README は人間向け。エージェント向けの入口は、リポジトリ直下の AGENTS.md。
「テストコマンドは？」「dist/ は触るな」「git push はするな」。これをチャットのたびに書いてるなら、仕事はまだ始まってない。モデルを差し替える前に、同じリポジトリを開いたエージェントが最初に読む1枚を置け。
README と AGENTS.md は読者が違う
README はクローンした人がビルドして、issue を書いて、オンボーディングするための文書。バッジもスクショも、人間が読むなら歓迎。
AGENTS.md はエージェントが毎回コンテキストに載せる指示。短く、検証できることだけ書く。
スタイルガイド全文は要らない。ここに置くのはこのリポジトリ固有の約束だけ。
Cursor 公式は AGENTS.md を .cursor/rules のシンプルな代替と位置づけている。フロントマターなしの素の Markdown。メタデータも globs も要らない。まずはルートに1枚。
エージェント向けに書く基準は「次のセッションでも同じことを言いたくなるか」。
README のクローン手順や貢献ガイドを丸写しする必要はない。README は人が最初の1回読む。AGENTS.md はエージェントが毎回のセッションで読む。
同じファイルを兼用すると、バッジとスクリーンショットがコンテキストを食う。人が読む文書と、毎回載せる指示は分ける。
人が読む README に「エージェントはこう動け」と書き足しても、エージェントはそこを入口だと思わない。入口はファイル名で決まる。Cursor と Codex は AGENTS.md。Claude Code は CLAUDE.md。CLI の Cursor は両方読む。だから正本は1枚で、あとは入口を生やす。
Cursor が読む場所と、近いファイルが勝つ話
公式の Rules ドキュメントの要点はこれだけ。
- 置き場所はプロジェクトルート。サブディレクトリにも置ける
- ネストした AGENTS.md は、そのディレクトリとその配下を触るときに効く
- 親ディレクトリの指示と結合される。近いファイルの指示が優先される
- プレーン Markdown。フロントマターは不要
モノレポなら、ルートに全体の約束、frontend/ や backend/ にその領域だけの約束、という切り方が公式の想定。
project/
AGENTS.md # 全体
frontend/
AGENTS.md # フロント固有
components/
AGENTS.md # コンポーネント固有
backend/
AGENTS.md # バックエンド固有
結合して近い方が勝つ。ルートに全部を詰め込まなくていい。
親と結合されるので、ルートの指示は消えない。近いファイルが優先されるだけだ。フロントの約束をルートに全部書かない。
ルートには全体の禁止事項と検証の方針だけ書いて、具体コマンドは領域側に置く。近いファイルが勝つ、をそう使う。フロントのコンポーネント規約をルートに書いても、バックエンド作業のたびにコンテキストを食う。
公式のネストは、サブディレクトリのファイルがその配下に効いて、親と結合され、具体的な指示が優先される。ルートを消す話ではない。近いファイルが勝つ、は結合のあとに来る優先順位だ。
.cursor/rules に素の .md を置いても読まれない
ここ、よく間違える。
Cursor の Project Rules は .cursor/rules 配下の .mdc だ。
フロントマターで description、globs、alwaysApply を持つ。素の .md はそれが無いので無視される。
公式のディレクトリ例でも api-guidelines.md は Ignored と書いてある。
プレーン Markdown で済ませたいなら AGENTS.md。適用条件を細かく分けたいなら .mdc。どっちかを使う。
拡張子だけ変えたつもりで foo.md を rules に置いても、エージェントは見てない。
Project Rules の .mdc は残していい。AGENTS.md は代替であって、排他ではない。最初はルートの1枚で足りる。パスごとに適用を分けたくなったら .mdc の globs を足す。順番は「まず1枚、次に分割」。
公式の例では react-patterns.mdc は認識され、api-guidelines.md は無視される。拡張子とフロントマターの有無で決まる。チャットに書いていたテストの回し方と、生成物を触るな、リモートへ出すな、もルートの1枚へ移せ。
CLI でも同じファイルが効く
エディタだけじゃない。Cursor CLI の公式は、CLI もエディタと同じ rules を読むと書いてある。
加えて、プロジェクトルートの AGENTS.md と CLAUDE.md があれば、.cursor/rules と並べて適用する。
つまりルートの AGENTS.md 1枚は、Cursor の Agent にも CLI にも乗る。エディタ用と CLI 用でファイルを分ける必要はない。
エージェントをエディタで使う日も、CLI で回す日も、読むファイルは同じでいい。入口を二重に作らない。.mdc に手を出すのは、パスごとに適用を分けたくなってからでいい。
最初の1枚は、これくらいで足りる
最小は「どう検証するか」「触るな」「出すな」。
# AGENTS.md
## Commands
- テストは npm test。変更したら走らせて、落ちてるなら直す
- パッケージマネージャは npm。yarn や pnpm は使わない
## Don't touch
- `dist/` と `build/` は生成物。手で編集しない
- `.env` と `.env.*` は読まない、書き換えない、コミットしない
## Git
- `git push` しない。コミットも、ユーザーが明示したときだけ
検証コマンドは「このリポジトリではどれが正か」を書く。一般的なツールの使い方は書かない。生成物と秘密情報は触るな、リモートへ出すな。これだけで毎回のチャット前置きが消える。
長いスタイルガイドを貼らない。エージェントが毎回同じミスをする項目だけ足す。
公式の best practices も、500行未満、曖昧な案内を避ける、繰り返すミスを見てから足す、という側だ。最初から百科事典を書かない。
よくあるツールの使い方、リンタが既に見てるスタイル、めったに起きないエッジケースは書かない。公式の What to avoid と同じ方向だ。このリポジトリでエージェントが二度つまずいたことだけ足す。
ルールを3倍にしない
同じリポジトリを Codex と Claude Code でも開くなら、指示を3箇所にコピーしない。
Codex は AGENTS.md をネイティブに読む。公式どおり、作業前にファイルを発見して指示チェーンに載せる。ルートの AGENTS.md はそのまま Codex の入口になる。
Codex 側もリポジトリの AGENTS.md を作業前に読む。ルートから今いるディレクトリまで辿って結合し、近いファイルが後から載る。優先度の感覚は Cursor のネストと近い。
個人の好みはホームディレクトリ側、チームの約束はリポジトリ側、と分ける。リポジトリの正本を増やさない。
Claude Code は違う。公式は Claude Code reads CLAUDE.md, not AGENTS.md と明言している。同じ内容を二重管理しないために、CLAUDE.md から import する。
@AGENTS.md
これ1行。Claude はセッション開始時に展開して読む。
Claude 固有の指示があるなら、その下に足せばいい。シンボリックリンクでもつながるが、Windows では管理者権限か Developer Mode が要るので、公式も import を推奨している。
Cursor CLI はルートの CLAUDE.md も読むので、この1行 import があっても害はない。中身の正本は AGENTS.md のまま。
import はコードフェンスの外に書く。バッククォートで囲むとただの文字扱いになる。正本を AGENTS.md に置いて、CLAUDE.md は入口だけにする。ここをコピーし始めると、また3倍に戻る。
ステアリングであって、拒否ではない
空のリポジトリに Cloud Agent を連打しても入口が無い作業は入口が無い。AGENTS.md はコンテキストに載る案内で、有害な操作を止めるハードブロックではない。拒否は hooks と permissions の層。
次にやること
- ルートに上記の最小 AGENTS.md を置いてコミットする。チャットに書いていた検証方法と触るなを移す。
- 規約が本当に違うディレクトリにだけ、ネストした AGENTS.md を足す。ルートのコピペはしない。
- Claude Code を使うなら、ルート CLAUDE.md に @AGENTS.md の1行だけ置く。Codex は同じ AGENTS.md をそのまま読む。
- .cursor/rules に素の .md が残ってないか確認する。細かい適用条件が要るものだけ .mdc に移し、拒否したい操作は hooks と permissions に任せる。
入口は1枚。増やすのは、エージェントが同じ場所で二度つまずいてから。
検証の正と触るなとリモートへ出すなは最初の一枚に書いてコミットしチームの約束として残しておく。