writing-agents-md

writing-agents-md

リポジトリのハンドブックではなく、小規模な指示インターフェースを設計します。まず重複と競合を取り除き、次に残った各ルールを適切な最小のスコープに配置します。強い制約を追加するのは、コストの大きい誤り、永続的なポリシー、または対象ホストでの評価によって実証された機能不足に限ります。

ワークフロー

1. タスクの範囲を定めます。 対象ホスト、ファイル、ディレクトリのスコープ、要求されたモード（create、update、rewrite、review）を特定します。レビューは、ユーザーが変更も求めている場合を除き、読み取り専用で行います。出力のみを求める依頼には従います。
2. 有効な指示チェーンを調べます。 編集前に、適用される祖先、対象、上書き、入れ子、インポート、パススコープの指示ファイルを特定します。ホストの検出方法や優先順位が結果に影響する場合は、host-semantics.md を読みます。
3. 権限の所在を確認します。 既存の指示ファイルを継続的に適用される契約として読み、その後、リポジトリのコード、設定、CI、ドキュメント、最近の根拠を調べて乖離がないか確認します。実装を観察した結果、古くなった実装に関する記述が誤りだと判明することはありますが、人間が定めた安全、リリース、コンプライアンス、運用のポリシーが自動的に上書きされるわけではありません。解決していない競合は、オーナーへの確認事項として明記します。
4. 候補をすべて振り分けます。 以下の振り分けインターフェースを使います。既存の指示チェーンをレビューまたは改訂する場合は、行ごとの監査のために checklist.md を読みます。
5. 選定した配置先のみを書き換えます。 依頼によって許可された配置先だけを編集し、その範囲外への移動を推奨する場合は報告したうえで、該当ファイルは変更せずに残します。唯一の情報源を維持し、具体的で検証可能な表現を使い、更新時には無関係で有効なルールを保持します。望ましい動作を肯定的に示し、禁止事項は実際のガードレールに限り、安全な代替手段と併記します。
6. 完了を確認します。 有効な指示チェーン全体を考慮し、競合を解決または報告して、変更したファイルを検証します。ユーザーが成果物のファイルのみを求めている場合を除き、移動や削除について説明します。

振り分けインターフェース

各ルールについて、次のアクションを1つ選びます。

• 保持 — このファイルのスコープ全体にわたって判断に影響し、簡潔、具体的、検証可能で、常時読み込むだけの価値があるほど安定している場合は、ここに残します。
• 範囲を狭める — サブツリーまたはファイルの種類にのみ必要な場合は、継続的なガイダンスを最も近い入れ子の AGENTS.md、入れ子の CLAUDE.md、またはパススコープのルールに移します。
• 委任 — 条件付き、参照が多い、または複数手順にわたる作業は、スキルまたはドキュメントに移します。エージェントが資料の存在と読み込む条件を知る必要がある場合に限り、短い参照を残します。
• 強制 — 決定的に検証できる要件は、コード、設定、テスト、CI、権限、またはフックに置きます。判断に影響する場合に限り、明白でない理由やフォールバックのみを指示に残します。
• 削除 — 重複、古い記述、汎用的なデフォルト、動作に影響しない記述、ディレクトリの案内、簡単にできる単一ファイルまたは単一コマンドの確認を取り除きます。
• 確認 — 権限の所在が不明な場合、特に安全、本番環境、リリース、法務、外部システムに関する未解決のルールは保持するか、未解決であることを明確に示します。

見つけやすさは根拠にはなりますが、自動的に削除する理由にはなりません。誤った選択の繰り返しや、コストの大きい調査を防げる場合は、短い標準コマンドやリポジトリの目的に関する記述を残してもかまいません。分岐の多い検証手順は、常時読み込むコンテキストを増やすのではなく、スキルに移します。

執筆基準

• 常時読み込まれるトークンの大半は、落とし穴、判断を変える慣例、安全な方法に充ててください。
• ルールの適用範囲を、そのルールが読み込まれる範囲に合わせてください。リポジトリ全体に適用されるルールが、リポジトリ外でも全般的に適用されるとは限りません。また、サブツリー全体に適用されるルールが、タスク固有とは限りません。
• 参照内容をコピーするよりも、対象となる資料と適用される条件の両方を示す参照先を優先してください。
• 例は任意の参考資料であり、機械的に模倣すべきルールではありません。振り分けの判断がなお曖昧な場合に限り、examples.md を読んでください。
• 常設の指示に読み込む価値がない場合は、ごく短いファイルにするか、ファイルを作成しないことを提案してください。ユーザーが作成を明示的に依頼した場合は、成果物を黙って省略せず、その結論を説明してください。

このインターフェースとモデルに応じたプルーニングの根拠については、principles.md を読んでください。