このページの目次

このページの目次

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. コマンド:セットアップ、実行、単一テスト、全体テスト、リンター、型チェック、ビルド、コード生成、全体検証の正確なコマンドを記載する。プロジェクトにない項目は省く。
  2. エンジニアリング標準:共有ガイドラインと、プロジェクト固有の例外。
  3. 構成:トップレベルのディレクトリごとに 1 行で、主要モジュールを示す。
  4. 境界:必ず行うこと、決して行わないこと、事前に確認すること。
  5. 確定した言語ポリシー:言語ポリシーを参照する。
  6. プロジェクト固有の規約:コードからは推測できない判断。
  7. 詳細リンク: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 も更新すること。

古い指示は、指示がないよりも悪い。エージェントはそれを疑わずに実行し、誰も求めていない変更を生み出す。