shinpr LLM-Friendly Context
目標は、下流が安定して実行できるようにすることである。次のエージェントが、何を読み、何をし、何をもって成功とし、どの未解決の判断が結果を変えうるかを把握できる状態を目指す。
このスキルはLLM向け出力（プロンプト、ハンドオフ、生成物）の明確さを扱う。生成物の種類と、生成物固有のテンプレートまたは入力契約は呼び出し元が渡す。利用側が判断、実行、検証に使う情報だけを含める。利用側が値によって分岐する場合は、宣言された契約のフィールド名と値の意味を使用する。
中核ルール
肯定形で実行可能な指示を使う
- 次のエージェントが何をすべきかを述べる
- 品質ポリシーは肯定的な基準に変換する
- 例: 「文書化された互換ケース全体で、既存の公開APIの振る舞いを維持する」
- 禁止形を残すのは、それが不可逆な境界またはリリース済みの契約を守る場合に限る。その場合は、守る条件と許容されるアクションを併記する
曖昧な指示を具体化する
- 主観的な語を、観測可能な条件、パス、コマンド、スキーマ、例、判断ルールに置き換える
- 次のエージェントに判断を委ねる場合に明確化が必要になりやすい語:
appropriate、proper、related、existing behavior、optional、as needed、if needed、per convention、未解決の代替案、TBD、placeholder
出力構造を指定する
- 利用側が使うセクション、フィールド、表のカラム、JSONキー、チェックリスト項目を定義する
- ハンドオフでは、次の遷移を制御する場合に限り、生成した成果物のパスとステータスフィールドを含める
必要なコンテキストを与える
- 目的、出典となる成果物、厳格な制約、承認済みの判断、未解決条件を含める
- 大まかなモジュール名より、具体的なファイルパスとセクションヒントを優先する
- 参照は、スコープ内の判断、アクション、検証結果を変えうる間はたどる。次のリンクが既に決まった内容を確認するだけになった時点で止める
複雑な作業を検証可能なステップに分解する
- 目的が3つ以上、または逐次的な依存がある作業は、順序付きのステップに分割する
- 各ステップには、何が完了を証明するかを示すチェックポイントを設ける
不確実性を明示的に許可する
- 運用上の詳細が欠けている場合、未解決とみなす前に根拠となる成果物とリポジトリの代表的なエビデンスから解決する
- 残る不確実性を、それが成果または証明に与える影響とともに記録する。確認済みの境界内では可逆なリポジトリローカルの選択を行い、使用したエビデンスを残す
- 次のステップを妨げる不明点は、必要なエビデンスを具体的に示す。ユーザーに尋ねるのは、確認済みの成果、将来状態の要件、対象外をユーザーの選択なしには同時に維持できない場合、または不可逆な外部操作に承認が必要な場合に限る。証明だけを利用できない場合は、影響を受けない作業を完了し、検証できなかった内容と理由を正確に報告する
制約は必要な分にとどめる
- 曖昧さを減らす、または実在の要件を守る制約だけを追加する
- 対象アクション、コンテキスト、成功基準が既に明確な単純な下流タスクは、軽量なまま保つ
- 指定された分量の目安 —
minimal、数行、明示的な行数やファイル数の見積り — は、ファイル単位やステップ単位ではなく完成した差分全体に対する1つの上限として扱う。作業がそこに収まらない場合は、黙って超過せず超過分とその理由を報告する
書き換えパターン
プロンプト、ハンドオフ、成果物を完成とみなす前に、以下の書き換えを適用する。
| 曖昧な形 | 書き換え後 |
|---|---|
未解決の選択として使われる optional |
必須、不要、特定条件下でのみ必須、のいずれか |
| 次のエージェントが選ばなければならない複数の代替案 | 選択した選択肢、または決定可能な判断ルール |
as needed / if needed |
発動条件と必要なアクション |
per convention |
従うべきファイル、関数、テスト、文書化された規約 |
related files |
具体的なパス、glob、検索の手掛かり |
existing behavior |
維持すべき観測可能な振る舞い、出典ファイル、テスト、APIレスポンス、UI状態 |
placeholder |
正確な暫定値または振る舞い、許容される依存、検証の期待値 |
必須情報のプレースホルダとして使われる TBD |
それが変えうる判断と、必要なエビデンス。下流への影響がなければ省略する |
appropriate / proper |
測定可能な基準またはチェックリスト |
ハンドオフチェックリスト
プロンプトや成果物を別のエージェントに渡す前に確認する:
- 対象アクションが明示されている
- 必須の入力パス、出典となる成果物、判断に関係する事実が指定されている
- 承認済みの判断と制約が、別の表現で重複せず一度だけ記載されている
- 出力形式または期待されるステータスフィールドが指定されている
- 成功基準が観測可能である
- 曖昧な表現が書き換え済み、または未解決として明示されている
- 指定された分量の目安が、完成した差分全体に対する1つの上限として表現され、超過を報告する条件が示されている
- 次のエージェントが、渡された目的、出典、基準、エビデンスから自身のスコープを完了できるか、必要なエビデンスまたは正規のワークフロー停止条件を1つ正確に返せる
生成物チェックリスト
生成ドキュメントを記述または確定する前に確認する:
- 各要件、主張、タスク、テストスケルトン、レビュー所見が、なぜ存在するかを辿れるだけの出典コンテキストを持つ
- 実行可能な各指示に、対象、アクション、期待結果が明記されている
- 検証ステップが、何を実行または観測するか、どの結果が成功を証明するかを述べている
- ある成果物が別の成果物から導出される場合、コピーした判断が文言と意味の両面で一貫している
- 指定された分量の目安が、完成した成果物全体に対する1つの上限として表現され、超過を報告する条件が示されている
- 欠けている情報が、それによって影響を受ける判断または証明を記録している。作業を止めるエスカレーションとして扱うのは、確認済みの成果、将来状態の要件、対象外のどれを変更するかという選択、または不可逆な外部操作の承認だけである