PENGUINITIS - AGENTS.md入門

AGENTS.md についての入門ドキュメントです。公式サイトをもとにしています。

AGENTS.md とは

AGENTS.md は、AIコーディングエージェントにプロジェクトのコンテキストと指示を提供するための、シンプルでオープンなフォーマットです。

AGENTS.md は、エージェントのための README と言えます。README.md が「人間のためのドキュメント」であるのに対し、AGENTS.md は「エージェントのためのドキュメント」として設計されています。リポジトリのルートに配置する標準的な Markdown ファイルであり、多くのオープンソースプロジェクトで採用されています。

なぜ AGENTS.md なのか？

README.md との違い

README.md は、人間を対象として書かれ、プロジェクトの概要やクイックスタートなどを示すことを目的としており、極力簡潔にまとめられます。

一方、AGENTS.md は、AIコーディングエージェントを対象として書かれ、ビルド手順、テストコマンド、コード規約、エージェント向けの詳細コンテキストなどが示され、必要に応じて詳細に記述可能なものになっています。

AGENTS.md がもたらす利点

オープンフォーマットであることの意味

AGENTS.md は、特定の企業やツールに閉じたプロプライエタリな形式ではありません。誰でも自由に採用できるオープンなフォーマットです。名前からして、誰もが理解しやすいシンプルな名前が選ばれています。AGENTS.md は現在、Linux Foundation 内の Agentic AI Foundation によって管理・運営されています。

AGENTS.md は、Cursor や OpenCode、Pi など、多くのAIコーディングエージェントでサポートされています。異なるエージェント間で共通のフォーマットを使用できることが、AGENTS.md の最大の強みです。

AGENTS.md の書き方

ベースとなるテンプレート

# AGENTS.md

## セットアップコマンド
- 依存関係のインストール: `pnpm install`
- 開発サーバーの起動: `pnpm dev`
- テストの実行: `pnpm test`

## コードスタイル
- TypeScript strict mode を使用
- シングルクォート、セミコロン不要
- 可能であれば関数型パターンを使用

記載すべき内容（推奨セクション）

エージェントがプロジェクトを効果的に操作するために役立つセクションを記載します：

サンプル：モノレポの場合

# AGENTS.md

## 開発環境のヒント
- `ls` でスキャンする代わりに、`pnpm dlx turbo run where <project_name>` を使用して
  パッケージにジャンプできます。
- `pnpm install --filter <project_name>` を実行して、Vite、ESLint、TypeScript が
  認識できるようにワークスペースにパッケージを追加します。
- `pnpm create vite@latest <project_name> -- --template react-ts` で、
  TypeScript チェック済みの React + Vite パッケージを新規作成できます。
- ルートの package.json ではなく、各パッケージ内の package.json の name フィールドを
  確認して正しい名前を確認してください。

## テスト手順
- .github/workflows フォルダーにCIプランがあります。
- `pnpm turbo run test --filter <project_name>` で、
  そのパッケージに定義されたすべてのチェックを実行します。
- パッケージのルートからは `pnpm test` のみで実行できます。
  マージ前にはすべてのテストがパスしていることを確認してください。
- 特定のステップに集中するには、Vitest のパターンを追加します：
  `pnpm vitest run -t "<テスト名>"`。
- すべてのテストがパスするまで、テストエラーとタイプエラーを修正します。
- ファイルの移動やインポートの変更後は、
  `pnpm lint --filter <project_name>` を実行して ESLint と TypeScript のルールが
  依然として通ることを確認してください。
- 誰からも依頼されていなくても、変更したコードのテストを追加または更新します。

## PR手順
- タイトル形式: `[<パッケージ名>] <タイトル>`
- コミット前に常に `pnpm lint` と `pnpm test` を実行します。

実践的な使い方

1. リポジトリルートに AGENTS.md を作成する

最も基本的な使い方です。リポジトリのルートに AGENTS.md ファイルを作成するだけで、ほとんどのコーディングエージェントが自動的に認識します。最近のコーディングエージェントは、AGENTS.md の作成を自動で提案・生成してくれるものもあります。

2. 重要な情報を記載する

エージェントがプロジェクトを正しく理解し、操作するために必要な情報を記載します。

3. 追加の指示を書く

コミットメッセージの規約、プルリクエストの手順、セキュリティ上の注意点、大規模なデータセットの情報、デプロイの手順など、「新しいチームメイトに伝えるべきこと」はすべて記載します。

4. モノレポの場合：ネストされた AGENTS.md を使用する

大規模なモノレポでは、各パッケージ内に個別の AGENTS.md を配置できます。エージェントは自動的にディレクトリツリー内で最も近い AGENTS.md を読み取るため、各サブプロジェクトが独自の指示を提供できます。

よくある質問

必須のフィールドはありますか？

いいえ。AGENTS.md は標準的な Markdown です。見出しは自由に使え、エージェントは記載されたテキストをそのまま解析します。

指示が競合した場合、どうなりますか？

エージェントは AGENTS.md に書かれたテストコマンドを自動実行しますか？

はい。テストコマンドを記載しておくと、エージェントは関連するプログラマティックなチェックを実行し、タスク完了前に失敗を修正しようとします。

後から更新できますか？

もちろん。AGENTS.md は「生きているドキュメント」として扱ってください。プロジェクトの変化に合わせて随時更新します。

まとめ

AGENTS.md は、AIコーディングエージェント時代の「新しい標準」になりつつあります。

プロジェクトでAIコーディングエージェントを活用している場合、AGENTS.md の導入は小さな労力で大きな効果をもたらすでしょう。エージェントに「何を伝えるか」を明確にすることで、開発体験が格段に向上します。

AGENTS.md入門

はじめに