コーディングエージェント向けAGENTS.mdの書き方
セットアップやテストのコマンド、ルール、禁止事項をまとめた短いAGENTS.mdを書き、Claude CodeとGemini CLIに読み込ませ、小さなタスクで動作を確かめる方法を説明します。
AGENTS.mdは、リポジトリのルートに置くシンプルなMarkdownファイルで、プロジェクトでの作業の進め方をコーディングエージェントに伝えます。どのコマンドを実行するか、コードがどこにあるか、何に手を触れてはいけないか、といった内容です。必須のセクションはありません。短く保ち、すべてのルールを確認できる形で書き、それぞれのエージェントが読み込んでいることを確かめてください。
この記事では、書く内容、テンプレート、Claude CodeとGemini CLIがファイルを見つける仕組み、簡単なテストを紹介します。ReunifiedのMonoでスマートフォンからエージェントを起動する場合も、手順は同じです。
1. ファイルに書く内容を決める
agents.mdのサイトでは、このファイルをエージェント向けのREADMEと呼んでいます。毎回のセッションで必要になる事実を書き、コードを読めばエージェントが分かることは省きます。
| AGENTS.mdに書く | 書かない |
|---|---|
| セットアップ、テスト、lintのコマンド | パスワード、APIキー、トークン |
| 主なコードの場所 | ファイルツリー全体や依存関係の一覧 |
| 一般的なやり方と異なる規約 | 長い手順（代わりにドキュメントへのリンクを書く） |
| 決して編集しないファイル、先に確認が必要な操作 | 個人的な好み（エージェントのユーザー単位のファイルを使う） |
モノレポでは、各パッケージの中にAGENTS.mdを追加できます。いちばん近いファイルが優先され、チャットで直接伝えた指示はそれよりも優先されます。
2. 短いテンプレートから始める
pnpmを使うTypeScriptのWebアプリ「tidy-recipes」の架空の例です。
# AGENTS.md
## Overview
TypeScript web app for saving recipes. Components live in src/components.
## Setup
- `pnpm install`
## Test and lint
- `pnpm test` and `pnpm lint`
## Code style
- TypeScript only. One component per file.
## Boundaries
- Never edit db/migrations/.
- Ask before adding a dependency.
## Before you finish
- Run `pnpm test` and `pnpm lint`.
- List the files you changed and the test results.書くのは、このリポジトリで実際に実行したことのあるコマンドだけにします。間違ったコマンドでも、エージェントはそのまま信じてしまいます。
3. 守ったかどうか確認できるルールを書く
よいルールなら、エージェントが従ったかどうかをあとで確認できます。
| あいまい | 具体的 |
|---|---|
| 変更をテストする | 作業を終える前にpnpm testとpnpm lintを実行する |
| ファイルを整理しておく | コンポーネントはsrc/componentsに置く |
| データベースは慎重に扱う | db/migrations/は決して編集しない |
| 作業をまとめる | 変更したファイルとテスト結果を一覧にする |
禁止事項は「決して〜しない」「先に確認する」という形のルールにして、1行に1つずつ書きます。
4. Claude CodeとGemini CLIに読み込ませる
agents.mdのサイトには、Codex、Gemini CLI、opencodeなど、この形式に対応するエージェントが載っていますが、先に設定が必要なものもあります。
最近のバージョンのClaude Codeは、標準では、作業ディレクトリやその上位にCLAUDE.md、.claude/CLAUDE.md、CLAUDE.local.mdのいずれもない場合にだけAGENTS.mdを読みます（メモリーのドキュメントを参照）。これらのファイルのどれかがある場合や、古いバージョンを使っている場合は、CLAUDE.mdからAGENTS.mdをインポートします。tidy-recipesのプロジェクトには以前からのCLAUDE.mdがあるので、先頭に次の行を追加し、Claude専用のメモはその下に残します。
@AGENTS.md
Prefer small commits.新しいセッションを始めて/contextを実行し、「Memory files」の下にCLAUDE.mdが表示されることを確認します。CLAUDE.mdがない場合は、代わりに/memoryがAGENTS.mdのパスを表示します。
Gemini CLIは、標準ではGEMINI.mdを読みます。AGENTS.mdを加えるには、プロジェクトの.gemini/settings.jsonに次の内容を書きます（GEMINI.mdのドキュメントを参照）。
{
"context": {
"fileName": ["AGENTS.md", "GEMINI.md"]
}
}新しいセッションを始めてから/memory showを実行し、何が読み込まれたかを確認します。ほかのエージェントについては、それぞれのドキュメントを確認してください。
5. 小さなタスクでファイルをテストする
新しいセッションで、エージェントに次のタスクを渡します。
まず、読み込んだプロジェクトのルールと、それぞれがどのファイルから来たかを一覧にして。次に、src/components/SaveButton.tsxのボタンの文言を「Save recipe」から「Save」に変えて。それ以外は何も変更しないで。
結果をファイルの内容と照らし合わせます。
- AGENTS.md（またはインポートを書いたCLAUDE.md）を挙げたか。
pnpm testとpnpm lintを実行し、結果を報告したか。- db/migrations/に手を付けず、依存関係を追加しなかったか。
- 変更したファイルを一覧にしたか。
編集内容はgit diffで自分でも確認します（AIによるコード変更の確認方法を参照）。エージェントがルールを挙げられない場合は、ファイルが読み込まれていない可能性が高いので、手順4に戻ります。ルールを挙げたのに守らなかった場合は、そのルールをもっと具体的にします。
6. 短く、最新の状態に保つ
Claude Codeのドキュメントでは、CLAUDE.mdを200行未満にすることを勧めています。長いファイルはコンテキストを多く使い、指示が守られにくくなるためです。AGENTS.mdも同じくらいを目安にしましょう。コンテキストがいっぱいになったときに何が起きるかは、コンテキストウィンドウのガイドで説明しています。
エージェントが同じ間違いを繰り返したらファイルを更新し、古くなったコマンドや矛盾するルールは削除します。ファイルはコミットし、その変更はコードと同じようにレビューします。
このファイルはエージェントへの案内であって、何かを強制するものではありません。操作を止めたいときは、エージェントの権限設定を使うか、そのリクエストを拒否します（ツール権限のガイドを参照）。
Monoでは、エージェントはパソコン上のプロジェクトの作業ディレクトリで起動し、そこでこれらのファイルを探します。AGENTS.md、CLAUDE.md、.gemini/settings.jsonはMonoのエディターで開けます。スマートフォンからも開くことができ、編集内容は自動で保存されます。ファイルを新しく作るには、エージェントに頼むか、プロジェクトのカードからターミナルを開きます。Monoはファイルの中身を確認せず、エージェントがどのファイルを読み込むかも変えません。Monoはまだ公開前ですが、ウェイトリストに登録できます。
