CLAUDE.mdを「とりあえずプロジェクトルートに置いた」——そこまでは多くのエンジニアがやっている。問題はその先だ。何を書けばいいか。どの順番で書けばいいか。どこまで詳しく書けばいいか。そして2026年現在、Claude自身が書く「auto memory」や領域ごとにルールを分割する「.claude/rules/」が公式に加わり、旧来の「CLAUDE.md一枚岩」の設計だけでは足りなくなっている。
この記事ではCLAUDE.mdの書き方に、2026年公式ドキュメント（code.claude.com/docs/en/memory）で追加された新機能を反映して特化して解説します。Claude Code全般の使い方は Claude Code完全ガイド2026：インストールから本番運用まで をご覧ください。
この記事でわかること
・CLAUDE.mdとauto memoryの違い——2026年の2本柱構成と、それぞれ何を書くべきか
・セクション設計パターン——コーディング規約・アーキテクチャ・テスト戦略・禁止事項の書き方
・プロジェクト規模別テンプレート（小〜大規模）と.claude/rules/による分割設計
・Managed policy CLAUDE.mdを含む4階層の読み込み優先順位
・よくある失敗パターン7つと、検証可能な指示への書き換え方（before/after）
・AGENTS.mdとの最新の統合方法（@importとsymlink）、.cursorrules・Copilot instructionsとの比較
CLAUDE.mdとauto memory——2026年の2本柱構成を理解する
Claude Codeが読み込むタイミング
CLAUDE.mdはClaude Codeが起動するたびに自動的に読み込まれる。「常時コンテキスト注入」と言い換えてもいい。チャット履歴がリセットされても、CLAUDE.mdの内容は毎セッション先頭からClaudeのコンテキストウィンドウに流し込まれる。Claude Codeのmdファイル（CLAUDE.md）はプレーンなMarkdownで、あなたが直接編集する。
公式ドキュメントでは、読み込まれる場所は広いスコープから狭いスコープへ4階層ある。
| スコープ | 場所 | 用途 | Gitコミット |
|---|---|---|---|
| Managed policy | macOS: /Library/Application Support/ClaudeCode/CLAUDE.mdLinux/WSL: /etc/claude-code/CLAUDE.mdWindows: C:\Program Files\ClaudeCode\CLAUDE.md |
IT管理者がMDM等で全社配布。個人設定で除外不可 | 対象外 |
| User | ~/.claude/CLAUDE.md |
全プロジェクト共通の個人的な好み | ❌ しない |
| Project | {project-root}/CLAUDE.md または ./.claude/CLAUDE.md |
チーム全員で共有するルール | ✅ する |
| Local | {project-root}/CLAUDE.local.md |
個人の設定・APIキー参照先・ローカルパス | ❌ しない（.gitignore対象） |
サブディレクトリに置いたCLAUDE.mdは起動時に全読み込みされるプロジェクト直下のものと異なり、Claudeがそのディレクトリのファイルを実際に読んだときだけオンデマンドで読み込まれる。モノリポで「フロントエンドはReact規約、バックエンドはFastify規約」のように領域ごとに規約を分けたい場合に有効だ。
auto memory——Claudeが自分で書く学習メモ
2026年の公式ドキュメントが明記する最大の変化は、CLAUDE.mdが唯一の永続コンテキストではなくなったことだ。auto memoryはClaudeが会話の中で得た訂正・好み・デバッグ知見を自分で判断して書き残す仕組みで、CLAUDE.mdと並ぶもう一本の柱として機能する。
| CLAUDE.md | auto memory | |
|---|---|---|
| 誰が書くか | 人間 | Claude自身 |
| 内容 | 指示・ルール | 学習・パターン |
| スコープ | プロジェクト／個人／組織 | リポジトリ単位（端末ローカル） |
| 読み込まれ方 | 毎セッション全文 | 毎セッション先頭200行/25KBのみ（詳細は必要時） |
| 向いている用途 | コーディング規約・ワークフロー・アーキテクチャ | ビルドコマンド・デバッグの知見・Claudeが発見した好み |
保存先は~/.claude/projects/<project>/memory/で、MEMORY.mdが索引として機能し、debugging.mdのような話題別ファイルはClaudeが必要になったタイミングで読みに行く。同一リポジトリの複数worktreeは1つのauto memoryディレクトリを共有するが、マシンをまたいでは共有されない。/memoryコマンドでオン/オフの切り替えや中身の閲覧ができ、プロジェクト単位で無効化したい場合は.claude/settings.jsonに"autoMemoryEnabled": falseを設定する。
「新しいチームメンバーに最初に読ませたい情報」はCLAUDE.mdに書く。「Claudeが試行錯誤の末に学んだ、その場限りではないコツ」はauto memoryに任せる。両方を人間が手書きしようとすると重複・陳腐化が起きやすい。
/init コマンドによる自動生成
ゼロから書く必要はない。Claude Codeのチャットで /init と入力するだけで、コードベースを分析してCLAUDE.mdのドラフトを自動生成してくれる。すでにCLAUDE.mdがある場合は上書きせず改善提案を返す。生成後の作業は「1行ずつ読んで自明な内容を削り、チームが知っておくべき情報を追記する」というレビューだ。ロードされているかどうかは/contextコマンドで確認できる。
242リポジトリ・253件のCLAUDE.mdを分析した実証研究（arXiv 2509.14744）によると、最も多いカテゴリはBuild/Run（77.1%）、次いで実装詳細（71.9%）、アーキテクチャ（64.8%）。「コマンドの書き方がわからない」問題への答えが、この分布にある——ビルド・実行コマンドから始めるのが事実上のデファクト標準だ。
ハーネスエンジニアリングの核心としてのCLAUDE.md
CLAUDE.mdの重要性は「便利なメモ帳」を超えた位置にある。
ハーネスエンジニアリングとは何か——5つの流派と設計思想を整理するで解説したように、ハーネスエンジニアリングとはAIエージェントが自律的に動くための「実行環境全体の設計」だ。その中でCLAUDE.mdはGuides（ガイド）——エージェントが最初から正しい結果を出せるよう事前制御する仕組みの実装形態として機能する。
Hashimoto流「失敗→ルール追記」サイクル
HashiCorp創業者のMitchell Hashimotoが実践する流派は、現場感覚に最も近いCLAUDE.md活用法を示している。
CLAUDE.mdは生き物だ——プロジェクトが成熟するにつれてルールが蓄積し、エージェントの失敗率が下がっていく。公式ドキュメントの「When to add to CLAUDE.md」も同じ発想を共有しており、「Claudeが同じミスを二度犯したら追記する」「コードレビューで指摘された知見を追記する」を基準として挙げている。
CLAUDE.mdがないとどうなるか
CLAUDE.mdがない状態でClaude Codeを使うと、以下の問題が繰り返し発生する。
・プロジェクトのコーディング規約を毎回プロンプトで伝えなければならない
・テスト実行方法を都度説明する必要がある
・「絶対に触ってはいけないファイル」を指定し忘れて上書きされる
・採用していない依存ライブラリを勝手にインストールされる
・アーキテクチャの決定（なぜその設計か）が伝わらず、過去の判断が覆される
CLAUDE.mdはClaudeへの「チーム合意事項の通知書」だ。新入りのエンジニアに最初に読ませるドキュメントをClaudeにも読ませる——それがCLAUDE.mdの本質的な役割だ。ただしCLAUDE.mdは強制設定ではなくコンテキストであり、絶対に守らせたい振る舞いはCLAUDE.mdでなくPreToolUseフックで機械的にブロックする必要がある点は公式ドキュメントも明記している。
CLAUDE.mdの書き方——セクション設計とプロジェクト規模別テンプレート
CLAUDE.mdの効果は、書く内容より書く順番と粒度に大きく左右される。Claudeのコンテキスト処理は前半ほど注意が集中するため、重要なルールは冒頭に置く必要がある。
推奨セクション構成
1. プロジェクト概要（必須・1〜3行）
何を作っているプロジェクトかを1〜2文で述べる。技術スタックとバージョンを明記する。ClaudeはNext.js 14とNext.js 15を区別できないし、DrizzleとPrismaを自動判断しない。
## プロジェクト概要
EC向けの在庫管理SaaS。Next.js 15 (App Router) + TypeScript strict + Drizzle ORM + PostgreSQL 16。
2. ビルド・実行コマンド（必須）
実証研究でも77%のCLAUDE.mdに含まれていた最頻出カテゴリ。ローカル起動・テスト・ビルドのコマンドを明記する。「どうやって動かすか」がわからないとClaudeは実行確認ができない。
3. コーディング規約（重要）
「暗黙のお作法」こそ書く価値がある。チームが自明だと思っている規約ほど、Claudeには伝わっていない。
4. アーキテクチャ・ディレクトリ構造（重要）
「なぜその設計か」の理由を添える。理由がないと、Claudeは「より良いと判断した別の設計」に書き換えようとする可能性がある。
5. テスト戦略（重要）
どんなテストをどのツールで書くか。VitestかJestか。E2EはPlaywrightかCypressか。「モックを使う場合のルール」も明記する。
6. 禁止事項・NG集（最重要）
最も効果が高いセクションの1つだ。「やってはいけないこと」を明示的に書くことで、繰り返しの失敗を防ぐ。
## 禁止事項
- npm install で新しいライブラリを追加する前に必ず確認を取る
- src/legacy/ ディレクトリは絶対に変更しない
- mainブランチへの直接pushは禁止。必ずdraft/ブランチを切る
- console.logをコミットに含めない。デバッグはloggerモジュールを使う
小規模プロジェクトの例（150行未満）
## プロジェクト
個人ブログ・静的サイト。Jekyll 4.3 + Cloudflare Pages。
## コマンド
- ローカル起動: bundle exec jekyll serve --livereload
- ビルド: bundle exec jekyll build
## ルール
- _posts/ の日付フォーマット: YYYY-MM-DD-slug.md
- frontmatterの title フィールドに二重引用符を使わない（YAMLパースが壊れる）
- mainに直接pushしない。draft/ブランチ経由でPR
## 禁止事項
- gemfileのバージョンを変更するときは事前確認
- _layouts/ の変更は全ページ影響するため慎重に
.claude/rules/ による大規模プロジェクトの分割
公式ドキュメントは200行を超えるCLAUDE.mdに対し、旧来の@importだけでなく.claude/rules/ディレクトリへの分割を第一の選択肢として案内している。
your-project/
├── .claude/
│ ├── CLAUDE.md # プロジェクト共通の要点
│ └── rules/
│ ├── code-style.md # pathsなし=毎セッション読み込み
│ ├── testing.md
│ └── frontend/
│ └── react.md # ---\npaths:\n - "src/**/*.tsx"\n---
pathsフロントマターを指定しないルールは.claude/CLAUDE.mdと同じ優先度で毎セッション読み込まれる。pathsを指定したルールは、Claudeがそのglobパターンに一致するファイルを実際に読んだときだけオンデマンドでロードされ、無関係な領域のルールでコンテキストを消費しない。シンボリックリンクにも対応しており、複数プロジェクトで共通ルールを共有できる。
.claude/rules/はCLAUDE.mdと同じく「毎セッションまたはファイルオープン時に自動ロードされる」設計だ。手順書・ワークフロー・テンプレートのように呼び出されたときだけ必要な情報はSKILL.mdへ移す。ルールに手順書を書くと、毎回全トークンを消費する。詳しくは[Claude Skillsを徹底解説](/explain/claude-skills-explained/)を参照。
大規模な150行超のプロジェクトでは、CLAUDE.md本体をクイックリファレンスに留め、詳細を.claude/rules/と@importに分散させる。
## このCLAUDE.mdについて
詳細なルールは以下を参照:
@.claude/rules/architecture.md
@.claude/rules/security.md
## クイックリファレンス（必ず読む）
（最重要ルールのサマリーを20行以内で書く）
インポートされたファイルはCLAUDE.md本体と同様に起動時に全読み込みされる。分割してもトークン消費量は変わらない。目的は保守性の向上であり、トークン削減が目的ならSKILL.mdや`paths`指定の`.claude/rules/`を使う。インポート記法はコードブロック内では展開されないため、パスに触れるだけならバッククォートで囲む。
（技術スタック・バージョン）"] --> B["2️⃣ ビルド・実行コマンド
（最頻出・必ず冒頭に）"] B --> C["3️⃣ コーディング規約
（暗黙の作法を明示化）"] C --> D["4️⃣ アーキテクチャ設計
（理由込みで記述）"] D --> E["5️⃣ テスト戦略
（ツール・境界・モックルール）"] E --> F["6️⃣ 禁止事項・NG集
（最も防御効果が高い）"] F --> G["7️⃣ .claude/rules/への分割
（200行超・領域別ルール）"] style A fill:#4A90D9,color:#fff style F fill:#E74C3C,color:#fff
CLAUDE.mdの良い例 vs 悪い例——before/afterで学ぶ書き方
Before（悪い例）: 曖昧な指示
# ルール
- きれいなコードを書いてください
- テストは必ず書いてください
- セキュリティに気をつけてください
- 変更前に確認してください
何が問題か：「きれいなコード」の定義がない。「必ず」「気をつける」は行動を規定していない。「確認」の対象・方法が不明。
After（良い例）: 具体的で検証可能な指示
## コーディング規約
- 関数は単一責任。20行を超えたら分割を検討する
- any型は禁止。unknown + 型ガードで代替する
## テスト
- 新機能にはVitest単体テストを必ず追加（カバレッジ80%以上）
- DBを直接テストに使う（モック禁止の理由: 2025Q3のマイグレーション失敗がモックで検知できなかった）
## 変更前の確認が必要な箇所
- packages/db/schema.ts（マイグレーション生成フローを経る）
- src/auth/（セキュリティ影響大）
よくある「良い意図・悪い記述」パターン
| 悪い例 | 良い例 | 問題の本質 |
|---|---|---|
| 「モダンなコードを書いて」 | 「クラスよりReact hooks、コールバックよりasync/await」 | 「モダン」の定義がない |
| 「適切なエラーハンドリングを」 | 「API失敗はResult型で。console.errorでなくlogger.error」 | 「適切」は計測できない |
| 「大きな変更は相談して」 | 「50行以上の変更・依存追加・DB変更前に確認」 | 「大きい」の基準がない |
| 「既存コードのスタイルに合わせて」 | 「既存ファイルを読んでパターンを確認。整合しない場合は確認」 | 読むべきコードが特定されていない |
| 「テストを書いて」 | 「src/以下の変更にはsrc/tests/に対応テストを追加」 | 場所・形式が不明 |
CLAUDE.mdでよくある失敗パターン7つ
CLAUDE.mdは書けば効果が出るわけではない。公式ドキュメントとコミュニティの知見が繰り返し指摘する失敗パターンは以下の7つに集約できる。
❌ パターン1：書きすぎて重要ルールが埋もれる
CLAUDE.mdを「知っていることをすべて書く場所」と誤解して500行・1000行になるケース。LLMの注意機構の特性上、後半のルールは実質的に無視される。
対策： 200行を上限として設計する。それを超えるなら.claude/rules/や@importで分割、または重要度の低いルールを削除する。公式の/doctorコマンドは、コードを読めばわかる内容（ディレクトリ構成・依存関係一覧など）の削減案を提示してくれる。
❌ パターン2：自明なことで埋め尽くされる
Claudeはpackage.jsonを読めば技術スタックを把握できる。「コードを読めばわかること」をCLAUDE.mdに書いても価値はない。対策： 「コードを読んでもわからない暗黙の合意事項」だけを書く。
❌ パターン3：一度書いて放置する
プロジェクトが進化するにつれ、CLAUDE.mdの内容は陳腐化する。対策： Hashimoto流の「失敗→ルール追記」に加えて、月次または四半期でのレビューを習慣化する。
❌ パターン4：禁止事項を書かない
「何をすべきか」だけ書いて「何をしてはいけないか」を書かないケース。対策： 禁止事項セクションを最高優先度で設ける。
❌ パターン5：個人設定をチームリポジトリに混入させる
「私のローカル環境では〜」「私はvimキーバインドが好みなので〜」のような個人設定をCLAUDE.mdに書くケース。対策： 個人設定はCLAUDE.local.mdに書き、.gitignoreで管理する。
❌ パターン6：手順書をCLAUDE.mdに書く
「デプロイ手順（20ステップ）」のような長い手順書を書くと、毎セッション全トークンを消費する。対策： 手順書はSKILL.mdに移す。呼び出されたときだけロードされる。
❌ パターン7：「確認してください」の羅列
「重要なファイルは変更前に確認してください」は動作を規定しない。対策： 「どのファイルを」「どういう場合に」「どんなアクションをとるか」を具体的に書く。
他ツールとの比較——.cursorrules・AGENTS.md・Copilot instructions・Cline
2026年現在、AIコーディングツールはそれぞれ独自のコンテキストファイル形式を持っている。プロジェクトで複数ツールを使う場合、どのファイルを「正」とするかの設計判断が重要になる。各フォーマットの対応関係を網羅したマップはAI時代におけるMDファイルを整理する｜CLAUDE.md・.cursorrules・AGENTS.md完全対応表も参照してほしい。
ツール別コンテキストファイル対応表
| ツール | コンテキストファイル | 自動読み込み | 複数ファイル | 階層構造 |
|---|---|---|---|---|
| Claude Code | CLAUDE.md | ✅ セッション開始時 | @import・.claude/rules/対応 | ✅ サブディレクトリ |
| Cursor | .cursorrules / .cursor/rules/*.md | ✅ | .cursor/rules/ | 限定的 |
| GitHub Copilot | .github/copilot-instructions.md | ✅ | ❌ 単一ファイル | ❌ |
| Cline | .clinerules/ 以下の.md/.txt | ✅ 全ファイル統合 | ✅ | ❌ |
| Devin / OpenAI Codex | AGENTS.md | ✅ | @import対応 | ✅ |
AGENTS.mdとの統合方法（2026年公式手順）
Claude CodeはAGENTS.mdを直接は読み込まない。複数ツール環境やOSSプロジェクトでは、AGENTS.md完全ガイド：OpenAI Codex・Devin・Claude Codeでの書き方と違いでも詳述されているように、AGENTS.mdがクロスプラットフォーム標準として台頭している。両方のファイルを重複メンテしないために、公式ドキュメントは次の2通りの統合方法を示している。
@AGENTS.md
## Claude Code
Use plan mode for changes under `src/billing/`.
Claude固有の追記が不要なら、シンボリックリンクでも代替できる（ln -s AGENTS.md CLAUDE.md）。ただしWindowsでシンボリックリンクを作るには管理者権限またはDeveloper Modeが必要なため、その場合は@AGENTS.mdインポートを使う。/initコマンドはCursor・Copilotのルールも読み取って統合案を提示し、/importコマンド（Claude Code v2.1.213以降）は他ツールの設定を一度だけ取り込める。
Cursorとの設計思想の違い
Cursorの.cursorrules（または.cursor/rules/）はIDE統合を前提とした設計で、インラインコード補完やAIコードアクションに対する指示が中心になる傾向がある。一方CLAUDE.mdはCLIベースの自律エージェント操作を前提とした設計で、「何をしてはいけないか（禁止事項）」「ツール実行の許可範囲」のような、エージェントの自律行動を制御するルールの比重が高い。
ツール間の構文の違いは細部だが、「コードを読んでもわからない暗黙の合意事項を書く」「禁止事項を明示的にリスト化する」「手順書ではなくルールを書く」という原則はCLAUDE.md・AGENTS.md・.cursorrulesいずれにも共通して有効です。
なお、ARCHITECTURE.mdのようなアーキテクチャ解説専用のMarkdownファイルを慣習として置くOSSプロジェクトもあるが、これはAnthropicが定義した仕組みではなく単なるファイル命名慣習で、Claude Codeが自動で読み込む対象ではない。読ませたい場合はCLAUDE.mdから@ARCHITECTURE.mdで明示的にインポートする必要がある。
まとめ——CLAUDE.mdを「育てる」という発想
CLAUDE.mdは「完璧に設計してから運用する」ものではなく、失敗のたびに改善されていく生き物だ。そして2026年現在、それを支える仕組みはCLAUDE.md単体ではなく、auto memory・.claude/rules/・managed policyまで含めた複数レイヤーの組み合わせになっている。
最初のCLAUDE.mdは：
・/initコマンドで自動生成する
・自明な内容を削り、「コードを読んでもわからない合意事項」を追記する
・禁止事項セクションを最高優先度で設ける
・200行以内に収める
その後は：
・Claudeが失敗するたびにルールを追記する（Hashimoto流）。Claude自身の学習はauto memoryに任せる
・月次でレビューし、古い情報を削除する。/doctorの提案を参考にする
・200行を超えたら.claude/rules/または@importで分割する
CLAUDE.mdはチームの「AIとの共同作業マニュアル」だ。人間の新入りエンジニアに読ませるドキュメントと同じ観点で書いて、同じ観点で更新し続ける——それが長期的に機能するCLAUDE.mdを維持するための最もシンプルな方針だ。
参照ソース
- How Claude remembers your project - Claude Code Docs
- Best Practices for Claude Code - Claude Code Docs
- Writing a good CLAUDE.md - HumanLayer Blog
- How to Write a Good CLAUDE.md File - Builder.io
- On the Use of Agentic Coding Manifests: An Empirical Study of Claude Code - arXiv
- Using CLAUDE.MD files: Customizing Claude Code for your codebase - Anthropic Blog
- cursorrules vs CLAUDE.md vs Copilot Instructions - Agent Rules
- Claude Code project memory: how CLAUDE.md files work across nested directories - DEV Community
