LLM Friendly Context

LLM-Friendly Context

目標は、下流が安定して実行できるようにすることである。次のエージェントが、何を読み、何をし、何をもって成功とし、いつ停止・エスカレーションするかを把握できる状態を目指す。

本スキルはLLM向け出力（プロンプト、ハンドオフ、生成物）の明確さを扱う。生成物の種類と、生成物固有のテンプレートまたはセクション契約は呼び出し元が渡す。本スキルは、渡された契約を後続エージェントが実行できる形にする。

中核ルール

• 肯定形で実行可能な指示を使う
• 次のエージェントが何をすべきかを述べる。
• 品質ポリシーは肯定的な基準に変換する。
• 例: 「文書化された互換ケース全体で、既存の公開API挙動を維持する」
• 禁止形を残すのは、それが不可逆な境界または出荷済みの契約を守る場合に限る。その場合は、守られる条件と許容されるアクションを併記する。

• 曖昧な指示を具体化する
• 主観的な語を、観察可能な条件・パス・コマンド・スキーマ・例・判断ルールに置き換える。
• 次のエージェントに判断を委ねてしまい、明確化が必要になりやすい語: appropriate、proper、related、existing behavior、optional、as needed、if needed、per convention、未解決の代替案、TBD、placeholder。

• 出力構造を指定する
• 必須のセクション・フィールド・表のカラム・JSONキー・チェックリスト項目を定義する。
• ハンドオフでは、生成した成果物のパスと、呼び出し側が確認すべき正確なステータスフィールドを含める。

• 必要なコンテキストを与える
• 目的・出典となる成果物・厳格な制約・合意済みの決定・未解決条件を含める。
• 大まかなモジュール名より、具体的なファイルパスとセクションヒントを優先する。
• 参照は、次のリンクがスコープ内の判断を変えうる間はたどる。既に決まっている内容を確認するだけになった時点で止める。

• 複雑な作業を検証可能なステップに分解する
• 目的が3つ以上、または逐次的な依存がある作業は、順序付きのステップに分割する。
• 各ステップには、完了を証明する根拠を示すチェックポイントを設ける。

• 不確実性を明示的に許可する
• 出典が欠落・矛盾・検証不能な場合は、その不確実性と必要なエスカレーションを述べる。
• ビジネス・プロダクト・セキュリティ・互換性に関する未知の決定は、解決に必要な入力とエスカレーション条件を付したブロッキングな未解決項目として記録する。
• ブロッキングな未解決項目は、成果物を問わず一貫した形式で書く: Unresolved: <必要な決定> — required input: <解決に必要な入力（必要なら確認先も）> — escalation: <次のエージェントが推測せず停止すべき条件>。

• 制約を比例的に保つ
• 曖昧さを減らす、または実在の要件を保つ制約のみを追加する。
• 対象アクション・コンテキスト・成功基準が既に明確な単純な下流タスクは、軽量なまま保つ。
• 記述されたサイズの期待 — minimal、数行、明示的な行数やファイル数の見積り — は、ファイル単位やステップ単位ではなく完成した差分全体に対する1つの予算として扱う。作業がそこに収まらない場合は、黙って超過せず超過分とその理由を報告する。

書き換えパターン

プロンプト・ハンドオフ・成果物を完成とみなす前に、以下の書き換えを適用する。

| 曖昧な形 | 書き換え後 |

|---|---|

| 未解決の選択として使われる optional | 必須・省略・特定条件下でのみ必須、のいずれか |

| 次のエージェントが選ばねばならない複数の代替案 | 選択した選択肢、または決定的な判断ルール |

| as needed / if needed | 発動条件と必要なアクション |

| per convention | 従うべきファイル・関数・テスト・文書化された規約 |

| related files | 具体的なパス・glob・サーチヒント |

| existing behavior | 維持すべき観察可能な挙動・出典ファイル・テスト・APIレスポンス・UI状態 |

| placeholder | 正確な暫定値/挙動・許容される依存・検証の期待値 |

| 必須情報のプレースホルダとして使われる TBD | required inputとescalation conditionを付したブロッキングな未解決項目（判明していればownerも） |

| appropriate / proper | 測定可能な基準またはチェックリスト |

ハンドオフチェックリスト

プロンプトや成果物を別のエージェントに渡す前に確認する:

• [ ] 対象アクションが明示されている。
• [ ] 必須の入力パスと出典成果物が名指しされている。
• [ ] 合意済みの決定と制約が、言い換えなしに一度だけ記載されている。
• [ ] 出力形式または期待されるステータスフィールドが指定されている。
• [ ] 成功基準が観察可能である。
• [ ] 曖昧な表現が書き換え済み、または未解決として明示されている。
• [ ] 記述されたサイズの期待が、完成した差分全体に対する1つの予算として表現され、超過を報告する条件が示されている。
• [ ] 次のエージェントが、明示的な選択・判断ルール・ブロッキングな未解決項目によって自身のスコープを完了できる。

生成物チェックリスト

生成ドキュメントを記述・確定する前に確認する:

• [ ] 各要件・主張・タスク・テストスケルトン・レビュー所見が、なぜ存在するかを辿れるだけの出典コンテキストを持つ。
• [ ] 実行可能な各指示が、対象・アクション・期待結果を名指ししている。
• [ ] 検証ステップが、何を実行/観察するか、どの結果が成功を証明するかを述べている。
• [ ] ある成果物が別の成果物から導出される場合、コピーした決定が文言と意味の両面で一貫している。
• [ ] 記述されたサイズの期待が、完成した成果物全体に対する1つの予算として表現され、超過を報告する条件が示されている。
• [ ] 下流作業が情報欠落でブロックされる場合、成果物が欠落している入力とエスカレーション条件を記録している。