AGENTS.md の執筆
AGENTS.md はリポジトリにおける AI エージェントの入口であり、コードを書く前に読み込む作業コンテキストである。エージェントツールはセッション開始時にこれを読み込み、保持できるコンテキスト量にも上限があるため、各行には作業に必要な内容だけを記載する。
テンプレート:project-agents.template.md
必須要件
すべてのプロジェクトは、リポジトリのルートに AGENTS.md を 1 つ置くこと。
正式なファイル名は AGENTS.md である。同じルールを CLAUDE.md などの互換性のあるファイル名に複製しないこと。指示ファイルを複製すると内容が食い違い、コンテキスト予算を二重に消費する。
適切なファイルへの振り分け
指針は種類に応じて適切な場所に置くこと。
| 内容 | 記述先 |
|---|---|
| 常に適用するコマンド、規約、境界 | AGENTS.md |
| プロダクトの背景、導入説明、スクリーンショット | README.md |
| 開発ワークフローとツールチェーンの詳細 | DEVELOPMENT.md |
| プルリクエスト、レビュー、検証の要件 | CONTRIBUTING.md |
| アーキテクチャの不変条件 | ARCHITECTURE.md |
| 特定のワークフローにだけ必要な手順 | 別ドキュメントまたはエージェントスキル(リンクを付けて参照) |
| エージェントツールの設定、既定モデル、自律度 | 各ツールの設定ファイル |
運用手順書や長い参照ドキュメント、個別タスクのメモを AGENTS.md に貼り付けないこと。信頼できる唯一の情報源にリンクすること。
構成
冒頭に、プロジェクトの目的と対象を 1 文で示すこと。その後は、エージェントが必要とする順に、テンプレートに沿って節を並べること。
- コマンド:セットアップ、実行、単一テスト、全体テスト、リンター、型チェック、ビルド、コード生成、全体検証の正確なコマンドを記載する。プロジェクトにない項目は省く。
- エンジニアリング標準:共有ガイドラインと、プロジェクト固有の例外。
- 構成:トップレベルのディレクトリごとに 1 行で、主要モジュールを示す。
- 境界:必ず行うこと、決して行わないこと、事前に確認すること。
- 確定した言語ポリシー:言語ポリシーを参照する。
- プロジェクト固有の規約:コードからは推測できない判断。
- 詳細リンク:
DEVELOPMENT.md、CONTRIBUTING.md、ARCHITECTURE.mdへのリンク。
コマンドを最初に置くのは、エージェントが最初の 1 分で必要とするためである。対象を絞った軽いコマンド(単一テストファイルの実行など)と、全体検証のコマンド(コミット前の mise run check)の両方を記載し、小さな変更のたびに最も重いコマンドを実行させないようにする。
検証可能なルール
すべてのルールは、エージェントが実行でき、レビュアーが確認できる行動として示すこと。コマンド、パス、条件を具体的に記すこと。
検証可能な例:
- `src/auth/` 配下を変更したら `mise run test -- src/auth/token.test.ts` を実行する。
- `src/generated/` 配下は手で編集しない。`mise run codegen` で再生成する。
- 依存関係の追加や `ARCHITECTURE.md` の不変条件の変更は、事前に確認する。
検証できず、役に立たない例:
- 認証コードは慎重に扱う。
- すべてが動くことを確認する。
- ベストプラクティスに従う。
ネストしたファイル
まずルートに 1 ファイルだけ置くこと。ネストした AGENTS.md を追加するのは、そのディレクトリツリーに実質的な違いがある場合だけとする。
- 別のパッケージマネージャー、テストランナー、ランタイムを使用する場合。
- 手で編集せず、再生成する必要がある生成コードを含む場合。
- マイグレーションやデプロイなど、追加の承認が必要な場合。
- 他の場所には適用されない UI やデザインシステムのルールがある場合。
ネストしたファイルには固有の差分だけを記載し、それ以外はルートに委ねること。ルートのルールをネストしたファイルで繰り返してはならない。
ファイルサイズ
このファイルはタスクのたびに読み込まれるため、長くなるほど毎回コンテキストを消費する。
- 最も重要なルールを先頭に置く。
- 詳細ドキュメントは複製せず、リンクで案内する。
- 文章での注意書きより自動チェックを優先する。リンター、prek、CI がすでに強制しているルールは重ねて書かない。
- サブシステム固有の指針はルートに書き足さず、サブディレクトリのネストしたファイルへ移す。
ルートファイルは一度で読み通せる長さに保つこと。長くなりすぎたら、詳細をリンク先へ移し、ツールで強制できる記述を削る。
記載しない内容
- シークレット、トークン、内部ホスト名。
- リポジトリ内にすでに存在するドキュメントの複製。
- 網羅的なディレクトリ一覧。次のリファクタリングですぐに古くなる。
- Issue やプルリクエストに記載すべき一時的なタスクメモ。
- 検証を一律に省略させる指示。
最新状態の維持
コマンド、構成、境界、取り決めを変更するときは、同じ変更で AGENTS.md も更新すること。
古い指示は、指示がないよりも悪い。エージェントはそれを疑わずに実行し、誰も求めていない変更を生み出す。