AGENTS.md は、コーディングエージェントにリポジトリ内での作業方法を伝える
ファイルです。セッションのたびにコンテキストへ読み込まれるため、追加した
一行一行がすべてのタスクでコストになり、実際の依頼とエージェントの注意を
奪い合うことになります。
この事実だけで、以下の助言のほとんどを説明できます。
調べても分からないことだけを書く
エージェントがリポジトリを見れば分かることは、書き残さないでください。 ディレクトリ構成、使用中のフレームワーク、テストファイルの命名規則は、どれも リポジトリから確認できるため、繰り返し説明する必要はありません。
見ただけでは分からないのは、意図と制約です。
- テストを実行するコマンド。特に自明でない場合
- コード全体にはまだ一貫して反映されていない規約
- バグに見えても、意図的にそうしているもの
- 編集してはいけないディレクトリと、その理由
最後まで読める短さに保つ
およそ百行を超えると、ファイルは誰にも読まれない文書のようになり始めます。 180 行目に埋もれた指示は、残りの内容すべてと注意を奪い合うため、行動を確実に 変えることができません。
ファイルがすでに長くなっているなら、「どうすればエージェントに従わせられる か」よりも、「この中で実際に結果を変えた行はどれか」と問うほうが有益です。
コマンドを具体的に書く
曖昧な指示からは、曖昧な行動しか生まれません。次の二つを比べてください。
Run the tests before committing.一方、次のように具体的に書けます。
Run `pnpm test -- --run` before committing. It takes about 40 seconds.
Do not run `pnpm test` without `--run`; it starts watch mode and hangs.後者は、具体的で繰り返し起きる失敗を防ぎます。前者は心構えを述べているだけ です。
ルールだけでなく理由も書く
理由が添えられたルールは、未知の状況にも対応できます。禁止事項だけではそうは
いきません。「src/generated/ を編集しないでください」だけでは、直接直す
ほうが便利に見えた時に例外を作りたくなります。「src/generated/ を編集しない
でください。pnpm codegen で上書きされ、変更が消えるためです」なら、その
余地はありません。
機能しなくなったら見直す
このファイルも時間とともに劣化するものとして扱ってください。エージェントが 望ましくない行動を繰り返すなら、それはモデルだけでなくファイルについての 手掛かりです。必要な指示が欠けているか、既存の指示が、もう重要でない三百行に 埋もれているかのどちらかです。