writing-agents-md

エージェント向け指示の作成

AGENTS.md／CLAUDE.mdには、周辺のコードやツールからエージェントが確実に推測できない、プロジェクトの決定事項に絞って記載してください。指示の読み込み方はハーネスによって異なるため、コンテキストのコストを見積もる前に、どのルートファイルとネストされたファイルが適用されるかを確認してください。

残す、移動する、または削除する

• 自明でないコマンド、コストの高い落とし穴、ドメイン用語、プロジェクト固有の所有権や互換性に関する決定事項は残してください。
• ルールは、それを必要とする最も狭いサブツリーまたは必要なときに使うスキルに移してください。長い根拠やインシデントの証拠は、埋め込むのではなくリンクしてください。
• 一般的なエンジニアリングの助言、重複するルール、古くなったモデルの固定指定、修辞的な強調、固定された応答手順、ハーネスやツールチェーンがすでに担っている手順は削除してください。
• ルールには適用される条件を明記してください。スキルが利用可能だからといって、すべてのタスクで必須にする必要はありません。具体的な安全上およびプロダクト上の不変条件を維持しつつ、その手順の適用範囲を絞ってください。
• 繰り返し行うワークフローでは、既存の権限を具体化してください。エージェントが自律的に完了してよい作業、安全に実行できる条件、観測可能な停止条件、承認が必要なアクションを明記してください。すでに許可された作業を、その結果が出る前に中断するレビュー待ちは削除してください。

作業

1. 関連する指示、現在のリポジトリ上の取り決め、ユーザーの決定事項を確認してください。方針を削除する前に最近の変更を確認し、過去の証拠は有効なルールと分けてください。
2. ルールを懸念事項ごとに確認し、残す、書き換える、移動する、または削除してください。方針に重要な変更や移動があれば、簡潔な概要に記録してください。依頼がない限り、行ごとの判定を公開する表は不要です。
3. ユーザーの現在の方針とリポジトリの正式な方針に基づいて矛盾を解消してください。結論に影響し、かつ既定の責任者が決まっていない場合に限り、質問してください。
4. 正式な管理ファイルを編集し、参照先を更新してください。シンボリックリンクとツールが生成するブロックを維持し、乖離する並行コピーは避けてください。
5. 重要な不変条件と実際のコマンドに引き続きアクセスできること、ネストされた指示に矛盾がないこと、削除したルールがスキルやメモリからひそかに再導入されていないことを確認してください。リンクと変更された動作を確認し、文面だけの編集では文言を固定するテストは不要です。

短く具体的なルールを使い、コストの高い違反を強調するときに限って強調表現を使ってください。曖昧さを実際に防ぐ場合に、コマンドや例を記載してください。行数だけを減らしたり、参照先に常時必要な全文を移したりするのではなく、代表的なタスクで読み込まれる資料全体を最適化してください。

依頼された範囲について、各ルールの明確な管理者が一つに定まり、方針の矛盾が残らず、検証が適切な規模で行われたら完了です。定期的な監査手順を新たに設けず、変更内容と残る制約を報告してください。