セマンティックスペックライター は何をしますか？
実装エージェントがこのスキルを読み込まずに使用できる.plan.ctxおよび.spec.ctxファイルを生成します。
モード
- 新規ドキュメント: リクエストと検証済みのリポジトリ情報から、直接最終的なセマンティック成果物を記述します。最初に散文的なドラフトを作成しないでください。
- 既存ドキュメント: リクエストに応じてのみ変換し、ソースの意味と識別子を保持します。最終成果物はソースより短くする必要があります。
- ハンドオフまたは再利用: 別のエージェントまたは後続のターンによる独立した実行のために最適化します。
- リポジトリ実行パケット: ユーザーがコーディングハンドオフを希望し、コードベースが利用可能な場合、references/execution-packets.mdを参照してください。パケットを作成する前に、最小限の読み取り/編集ルートを具体化します。
変換によって1回限りの実装の合計トークンが節約されると主張しないでください。これは作成ステップを追加します。その経済性は、より小さな再利用可能なコンテキストと、実装の曖昧さの低減に由来します。
目標
文字数だけではなく、実装ループ全体を最適化します:
- すべての動作、制約、エッジケース、および正確な識別子を保持する
- ナラティブ、繰り返し、装飾的なメタデータ、および汎用的なアドバイスを削除する
- 要件から編集、検証への最短の信頼できるパスを公開する
- 解釈を必要とする略記よりも直接的な言語を優先する
より小さなファイルは、正しく実行するのがより速いままである場合にのみ有用です。既存のドキュメントを変換する場合は、記述する前にコンパクトな構造を計画し、ソースを拡張しないようにしてください。ファイルサイズだけを追求するために、ツールループや繰り返しの書き直しを追加しないでください。
トークン規律
- 欠落した事実にターゲットを絞ったルックアップが必要でない限り、提供された各ソースを1回だけ読み取ります。
- スコープ、インターフェース、および検証を具体化するために必要なファイルのみを検査します。
- 1つの最終成果物を記述します。最初の記述で短くします。変換の場合は、このスキルディレクトリから
scripts/check_conversion.py SOURCE OUTPUTを1回実行します。ターゲットトークナイザーが既知でtiktokenが利用可能な場合は、--encoding NAMEを渡します。チェックが失敗した場合は、冗長性を1回削除してもう1度実行します。サイズ追求ループを続けないでください。リクエストがない限り、アウトライン、ドラフト、変換ノート、サイズレポート、説明を出力しないでください。 - 実装エージェントが検索なしで正確なターゲットファイルから取得できるリポジトリ情報をコピーしないでください。間違った編集や余分な発見を防ぐ情報を含めてください。
- 汎用的な実装アドバイスよりも、正確なパスと1つの実行可能な検証コマンドを優先してください。
- 実行パケットの場合、ダウンストリームの発見を排除したり、間違った編集を防いだりする事実にのみ作成労力を費やしてください。パケットをリポジトリのダンプにしないでください。
- 実行パケットに、リファレンスからの標準的な有界ダウンストリームループ（1つのルーティングされた読み取り、1つの実装パス、1つの宣言された検証、成功時に停止）を提供します。拡張には、具体的な矛盾または失敗が必要です。
フォーマット
planまたはspecで始めます。- プロジェクトに別の規則がない限り、計画には
.plan.ctxを、仕様には.spec.ctxを使用します。 - 明白なローカルブロック名を使用します。これらはラベルであり、予約された言語キーワードではありません。
- 情報を運ぶブロックのみを含めます。空のセクションは出力しないでください。
- ターゲット、スコープ、および契約情報を、別々のブロックが同じ情報を繰り返す場合は結合します。
- ファイルパス、シンボル、APIルート、フィールド、テーブル、環境変数、コマンド、ステータス、ロール、エラーテキストを正確に保持します。
- フィールドの所有権とネストを正確に保持します。フィールド表記を実装言語に合わせます: Python JSON/マップには
event["payment_id"]を使用し、event.payment_idは使用しません。ソースで定義されていないdata、payload、またはその他のラッパーを決して発明しないでください。 .ctxをプレーンテキストとして扱い、Markdownとしては扱いません。通常の識別子をバックティック、太字、またはその他のプレゼンテーションマークアップで囲まないでください。verifyの下の実行可能コマンドにのみバックティックを使用します。- 実際の繰り返しを排除する場合にのみ、ローカル用語を定義します。説明的な用語を優先し、1文字のエイリアスや発明された表記法は避けてください。
- 別のアイテムがそれらを参照する場合にのみ、IDを追加します。
x=true、x in [a,b]、condition -> resultなどの使い慣れた表現を使用します。隠された構文に依存しないでください。- 構造化フィールドが重要なニュアンスを失う場合にのみ、短い
#コメントを使用します。 - 並列バリデーション、出力フィールド、および正確なエラーを、同じ文フレームを繰り返す代わりに、1つのコンパクトなマッピングの下にグループ化します。
- フィールドの所有権が確立された後は、バリデーションマップとエラーマップで、完全な所有者パスを繰り返す代わりに、短く明確なラベルを使用します。
- エラーマップでは、ブロックに繰り返される文法を任せます。すべての行で
invalid owner.field -> ErrorTypeを繰り返す代わりに、field: condition | ErrorType "exact message"を優先します。 - 1行に1つの独立してテスト可能なルールを維持します。共有マッピングは、その文法が一貫している場合、関連するフィールドケースを保持してもかまいません。
A*IDはacceptanceの下で1回だけ使用します。同意IDをルールIDまたはタスクIDとして再利用しないでください。
グラウンディング
コードベースが利用可能な場合は、記述する前に調査します。既知の編集範囲、既存のインターフェース、制約、および実行可能な検証コマンドを取得します。verifyは、正確なコマンドまたは既存の名前付きチェックにのみ含めます。検証シナリオを発明しないでください。ファイル名やアーキテクチャを推測しないでください。
不明な決定はopen_questionsに属します。不明な点がない場合は、そのブロックを省略します。
情報の順序
実装エージェントが必要とする順序で情報を配置します。関連する部分のみを使用します:
- 目標またはターゲット（既知の場合は正確な編集範囲を含む）
- ターゲットによってまだ述べられていない契約
- ルール、不変条件、状態、またはフロー
- 依存関係が重要となる場合の順序付けられた作業
- 検証コマンドと観測可能な同意
- 未解決の質問
正確な範囲と検証は、通常、攻撃的な散文の圧縮よりもエージェントの作業を節約します。
圧縮ルール
- 各事実を1回述べます。
- 重複する要件をマージします。
- その内容が別の行ですでに伝達されている場合は、ブロックを省略します。
- 同意は、散文を言い換える代わりに、既存のルール、契約、および検証IDを参照します。
- 参照されたブロックがすでに観測可能な動作を述べている場合にのみ、同意を参照として保持します。
- 実装の決定を変更する場合にのみ、理由を保持します。
improve、support、handle、optimize、fixなどのあいまいな動詞を、観測可能な結果に置き換えます。- 稀ではあるが結果的なエッジケースを保持します。ファイルを短くするために決して削除しないでください。
- 単語数を減らすためだけに、通常の要件を式としてエンコードしないでください。
- 正しく実行するのがより簡単な場合は、長い散文の説明よりも、ソースから導出された正確な整数式を優先します。
例
実装仕様:
spec
target: [src/payments.ts,tests/payments.test.ts] :: Idempotency-KeyによりPOST /paymentsをべき等にする
keep: レスポンススキーマ、認証動作
rules:
R1: キーのスコープはuser_id
R2: 同じユーザー + 同じキー + 同じボディ -> 元のステータスとボディを再生
R3: 成功を返す前に結果を永続化
errors:
E1: Idempotency-Keyがない -> 400 idempotency_key_required
E2: 同じキー + 異なるボディ -> 409 idempotency_conflict
verify:
V1: `pnpm test tests/payments.test.ts`
acceptance:
A1: R1,R2,R3,E1,E2 -> V1
並列バリデーションマップ:
validation:
retries: int>=0 | ValueError "retries must be non-negative"
timeout: int>0 | ValueError "timeout must be positive"
実装計画:
plan
goal: APIの動作を変更せずにセッションストレージをメモリからRedisに移行する
facts:
現在のストア: src/session/memory.ts
コントラクトテスト: tests/session.contract.test.ts
tasks:
T1: 既存のSessionStoreインターフェースの背後にRedisアダプターを追加する
T2: メモリとRedisアダプターに対してコントラクトテストを実行する
T3: T2が合格したらコンポジションルートを切り替える
verify:
V1: `pnpm test tests/session.contract.test.ts`
品質ゲート
終了する前に、以下を確認します:
- 新しい実装エージェントが、このスキルや暗黙のコンテキストなしで行動できること
- すべての行がスコープ、動作、実装順序、または検証を変更すること
- 要件が重複しておらず、未定義の省略形に置き換えられていないこと
- 既知のファイル、インターフェース、およびコマンドが正確であること
- 同意が観測可能で、述べられた契約にトレースできること
- すべてのフィールドが依然としてソースと同じ所有者とネストを持っていること
- 冗長性を排除することによって結果が短くなっており、意味を不明瞭にすることによってではないこと
最初にセマンティックドキュメントを出力します。実装を実質的に妨げる未解決の決定についてのみ、別途メモを追加します。