先に要点
AIコーディングツールを使い始めると、AGENTS.md を置くとよい、CLAUDE.md を書く、Cursor Rules を作る、memory を使う といった話が一気に出てきます。
でも実際には、これらは全部同じものではありません。
雑に言うと、毎回その場で伝える話 と プロジェクトに常設する話 と 条件つきで適用したい話 と 個人の繰り返しの癖 が混ざりやすいです。
そこが混ざると、AIが守ってほしい前提を外したり、逆に細かすぎるルールで毎回の作業が重くなったりします。
既にある AIコーディングで使うmdファイルとは？AGENTS.md・CLAUDE.md・指示書の役割を整理 が mdファイルそのもの の記事だとしたら、今回は 何をどこに置くべきか に寄せます。
まず結論: 設定すべきものは4層で考える
最初に全体像を固定すると、整理しやすくなります。
| 置き場 | 向いている内容 | 例 |
|---|---|---|
| 毎回のプロンプト | 今回だけの目的、優先順位、締切、判断軸 | `今日は調査だけ` `本番反映はしない` |
| mdファイル | プロジェクト概要、ディレクトリ構成、開発コマンド、危険箇所 | AGENTS.md、CLAUDE.md |
| rules | 特定ファイルや条件でだけ強く効かせたい指示 | Cursor の Project Rules、GitHub Copilot の `.instructions.md` |
| memory | 継続的に使う個人の好み、繰り返しの作法 | 説明は短め、テストを最後にまとめる、など |
この4つは、全部を同じ箱に入れるのではなく、役割を分ける方がうまく回ります。
mdファイルは「プロジェクトの前提」を置く
mdファイルに向いているのは、毎回同じ説明をしたくないプロジェクト前提です。
たとえば次のようなものです。
OpenAI の Codex 公式ドキュメントでは、Codex は作業前に AGENTS.md を読み、グローバル指示とプロジェクト配下の指示をレイヤーとして扱うと説明されています。
Anthropic の Claude Code 公式ドキュメントでも、CLAUDE.md を project memory として使い、チーム共有の前提を置く形が案内されています。
つまり md ファイルは、今回だけの指示 ではなく このプロジェクトではだいたい毎回必要になる前提 を置く場所です。
rulesは「条件つきで強く効かせたい指示」を置く
Rules は md ファイルより細かく、適用条件を持たせやすいのが特徴です。
たとえば次のような場面です。
app/Payments/**に入ったら決済系の手順を強く出したい*.sqlを触るときだけ migration と rollback の確認を入れたい- フロントエンド配下だけ React / UI の流儀を足したい
- インフラ配下では destroy 系コマンドに慎重さを要求したい
Cursor の公式ドキュメントでは、Rules は reusable で scoped な system-level instructions とされていて、Project Rules、User Rules、AGENTS.md が別の仕組みとして整理されています。
GitHub Copilot でも .github/instructions/*.instructions.md のように、パスごとの custom instructions を分けられます。
ここで大事なのは、rules は「全部の作業に毎回読ませる長文メモ」ではない ということです。
条件つきで効かせたいものを切り出すから意味があります。
memoryは「繰り返し出る個人の好み」を持たせる
Memory は、リポジトリの仕様書よりも その人やそのチームが繰り返し使う癖 に向いています。
たとえばこういうものです。
- 説明は冗長にしすぎない
- 先に結論を出す
- テストは最後にまとめて報告する
- 英語コメントより日本語コメントを優先したい
- コマンド実行前に一言状況を共有してほしい
Claude Code の memory ドキュメントでは、enterprise policy、project memory、user memory など複数の層が案内されています。
OpenAI Codex 側でも features.memories や memories.use_memories などの設定があり、メモリ機能そのものを有効化するか、将来セッションへ注入するかを切り替えられます。
ただし memory は万能ではありません。
実務では、プロジェクト固有の事実 まで memory に背負わせるより、md ファイルや rules に置いた方が安定します。
毎回のプロンプトでしか伝えにくいこともある
ここまで読むと、全部ファイルに書けばいいのでは と思いやすいですが、そうでもありません。
毎回のプロンプトで伝える方がよいものもあります。
- 今回は調査だけで実装しない
- 今日中に公開したい
- リスクが高いので先に差分方針だけ出したい
- A案よりB案を優先したい
- 今回は既存UIの見た目を変えたくない
こういうものは、プロジェクト全体の恒久ルールではなく、その時の仕事の条件です。
md ファイルや memory に入れると、次の unrelated な作業まで引きずりやすくなります。
ツールごとに何が違うのか
名前が似ていても、読み方や役割はツールごとに違います。
| ツール | 主な置き場 | 見方のポイント |
|---|---|---|
| Codex | `AGENTS.md`、`AGENTS.override.md`、`~/.codex/config.toml` | ディレクトリをたどって instruction chain を作る。fallback filenames や byte 上限も設定できる |
| Claude Code | CLAUDE.md、user memory、enterprise policy | project memory と user memory を分けやすい。`/memory` で読まれているファイル確認もできる |
| Cursor | Project Rules、User Rules、`AGENTS.md` | `AGENTS.md` はシンプルな代替。条件つきの運用は Rules の方が向く |
| GitHub Copilot | `.github/copilot-instructions.md`、`.github/instructions/*.instructions.md`、`AGENTS.md` | repo-wide と path-specific を分けられる。複数指示が合成される前提で書く必要がある |
この違いを無視して、うちは AGENTS.md を置いたから全部のツールが同じように読むはず と考えるとズレやすいです。
そのへんの読み込み差分や、書いたのに効かない ときの直し方は AIがルールのmdファイルを無視する原因は？AGENTS.md・CLAUDE.md・Rulesの対応策 もつながります。
何をどこに書くべきか
実務で迷いやすいので、よくある項目を置き場ごとに分けるとこうです。
| 内容 | 向いている置き場 |
|---|---|
| このリポジトリは何のサービスか | mdファイル |
| テストコマンド、起動コマンド、デプロイ手順の入口 | mdファイル |
| 特定ディレクトリだけの実装ルール | rules |
| SQLや決済系だけで強く出したい注意 | rules |
| 説明の長さ、話し方、報告スタイル | memory |
| 今日は修正より原因調査を優先する | 毎回のプロンプト |
| 今回は本番反映しない | 毎回のプロンプト |
この切り分けができるだけで、設定がかなり見通しよくなります。
よくある失敗
1. 何でも1ファイルに詰める
長い1ファイルに全部入れると、読みにくいだけでなく、ツール側の読み込み上限や遵守率の問題が出やすくなります。
Codex 公式でも project_doc_max_bytes の上限や、必要なら分割する考え方が案内されています。
2. プロジェクト固有の話を memory に入れすぎる
Memory は継続的な好みに向く一方、特定リポジトリだけの事情を持たせすぎると、別のプロジェクトへ漏れやすくなります。
3. rules を増やしすぎて競合させる
repo-wide の指示、path-specific の指示、agent instructions が多すぎると、どれが効いているか分かりにくくなります。
GitHub Copilot の公式ドキュメントでも、複数 instructions が合わさる前提で、競合を避けるべきだと案内されています。
4. 秘密情報や環境差分を雑に置く
APIキー、管理者URL、個人情報、暫定トークンのようなものは、AI向け設定の置き場に安易に書かない方が安全です。
設定の目的は 前提共有 であって、秘密の保管庫ではありません。
最初に入れるならこれで十分
最初から大げさに作る必要はありません。
まずは次の3つくらいで十分です。
- プロジェクトルートの md ファイルに、概要・主要コマンド・危険箇所を書く
- 条件つきで強く効かせたい部分だけ rules に切り出す
- 自分の説明スタイルや報告の好みだけ memory に持たせる
この3つが分かれているだけで、毎回の長い説明はかなり減ります。
AIコーディングルール設定のよくある質問
Q. .md ファイル、rules、memory はどう違いますか？
A. .md(CLAUDE.md、AGENTS.md など)はプロジェクト全体の前提、rules(.cursor/rules、.cursorrules)は条件付き指示、memory は個人の継続好み。役割を分けて配置するのが現代的。
Q. CLAUDE.md は何文字くらいが適切？
A. 短いほど良い。1000-3000 文字程度。長すぎると AI が読み飛ばし、重要ルールが埋没。必須ルールのみ を厳選し、詳細は別ファイルへリンクする運用が定番。
Q. ルールが守られないとき？
A. 1) 重要ルールを先頭に再配置、2) 短く言い切る形に書き直し、3) 必須、禁止 のような強い語を使う、4) Pre-commit hook でコード側でも検証、で対処。プロンプトのみで守らせる は完全保証されません。
Q. Cursor、Claude Code、Codex で同じファイルを使えますか？
A. ファイル名が異なります。CLAUDE.md(Claude Code)、.cursor/rules/*.md(Cursor)、AGENTS.md(Codex)、copilot-instructions.md(GitHub Copilot)、と各ツール用に分けて配置するのが現実的。
Q. チームで共有する設定は？
A. Git にコミットして共有。.gitignore に含めない、PR レビューで設定変更も承認、定期的な見直し、です。個人特有の好み は memory(リポジトリ外)に置きます。
Q. memory にはどんな内容を入れる？
A. 説明スタイル(関西弁、英語混じり、丁寧語、簡潔)、報告の好み(箇条書き、表、まとめ)、好む技術スタック、苦手な分野、です。プロジェクト固有でなく、個人共通の好み。
Q. AI が古いルールを引きずる時は？
A. プロジェクトのルール更新を明示、新しいセッション開始、CLAUDE.md の更新理由を明記、明確な変更点を会話で伝える、で対処。AI は前バージョンの記憶を持ち続けることがあります。
まとめ
AIコーディングで設定すべきものは、mdファイルを作ること そのものではありません。
本当に大事なのは、何をどこに置くとツールが安定して働くか を分けることです。
ざっくり言えば、
- mdファイルはプロジェクトの前提
- rulesは条件つきの強い指示
- memoryは個人の継続的な好み
- 毎回のプロンプトはその場限りの条件
です。
この4層を分けるだけで、毎回同じ説明をしているのにブレる 状態はかなり減らせます。
さらに md ファイルの書き方そのものを詰めたい場合は、AIコーディングで使うmdファイルとは？AGENTS.md・CLAUDE.md・指示書の役割を整理 から続けて読むとつながりやすいです。
AGENTS.md をどんどん足した結果、かえってAIコーディングが崩れる理由 を先に整理したいなら、AGENTS.mdが長すぎるとAIコーディングはなぜ崩れる？指示の埋もれ方と直し方を整理 も役立ちます。
参考リンク
- OpenAI Developers: Custom instructions with AGENTS.md
- OpenAI Developers: Configuration Reference
- Anthropic Docs: Manage Claude Code's memory
- Cursor Docs: Rules
- GitHub Docs: Adding repository custom instructions for GitHub Copilot
- GitHub Docs: Copilot customization cheat sheet