Claude Code の AGENTS.md 実例集：プロジェクトごとに指示書を書き分けた話

Claude Code を使い始めたとき、最初に「AGENTS.md って何を書けばいいんだ」で詰まった。

ドキュメントを読んでも「プロジェクトのコンテキストを書く場所」くらいしか分からなくて、とりあえず技術スタックを羅列してみたら、Claude の動きが全然変わらなかった。

なので今回は、実際に使って効果があった AGENTS.md のパターンをそのまま公開する。

AGENTS.md ってそもそも何をするファイルか

Claude Code は、プロジェクトのルートに AGENTS.md（または CLAUDE.md）があるとそれを自動で読む。セッションをまたいで毎回読まれるので、「Claude に覚えておいてほしいこと」を置く場所だと思えばいい。

設定できることは大きく3つ。

技術的な制約：使っているフレームワークのバージョン、独自の規約
行動ルール：ファイルを消す前に確認する、コミットは必ず作る、など
コンテキスト：このプロジェクトが何で、誰のためのものか

この3つを書くだけで、Claude の動きが体感できるレベルで変わった。

失敗した書き方：技術スタックの羅列

最初に書いた AGENTS.md はこんな感じだった。

# My Project
 
- Next.js 15
- TypeScript
- Tailwind CSS
- Prisma
- PostgreSQL

これだとほぼ意味がなかった。Claude は技術スタックを知っていても、「このプロジェクトでどう動くべきか」が分からないから、毎回汎用的な実装を提案してくる。

効果があった書き方パターン3つ

パターン1：バージョン起因の誤動作を防ぐ

Next.js の App Router が出てから、Pages Router の書き方を提案されることがよくあった。バージョンが訓練データと違うとこれが起きる。

# This is NOT the Next.js you know
 
This version has breaking changes — APIs, conventions, and file structure
may all differ from your training data.
Read the relevant guide in `node_modules/next/dist/docs/` before writing any code.
Heed deprecation notices.

英語で書いているのは意図的で、Claude への指示は英語のほうが精度が上がる感覚がある。日本語プロジェクトでも指示だけ英語にするのはあり。

これを入れてから「getServerSideProps を使おうとする」みたいな誤動作がほぼ消えた。

パターン2：会社・プロジェクトの役割構造を渡す

個人の副業プロジェクトで、Claude Code に複数の役割を担わせたかった。そのとき AGENTS.md に組織図を書いてみたら、Claude の応答が一気にキャラクターを持った。

## 組織構成
 
| 役職 | 役割 |
|---|---|
| CEO（AI代表） | 評価・判断・統合・最終回答 |
| 秘書 | 情報整理・議事録・スケジュール |
| 分析・戦略部 | 市場分析・KPI・競合調査 |
| 開発部 | 技術選定・アーキテクチャ・工数見積もり |
 
## プロジェクト相談フロー
 
ユーザーから相談を受けたら以下の順で動く：
1. 秘書として内容を整理する
2. CEO として部署にアサインする
3. 各部署の Agent を並列で起動する
4. CEO として統合して最終回答する

Claude が「どの役割で動くか」を毎回判断してくれるようになって、複雑な依頼でも流れが安定した。

パターン3：やらないことを明示する

「実装前に必ず設計を出せ」「ファイルを消す前に確認しろ」みたいなルールは、言わないと守ってくれない。

## 絶対にやらないこと
 
- 確認なしにファイルを削除する
- git commit --amend で既存コミットを書き換える
- --no-verify でフックをスキップする
- ユーザーに聞かずに重要な判断をする
 
## 必ずやること
 
- 実装前に planモードで設計を出す
- 作業完了後は git status で確認する
- 記録はすべて Notion に残す

「やること」より「やらないこと」のほうが効果が高かった。 Claude は親切なので、良かれと思って余計なことをしがちだから。

@ファイル参照でメモリを分割する

AGENTS.md が長くなってきたら、@ でファイルを参照して分割できる。

# AGENTS.md
 
@MEMORY.md
@rules/development.md
@rules/communication.md

MEMORY.md にはプロジェクト固有の文脈（決定した仕様、過去の判断理由）を書いて、 rules/ に共通ルールをまとめておく。

実際にこれを使い始めてから、セッションをまたいでも「前に決めたこと」を忘れなくなった。前は毎回「先週決めたやつなんだっけ」と確認していたのが、そのコストがほぼゼロになった。

AGENTS.md を書くときの3つの問い

実際に何を書くか迷ったときは、この3つを考えると整理しやすい。

1. Claude が誤解しやすいことは何か バージョン差、命名規則、独自の設計方針など。知らないと間違える情報を優先的に書く。

2. 毎回言わないといけないことは何か 「コミット前に確認して」「設計から出して」など、口頭で言い続けていることは AGENTS.md に書く。

3. このプロジェクトで Claude にどう動いてほしいか 役割、優先順位、判断の基準。曖昧なまま使うより、キャラクターを与えたほうが精度が安定する。

まとめ

AGENTS.md はゼロから完璧に書こうとしなくていい。使いながら「また同じミスをされた」と思ったときに、その防止策を1行追加していく感じで育てるのが向いている。

今使っているプロジェクトに AGENTS.md がないなら、まず「やらないこと」を3行書くだけで始めてみるといい。それだけでも、Claude の動きが少し変わるのが分かると思う。