CLAUDE.mdを「とりあえずプロジェクトルートに置いた」——そこまでは多くのエンジニアがやっている。問題はその先だ。何を書けばいいか。どの順番で書けばいいか。どこまで詳しく書けばいいか。サブディレクトリはどう扱うか。他のAIツールとの使い分けは——これらの疑問に答えてくれるまとまったドキュメントは少ない。
この記事ではCLAUDE.mdの書き方に特化して解説します。Claude Code全般の使い方は Claude Code完全ガイド2026：インストールから本番運用まで をご覧ください。
CLAUDE.mdとは——セッション開始時に読み込まれるコンテキストファイル
Claude Codeが読み込むタイミング
CLAUDE.mdはClaude Codeが起動するたびに自動的に読み込まれる。「常時コンテキスト注入」と言い換えてもいい。チャット履歴がリセットされても、CLAUDE.mdの内容は毎セッション先頭からClaudeのコンテキストウィンドウに流し込まれる。
読み込まれるファイルは複数存在し、優先順位がある。
~/.claude/CLAUDE.md ← グローバル設定（全プロジェクト共通）
{project-root}/CLAUDE.md ← プロジェクト設定（チームで共有）
{project-root}/CLAUDE.local.md ← 個人設定（.gitignore対象）
{subdirectory}/CLAUDE.md ← サブディレクトリ設定（オンデマンド）
グローバル設定（~/.claude/CLAUDE.md）はすべてのプロジェクトに適用される個人の好みや汎用ルールを書く場所だ。プロジェクト設定（{project-root}/CLAUDE.md）はチーム全員で共有するルール。CLAUDE.local.mdは個人の設定で、Gitには含めない。
/init コマンドによる自動生成
ゼロから書く必要はない。Claude Codeのチャットで /init と入力するだけで、コードベースを分析してCLAUDE.mdのドラフトを自動生成してくれる。生成後の作業は「1行ずつ読んで自明な内容を削り、チームが知っておくべき情報を追記する」というレビューだ。
242リポジトリ・253件のCLAUDE.mdを分析した実証研究（arXiv 2509.14744）によると、最も多いカテゴリはBuild/Run（77.1%）、次いで実装詳細（71.9%）、アーキテクチャ（64.8%）。「コマンドの書き方がわからない」問題への答えが、この分布にある——ビルド・実行コマンドから始めるのが事実上のデファクト標準だ。
CLAUDE.mdとCLAUDE.local.mdの分担
| ファイル | 内容 | Gitコミット |
|---|---|---|
| CLAUDE.md | チーム共通ルール・コーディング規約・アーキテクチャ | ✅ する |
| CLAUDE.local.md | 個人設定・APIキー参照先・ローカルパス | ❌ しない |
| ~/.claude/CLAUDE.md | 全プロジェクト共通の個人好み | ❌ しない |
この3ファイル体制を最初から意識して設計すると、「チームメンバーの個人設定が混入する」「秘匿情報をうっかりコミットする」といった問題を防げる。
ハーネスエンジニアリングの核心としてのCLAUDE.md
CLAUDE.mdの重要性は「便利なメモ帳」を超えた位置にある。
ハーネスエンジニアリングとは何か——5つの流派と設計思想を整理するで解説したように、ハーネスエンジニアリングとはAIエージェントが自律的に動くための「実行環境全体の設計」だ。その中でCLAUDE.mdはGuides（ガイド）——エージェントが最初から正しい結果を出せるよう事前制御する仕組みの実装形態として機能する。
Hashimoto流「失敗→ルール追記」サイクル
HashiCorp創業者のMitchell Hashimotoが実践する流派は、現場感覚に最も近いCLAUDE.md活用法を示している。
プロセスはシンプルだ。
- エージェントが失敗する
- その失敗が「物理的に再発不能になるルール」をCLAUDE.mdに追記する
- これを繰り返す
特別な設計なしに、実運用の失敗からCLAUDE.mdが育っていく。「最初から完璧なCLAUDE.mdを書こうとしない」というメッセージでもある。CLAUDE.mdは生き物だ——プロジェクトが成熟するにつれてルールが蓄積し、エージェントの失敗率が下がっていく。
CLAUDE.mdがないとどうなるか
CLAUDE.mdがない状態でClaude Codeを使うと、以下の問題が繰り返し発生する。
- プロジェクトのコーディング規約を毎回プロンプトで伝えなければならない
- テスト実行方法を都度説明する必要がある
- 「絶対に触ってはいけないファイル」を指定し忘れて上書きされる
- 採用していない依存ライブラリを勝手にインストールされる
- アーキテクチャの決定（なぜその設計か）が伝わらず、過去の判断が覆される
CLAUDE.mdはClaudeへの「チーム合意事項の通知書」だ。新入りのエンジニアに最初に読ませるドキュメントをClaudeにも読ませる——それが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には伝わっていない。
良い書き方の例：
any型を使わない。型が不明な場合はunknownを使うコンポーネントはApp Router規約に従いServerComponentをデフォルトとするエラーハンドリングはResult型パターン（neverthrow）で統一
4. アーキテクチャ・ディレクトリ構造（重要）
「なぜその設計か」の理由を添える。理由がないと、Claudeは「より良いと判断した別の設計」に書き換えようとする可能性がある。
5. テスト戦略（重要）
どんなテストをどのツールで書くか。VitestかJest か。E2EはPlaywrightかCypressか。「モックを使う場合のルール」「テスト対象の境界（どこから先はテスト不要か）」も明記する。
6. 禁止事項・NG集（重要）
最も効果が高いセクションの1つだ。「やってはいけないこと」を明示的に書くことで、繰り返しの失敗を防ぐ。
良い例：
npm install で新しいライブラリを追加する前に必ず確認を取るsrc/legacy/ ディレクトリは絶対に変更しないmainブランチへの直接pushは禁止。必ずdraft/ブランチを切るconsole.logをコミットに含めない。デバッグはloggerモジュールを使う
7. ワークフロー・開発フロー（任意）
PRフロー・コードレビュープロセス・デプロイ手順など、反復的な作業の手順を書く。
セクション優先順位の設計原則
（技術スタック・バージョン）"] --> B["2️⃣ ビルド・実行コマンド
（最頻出・必ず冒頭に）"] B --> C["3️⃣ コーディング規約
（暗黙の作法を明示化）"] C --> D["4️⃣ アーキテクチャ設計
（理由込みで記述）"] D --> E["5️⃣ テスト戦略
（ツール・境界・モックルール）"] E --> F["6️⃣ 禁止事項・NG集
（最も防御効果が高い）"] F --> G["7️⃣ ワークフロー
（反復作業の手順）"] style A fill:#4A90D9,color:#fff style F fill:#E74C3C,color:#fff
プロジェクト規模別テンプレート
CLAUDE.mdの適切な長さはプロジェクト規模によって異なる。「長ければ良い」は誤りだ。LLMが一貫して従える指示数は150〜200件程度が上限とされており、それを超えると後半のルールが実質的に無視される。
小規模：個人プロジェクト（20〜50行）
## プロジェクト
個人ブログ・静的サイト。Jekyll 4.3 + Cloudflare Pages。
## コマンド
- ローカル起動: bundle exec jekyll serve --livereload
- ビルド: bundle exec jekyll build
- テスト（リンクチェック）: bundle exec htmlproofer ./_site
## ルール
- _posts/ の日付フォーマット: YYYY-MM-DD-slug.md
- frontmatterの title フィールドに二重引用符を使わない（YAMLパースが壊れる）
- mainに直接pushしない。draft/ブランチ経由でPR
## 禁止事項
- gemfileのバージョンを変更するときは事前確認
- _layouts/ の変更は全ページ影響するため慎重に
中規模：チーム開発（50〜150行）
中規模では「暗黙の合意事項」が増えるため、コーディング規約とアーキテクチャの記述を厚くする。
## プロジェクト概要
B2B SaaS（在庫管理）。Node.js 22 + TypeScript 5.4 strict + Fastify + Drizzle ORM + PostgreSQL 16 + Redis。
チームサイズ: 7人。モノリポ構成（pnpm workspaces）。
## コマンド
- 開発環境起動: pnpm dev（全サービス起動。docker compose up -d が前提）
- テスト: pnpm test（単体）, pnpm test:e2e（E2E、ローカルDB必要）
- ビルド: pnpm build
- 型チェック: pnpm typecheck
- lint: pnpm lint（修正: pnpm lint:fix）
## ディレクトリ構造
apps/
api/ ← Fastify APIサーバー
web/ ← Next.js 15 フロントエンド
packages/
db/ ← Drizzle スキーマ・マイグレーション
shared/ ← 共通型定義・ユーティリティ
## アーキテクチャ原則
- APIはREST（GraphQL不採用の理由: over-fetchingより実装コスト削減を優先した歴史的経緯）
- 認証: JWT（httponly cookie）。サーバー側セッションなし
- DBアクセスはすべて packages/db 経由。apps/ から直接Drizzle importしない
## コーディング規約
- any型禁止。型が不明な場合はunknown + 型ガードで絞る
- エラーハンドリング: neverthrow の Result型を使う（throwは外部API失敗のみ許可）
- コンポーネントはServerComponentデフォルト。'use client' が必要な場合のみ明示
- 命名: ファイル名はkebab-case、コンポーネント名はPascalCase
## テスト
- 単体テスト: Vitest（MSW でHTTPモック）
- E2E: Playwright（locatorベース。page.$$ 禁止）
- DBをモックしない。テスト用DBインスタンスを使う（理由: 2025年Q3のマイグレーション失敗をモックで見逃した実績あり）
## 禁止事項
- pnpm add で新パッケージを追加する前に必ずチームに確認
- packages/db/schema.ts を直接変更しない（マイグレーションファイルを生成するフローを経る）
- console.log をコミットに含めない（logger モジュールを使う）
- force push 禁止（main, staging, production ブランチ）
- src/legacy/ は読み取り専用。絶対に変更しない
大規模：@import分割（150行超）
CLAUDE.mdが150行を超える場合は@import構文でファイルを分割する。ただし「分割しても読み込みトークンは減らない」——分割の目的はトークン削減ではなく、保守性の向上だ。
## このCLAUDE.mdについて
詳細なルールは以下のファイルを参照:
@.claude/rules/coding-standards.md
@.claude/rules/architecture.md
@.claude/rules/testing.md
@.claude/rules/security.md
@.claude/rules/forbidden.md
## クイックリファレンス（必ず読む）
（ここに最重要ルールのサマリーを20行以内で書く）
インポートされたファイルはCLAUDE.md本体と同様に起動時に全読み込みされます。分割してもトークン消費量は変わりません。トークン削減が目的なら、CLAUDE.mdではなくスキル（SKILL.md）を使ってください。スキルはオンデマンド読み込みのため、常時ロードされません。詳しくは Claude Skillsを徹底解説 をご覧ください。
良い例 vs 悪い例——before/afterで学ぶ
Before（悪い例）: 曖昧な指示
# ルール
- きれいなコードを書いてください
- テストは必ず書いてください
- セキュリティに気をつけてください
- 変更前に確認してください
何が問題か：
- 「きれいなコード」の定義がない（何がきれいで何が汚いか）
- 「必ず」「気をつける」は行動を規定していない
- 「確認」の対象・方法が不明
After（良い例）: 具体的で検証可能な指示
## コーディング規約
- 関数は単一責任。20行を超えたら分割を検討する
- コメントは「なぜ」を書く（「何を」はコード自体が語る）
- any型は禁止。unknown + 型ガードで代替する
## テスト
- 新機能にはVitest単体テストを必ず追加（カバレッジ80%以上）
- DBを直接テストに使う（モック禁止の理由: 2025Q3のマイグレーション失敗がモックで検知できなかった）
## セキュリティ
- SQLはすべてDrizzleのqueryビルダー経由（生クエリ禁止）
- ユーザー入力はzodでバリデーション後に使用
## 変更前の確認が必要な箇所
- packages/db/schema.ts（マイグレーション生成フローを経る）
- src/auth/（セキュリティ影響大）
- .env.production（本番環境変数）
よくある「良い意図・悪い記述」パターン
| 悪い例 | 良い例 | 問題の本質 |
|---|---|---|
| 「モダンなコードを書いて」 | 「クラスよりReact hooks、コールバックよりasync/await」 | 「モダン」の定義がない |
| 「適切なエラーハンドリングを」 | 「API失敗はResult型で。console.errorでなくlogger.error」 | 「適切」は計測できない |
| 「大きな変更は相談して」 | 「50行以上の変更・依存追加・DB変更前に確認」 | 「大きい」の基準がない |
| 「既存コードのスタイルに合わせて」 | 「既存ファイルを読んでパターンを確認。整合しない場合は確認」 | 読むべきコードが特定されていない |
| 「テストを書いて」 | 「src/以下の変更にはsrc/tests/に対応テストを追加」 | 場所・形式が不明 |
階層CLAUDE.mdと.claude/フォルダ構成
階層CLAUDE.mdの読み込み動作
Claude Codeはプロジェクトの複数箇所にあるCLAUDE.mdをインテリジェントに扱う。
.
├── CLAUDE.md ← 起動時に全読み込み（プロジェクト共通）
├── CLAUDE.local.md ← 起動時に全読み込み（個人設定・git除外）
├── src/
│ ├── CLAUDE.md ← src/配下ファイルを読んだときにロード
│ └── components/
│ └── CLAUDE.md ← components/配下ファイルを読んだときにロード
└── packages/
└── db/
└── CLAUDE.md ← packages/db/配下ファイルを読んだときにロード
ルートCLAUDE.mdはセッション開始時に常駐するが、サブディレクトリのCLAUDE.mdはClaudeがそのディレクトリのファイルに触れたときに初めてロードされる。これはオンデマンドロードの仕組みで、巨大なモノリポでもコンテキストを無駄に消費しない設計になっている。
モノリポで「フロントエンドはReact規約、バックエンドはFastify規約、DBはDrizzle規約」のように、サブパッケージごとに異なるルールを適用する場合に有効です。ルートCLAUDE.mdには全パッケージ共通のルールのみ書き、細則は各パッケージのCLAUDE.mdに委ねる構成です。
.claude/フォルダとCLAUDE.mdの関係
.claude/ ディレクトリはClaude Code全体の設定ハブだ。CLAUDE.mdはその一部に過ぎない。
.claude/
├── CLAUDE.md ← .claude/配下専用のルール（任意）
├── settings.json ← Claude Code設定（Hooks, ツール許可等）
├── settings.local.json ← 個人設定（git除外）
├── skills/ ← Skillsパッケージ
│ └── deploy/
│ └── SKILL.md
├── commands/ ← カスタムコマンド（旧形式）
└── memory/ ← Claudeの記憶ファイル（任意）
CLAUDE.mdとSKILL.mdの最大の違いは「読み込みタイミング」だ。
| ファイル | 読み込みタイミング | 用途 |
|---|---|---|
| CLAUDE.md | セッション開始時・常時 | チーム共通の不変ルール・禁止事項 |
| SKILL.md | 呼び出し時のみ | 特定ワークフロー・手順書・テンプレート |
| settings.json | セッション開始時・常時 | ツール許可・Hooks設定 |
手順書・テンプレート・長い参照ドキュメントをCLAUDE.mdに書くと、常にトークンを消費する。それらはClaude Skillsを徹底解説｜スキルはフォルダ——Anthropicエンジニアが明かした仕組みと使い方で解説したSKILL.mdに移すべきだ。
よくある失敗パターン
❌ パターン1：書きすぎて重要ルールが埋もれる
CLAUDE.mdを「知っていることをすべて書く場所」と誤解して500行・1000行になるケース。LLMの注意機構の特性上、後半のルールは実質的に無視される。
対策： 150〜200行を上限として設計する。それを超えるなら@importで分割、または重要度の低いルールを削除する。
❌ パターン2：自明なことで埋め尽くされる
# 悪い例
- TypeScriptでコードを書く
- コンポーネントはReactで実装する
- npm run dev でローカルサーバーを起動できる
Claudeはpackage.jsonを読めば技術スタックを把握できる。「コードを読めばわかること」をCLAUDE.mdに書いても価値はない。
対策： 「コードを読んでもわからない暗黙の合意事項」だけを書く。「なぜその技術を選んだか」「例外的なパターン」「絶対に変えてはいけない設計判断」が候補だ。
❌ パターン3：一度書いて放置する
プロジェクトが進化するにつれ、CLAUDE.mdの内容は陳腐化する。古いコマンド、廃止されたライブラリ、変更されたアーキテクチャ——これらが残ったままだとClaudeは古い情報を基に動く。
対策： Hashimoto流の「失敗→ルール追記」に加えて、月次または四半期でのレビューを習慣化する。「このCLAUDE.mdを読んで改善提案をして」 とClaudeに依頼するセルフレビューも有効だ。
❌ パターン4：禁止事項を書かない
「何をすべきか」だけ書いて「何をしてはいけないか」を書かないケース。エージェントは指示された行動より、指示されていないが合理的に見える行動を選ぶ傾向がある。
対策： 禁止事項セクションを最高優先度で設ける。過去に一度でも「やってしまった失敗」は必ずリスト化する。
❌ パターン5：個人設定をチームリポジトリに混入させる
# 悪い例（CLAUDE.md に書いてはいけない）
- 私のローカル環境では /Users/john/projects/lib を参照すること
- 私は vim キーバインドが好みなので vim風の操作感を維持して
対策： 個人設定はCLAUDE.local.mdに書き、.gitignoreで管理する。
❌ パターン6：手順書をCLAUDE.mdに書く
「デプロイ手順（20ステップ）」「新機能の実装フロー（15ステップ）」のような長い手順書をCLAUDE.mdに書くと、毎セッション全トークンを消費する。
対策： 手順書はSKILL.mdに移す。呼び出されたときだけロードされるため、不要なセッションでのトークン消費がゼロになる。
❌ パターン7：「確認してください」の羅列
# 悪い例
- 重要なファイルは変更前に確認してください
- 大きな変更は相談してください
- 依存関係の変更は注意してください
「確認」「相談」「注意」は動作を規定しない。Claudeが「確認した」と判断する基準が存在しないため、実際には何も変わらない。
対策： 「どのファイルを」「どういう場合に」「どんなアクションをとるか」を具体的に書く。
他ツールとの比較——.cursorrules・AGENTS.md・Copilot instructions・Cline
2026年現在、AIコーディングツールはそれぞれ独自のコンテキストファイル形式を持っている。プロジェクトで複数ツールを使う場合、どのファイルを「正」とするかの設計判断が重要になる。各フォーマットの対応関係を網羅したマップはAI時代におけるMDファイルを整理する｜CLAUDE.md・.cursorrules・AGENTS.md完全対応表も参照してほしい。
ツール別コンテキストファイル対応表
| ツール | コンテキストファイル | 自動読み込み | 複数ファイル | 階層構造 |
|---|---|---|---|---|
| Claude Code | CLAUDE.md | ✅ セッション開始時 | @import対応 | ✅ サブディレクトリ |
| 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（汎用） | AGENTS.md | ツールにより異なる | ツールにより異なる | ツールにより異なる |
AGENTS.mdとの使い分け
2026年、AGENTS.md完全ガイド：OpenAI Codex・Devin・Claude Codeでの書き方と違いでも詳述されているように、AGENTS.mdがクロスプラットフォーム標準として台頭している。Claude Code・Cursor・GitHub Copilot・Devin・Gemini CLIが認識するため、1ファイルで複数ツールに共通ルールを適用できる。
推奨パターン：
AGENTS.md ← 複数ツール共通ルール（最小限）
CLAUDE.md ← Claude Code固有のルール（Hooks設定への参照等）
.cursorrules ← Cursor固有のルール（IDEへの指示等）
「単一ツール環境（Claude Code専用）ならCLAUDE.mdで完結させる。複数ツール環境ならAGENTS.mdに共通ルールを集約し、CLAUDE.mdはClaude固有の差分だけ書く」——これが2026年の推奨パターンだ。
Cursorとの設計思想の違い
Cursorの.cursorrules（または.cursor/rules/）はIDE統合を前提とした設計で、インラインコード補完やAIコードアクションに対する指示が中心になる傾向がある。
一方CLAUDE.mdはCLIベースの自律エージェント操作を前提とした設計で、「何をしてはいけないか（禁止事項）」「ツール実行の許可範囲」「長期タスクの途中確認基準」のような、エージェントの自律行動を制御するルールの比重が高い。
ツール間の構文の違いは細部だが、「コードを読んでもわからない暗黙の合意事項を書く」「禁止事項を明示的にリスト化する」「手順書ではなくルールを書く」という原則はCLAUDE.md・AGENTS.md・.cursorrulesいずれにも共通して有効です。
まとめ——CLAUDE.mdを「育てる」という発想
CLAUDE.mdは「完璧に設計してから運用する」ものではなく、失敗のたびに改善されていく生き物だ。
最初のCLAUDE.mdは：
/initコマンドで自動生成する- 自明な内容を削り、「コードを読んでもわからない合意事項」を追記する
- 禁止事項セクションを最高優先度で設ける
- 100行以内に収める
その後は：
- Claudeが失敗するたびにルールを追記する（Hashimoto流）
- 月次でレビューし、古い情報を削除する
- 150行を超えたら@importで分割するか不要ルールを削除する
CLAUDE.mdはチームの「AIとの共同作業マニュアル」だ。人間の新入りエンジニアに読ませるドキュメントと同じ観点で書いて、同じ観点で更新し続ける——それが長期的に機能するCLAUDE.mdを維持するための最もシンプルな方針だ。
参照ソース
- Best Practices for Claude Code - Claude Code Docs
- How Claude remembers your project - 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
