5-1 CLAUDE.md の書き方｜Claude Code の脳を育てる

このレッスンで身につくこと

このレッスンは、第 5 章「プロンプト術」の入口です。続く 5-2「効果的な指示のコツ」、5-3「Best of N パターン」と合わせた 3 部作の 土台 にあたります。

CLAUDE.md は Claude Code の "脳" を育てるファイル です。プロジェクトの前提・規約・コマンド・禁止事項を書いておけば、毎回の対話で「このプロジェクトは React で書かれていて、テストは vitest を使っていて……」と説明し直す必要がなくなります。Claude Code が セッション開始時に自動で読み込み 前提として動いてくれます。

所要時間 — 約 60 分（手を動かしながらなら 90 分） 難易度 — ★★☆☆☆（第 1〜2 章を読み終えていれば OK）

CLAUDE.md とは何か — Claude Code の "脳" を育てる場所

CLAUDE.md は、プロジェクトルートに置くプレーンテキスト です。形式は Markdown。Claude Code はセッション開始時にコンテキストへ流し込みます。

README と違って、CLAUDE.md は 「人間」ではなく「AI」が読む前提 で書きます。同じ内容でも、箇条書き寄り・命令文寄り に書いたほうが効きます。

# CLAUDE.md（人間向け README とは違う書き方）

## プロジェクト
- 社内タスク管理ツール（React + TypeScript）

## 守ること
- 関数コンポーネントのみ。クラスコンポーネント禁止
- console.log を残してコミットしない
- コミットメッセージは日本語

## やってほしいこと
- テスト実行は `bun test`（npm 禁止）
- 新規ページは `app/routes/` に置く

見出しで構造化し、箇条書きで命令 する。これが基本フォームです。Claude Code は Markdown の見出しを「文脈の切れ目」として認識するため、構造化された方が 必要なときだけ正確に思い出してくれます。

読み込みのタイミングと優先順位

CLAUDE.md は 以下の優先順位でマージ されます。

1. ==~/.claude/CLAUDE.md== — 全プロジェクト共通のあなた個人の好み
2. プロジェクトルート/CLAUDE.md — プロジェクト固有の規約（Git にコミット）
3. プロジェクトルート/CLAUDE.local.md — そのマシン固有のローカル設定（.gitignore）
4. サブディレクトリ/CLAUDE.md — そのディレクトリ配下のみ追加で読まれる指示

全部が「上書き」ではなく「足し算」です。~/.claude/CLAUDE.md に「コミットは日本語」と書き、プロジェクトの CLAUDE.md に「コミットは英語」と書くと、Claude Code は 後から読んだプロジェクト側を優先 します。

/init で雛形を自動生成

ゼロから書くのが大変なら、==/init== というスラッシュコマンドで雛形を生成できます。

cd ~/Documents/my-project
claude
> /init

/init は現在のディレクトリを再帰的に読み込み、package.json や README、ファイル構成から雛形を作ります。生成物はそのまま使わず、必ず手で加筆 してください。/init が拾えるのは "表面的な事実" だけ。暗黙ルール（「この関数はリファクタ予定」「このディレクトリは触らない」など）は人間が書き足します。

Before / After — CLAUDE.md がある場合・ない場合

抽象的に「便利です」と言われても腑に落ちないので、具体的なシナリオで比較します。

シナリオ A — ない場合

> ユーザー一覧ページにフィルター機能を足して と打つと、CLAUDE.md がない状態だと Claude Code は次のように動きます。

ユーザー一覧ページがどこにあるか確認します。

[Grep] "ユーザー一覧" を検索 → 3 ファイルヒット
[Read] app/users/page.tsx ... src/pages/UserList.tsx ...

これらのうち、どれが現在のユーザー一覧ページですか？
また、フィルターは A. クライアントサイド / B. サーバーサイド
のどちらで実装しますか？
使用フレームワークと UI ライブラリも教えてください。

このやり取りだけで往復 5 回 の質問応答が発生します。

シナリオ B — ある場合

同じプロジェクトに次の CLAUDE.md が置いてあるとします。

## プロジェクト
- B2B SaaS（顧客管理）/ React Router v7 / Go API（Cloud Run）

## ディレクトリ
- ユーザー機能: app/routes/users.tsx + app/components/user-*.tsx
- 旧コード src/ は移行中。新規実装は app/ のみ

## 規約
- 一覧フィルターは必ずサーバーサイド（page= / q= / sort=）
- データ取得は loader 内で safeApi
- 表示は @blueai/ui を優先

同じ指示を出すと、Claude Code は 質問ゼロ・往復 1 回 で app/routes/users.tsx を編集して完了します。30 秒の合意形成が 3 秒 になりました。

お金よりも「思考の連続性」のほうが大事 です。毎回プロジェクトの背景を説明していると、本来の仕事に集中できません。CLAUDE.md は 「ここに書いてあることは、もう説明したものとして扱ってください」 という、あなたから AI への契約書です。

CLAUDE.md の基本構造 — 5 セクションで覚える

何を書くか迷ったら、以下の 5 セクション に当てはめてみてください。だいたいのプロジェクトはこれで十分です。

全部合わせて 30〜80 行 に収めるのが目安です。それを超えると Claude Code 側でも「結局どこが大事なのか」がボケ始めます。

セクション 1 — プロジェクト概要

何のためのコードか を 1〜2 行で、技術スタックを 3〜4 行で。

## プロジェクト概要
- 中小企業向けの請求書発行 SaaS（個人事業主〜50 名規模が対象）
- Next.js 15（App Router）/ Hono on Cloudflare Workers
- DB: Cloudflare D1 / 認証: Better Auth

「中小企業向けの」「個人事業主が対象」 のような 業務文脈 を 1 行入れると、Claude Code が書くコードの言葉選び（UI 文言、エラーメッセージ）が一気に良くなります。

セクション 2 — コーディング規約

ESLint や Prettier ではカバーしきれない、プロジェクト固有の慣習 をここに。

## コーディング規約
- 関数は arrow function より function 宣言を優先
- React コンポーネントは named export
- TypeScript の any 禁止。unknown + 型ガードで対応
- console.log を残してコミットしない
- コメント・コミットメッセージは日本語、識別子は英語

「日本語コメント、英語識別子」 のような言語ルールは明示しないと、Claude Code がバラバラの方針で書いてきます。

セクション 3 — ディレクトリ構造

Claude Code が新規ファイル置き場で迷わない程度 に書きます。フルツリーは不要。

## ディレクトリ構造
- app/routes/ — ページ
- app/components/ — 共有コンポーネント
- app/lib/ — クライアント側ヘルパー
- db/schema.ts — Drizzle スキーマ（単一ソース）
- 触らない: dist/、build/、.wrangler/

「触っちゃいけない場所」を明記 するのは超重要です。Claude Code は気を抜くと build 成果物の中まで編集しようとします。

セクション 4 — 依存とコマンド

開発・テスト・ビルド・デプロイのコマンドを コピペで動く形 で。

## 依存とコマンド
- パッケージマネージャ: bun（npm/yarn 禁止）
- 開発: `bun dev` / テスト: `bun test`
- ビルド: `bun run build` / デプロイ: `bunx wrangler deploy`

「npm 禁止、bun を使う」 のように 代替品の禁止 をセットで書くと、無意識に npm を叩いてしまう事故を防げます。

セクション 5 — 注意点・禁止事項

「これをやられたら困る」 を箇条書きで。

## 注意点・禁止事項
- .env / .dev.vars は絶対にコミットしない
- DB マイグレーションは drizzle-kit 経由のみ（手書き SQL 禁止）
- 本番 D1 に直接クエリを流さない（必ず staging で検証）
- 古い `pages/` は廃止予定。新規実装は app/ のみ

禁止事項は「具体的な行為」で書く のがコツです。「セキュリティに注意」のような抽象表現は伝わりません。「.env をコミットしない」のように、実行可能なレベル まで具体化します。

実例 1 — Web アプリ（Next.js + Tailwind）

ここから 3 つの実例を見ます。1 つ目は 個人開発の Web アプリ を想定したテンプレです。

# CLAUDE.md

## プロジェクト概要
- 日記投稿サービス「dailylog」
- Next.js 15（App Router）/ Tailwind v4 / Drizzle ORM / Neon
- 認証: Better Auth / ホスティング: Vercel

## ディレクトリ構造
- app/(auth)/ — login、signup
- app/(app)/ — dashboard、entries
- components/ — 共有 UI
- lib/ — db.ts、auth.ts
- 触らない: .next/、node_modules/

## コーディング規約
- Server Component を default、必要なときだけ "use client"
- フォーム送信は Server Actions（API Route は作らない）
- Tailwind の任意値（`w-[123px]`）は禁止
- アイコンは lucide-react

## 依存とコマンド
- パッケージマネージャ: pnpm
- 開発: `pnpm dev` / テスト: `pnpm test` / 型: `pnpm typecheck`
- DB マイグレ: `pnpm db:generate` → `pnpm db:push`

## 禁止事項
- .env.local は絶対にコミットしない
- DB スキーマ変更は drizzle-kit 経由のみ
- 本番 Neon の main ブランチに直接接続しない
- Server Actions の引数は必ず Zod でバリデーション

30 行で 5 セクション全部入り の良いサイズ感です。機能が増えるたびに微調整します。

実例 2 — Python データ分析プロジェクト

2 つ目は データ分析業務向け のテンプレ。Jupyter Notebook 中心で進めるプロジェクトを想定します。

# CLAUDE.md

## プロジェクト概要
- 月次の売上データ分析パイプライン
- 入力: Salesforce CSV / Shopify 注文ログ JSON
- 出力: 月次レポート（HTML + PDF）、BI 用 Parquet
- 言語: Python 3.12（pandas / polars / matplotlib）

## ディレクトリ構造
- data/raw/ — 元データ（読み取り専用、書き換え禁止）
- data/processed/ — 前処理済み（Parquet 形式）
- notebooks/ — 探索用 Jupyter Notebook
- src/ — 本番パイプライン（再現性重視）
- tests/ — pytest

## コーディング規約
- 探索は notebooks/、本番化したら src/ に移植
- カラム名は snake_case 統一（元が CamelCase でも揃える）
- マジックナンバー禁止。閾値は src/constants.py に集約
- 可視化は matplotlib のみ（seaborn / plotly は使わない）

## 依存とコマンド
- パッケージマネージャ: uv
- 環境構築: `uv sync`
- Jupyter 起動: `uv run jupyter lab`
- テスト: `uv run pytest`
- 型チェック: `uv run mypy src/`

## 注意点・禁止事項
- data/raw/ は絶対に書き換えない
- Notebook の出力セルはコミット前にクリア（nbstripout）
- 「動いた Notebook を src/ にそのまま貼る」は禁止。リファクタしてから
- pandas で for ループ多用しない。ベクトル化を優先

データ分析特有の落とし穴（出力セルのコミット や raw データの汚染）が 禁止事項に明示 されている点に注目してください。これで Claude Code が「探索 Notebook をそのまま本番コード化」してしまう事故を防げます。

実例 3 — Go API プロジェクト

3 つ目は バックエンド のテンプレ。チームで開発する API を想定します。

# CLAUDE.md

## プロジェクト概要
- B2B SaaS の API サーバー（給与計算サービス）
- 言語: Go 1.25 / DB: TiDB（MySQL 互換）/ デプロイ: Cloud Run

## アーキテクチャ（3 層）
- internal/http/ — ハンドラ
- internal/service/ — 業務ロジック
- internal/repository/ — DB アクセス（sqlc 生成）

## ディレクトリ構造
- internal/repository/sqlcgen/ — 自動生成、手で書き換え禁止
- migrations/ — Atlas マイグレーション
- sql/queries/ — sqlc 用 SQL 定義
- openapi/openapi.yaml — API 仕様（単一ソース）

## 規約
- エラーは fmt.Errorf("...: %w", err) で wrap
- 関数名は GetXxx ではなく FetchXxx
- テストは table-driven、t.Run でサブテスト名を必ずつける

## コマンド
- 開発: `make dev-go`
- テスト: `go test ./...`
- マイグレ生成: `atlas migrate diff --env local`
- sqlc 再生成: `make sqlc-generate`
- OpenAPI から型生成: `make openapi-generate`

## API 変更時のチェックリスト（必ず守る）
1. openapi/openapi.yaml を更新
2. sql/queries/*.sql を更新
3. `make sqlc-generate` と `make openapi-generate` を実行
4. changelog.md にエントリ追加
5. テスト追加

## 禁止事項
- sqlcgen/ を手で編集（必ず sqlc 経由）
- マルチテナントのクエリで org_id を省略
- 本番 DB への直接 ALTER（Atlas 経由のみ）
- ログに個人情報を出力

「API 変更時のチェックリスト」 というセクションが特徴的です。これは「コードを書くときの規約」ではなく 「タスクを進めるときの手順」 であり、CLAUDE.md に書くことで Claude Code が 手順を自分でチェックしながら作業 してくれるようになります。

効果的な指示文の 7 原則

CLAUDE.md がしっかり書けていても、毎回のプロンプトが雑だと精度は落ちます。==CLAUDE.md = 常設の前提、プロンプト = 今回のタスク という役割分担です。次の 5-2 でテクニックを深掘りする前の、指針== として 7 原則を頭に入れてください。

原則 1 — 完成形を箇条書きで描写 — 「ユーザー管理画面を作って」だけだと Claude のセンス任せ。完成形を 5 行で描写すると一気に精度が上がります。「画像の代わりにテキストで画像を描く」のがコツ。

原則 2 — 制約と禁止事項を冒頭で — 「外部ライブラリ追加禁止」「既存の useToast() を使う」のような制約は プロンプトの冒頭で 宣言。「コードを書いたあとで実は……」では遅いです。

原則 3 — 出力フォーマットを指定 — 「Markdown で」「箇条書きで 5 行以内」「JSON で { "title": "", "items": [] } の形」のように形を決めると結果がブレません。

原則 4 — 既存ファイルを「お手本」として参照 — ゼロから書くより、「app/routes/users.tsx と同じパターンで」 と既存コードを指差すほうが精度は飛躍的に上がります。

原則 5 — タスクを段階に分ける — 大きすぎるタスクは 3〜5 ステップに分割 し、各ステップごとに動作確認。「最後にまとめてエラー祭り」を防げます。

原則 6 — 失敗時のリカバリーを伝える — 「テストが落ちたら止まって質問して」「ビルドが通らなかったら直前の状態に戻して」など、失敗時の挙動 を先回りで指定。

原則 7 — 確認ステップを挟む — 「実装する前に、まず設計案を 3 行で説明して」と挟むと方向性のすり合わせが楽になります。Claude Code は出力前に止まり、OK を出してから書き始めます。

プロンプト失敗パターン — Bad / Good 対比 5 セット

「悪い例 → 良い例」 を 5 セット並べます。自分のプロンプトと見比べてみてください。

セット 1 — 「いい感じに」族

ヘッダーをいい感じにして

ヘッダーのデザインを以下のように調整して。
- 高さ 64px → 56px
- ロゴと右側ナビの間隔を均等に
- スクロール時に背景を白から半透明グレーに
- モバイルではナビをハンバーガーに畳む

セット 2 — 「全部やって」族

ECサイトを作って

ECサイトの「商品一覧ページ」だけ作って。
- 商品データは public/products.json をモック
- カート機能は今回スキップ
- Tailwind、グリッド 3 列、商品ごとに画像 / 名前 / 価格 / ボタン

次は商品詳細ページに進む予定。

セット 3 — 「直して」族

バグ直して

ログイン画面のバグを直して。
症状: メールに大文字を含めるとログイン失敗
再現: test@Example.com で signup → test@example.com でログイン
期待: 大文字小文字を区別せずログイン成功
推測: signup 時に toLowerCase() し忘れ
ファイル: app/routes/login.tsx、lib/auth.ts

セット 4 — 「ファイル全部読んで」族

プロジェクト全体を見て、改善点を 100 個挙げて

パフォーマンス観点で、重そうなページを 1 つ選んで、
改善案を上位 5 つに絞って提案して。
候補: app/routes/dashboard.tsx、app/routes/reports.tsx

セット 5 — 「もうちょっと」族

もうちょっと良くして

さっきのコードに対して、以下 3 点だけ修正して。
1. forEach を for...of に置き換え
2. エラーメッセージを日本語に
3. 関数名 fetchUsers → loadUserList
それ以外は変更しないで。

CLAUDE.md と Sub-agent への指示の使い分け

第 7-8 章で扱う Sub-agent（子エージェント）の話を先取りします。Claude Code は Task ツール でサブタスクを別エージェントに丸投げできます。たとえば「リファクタ案を 3 つ調査」のような 探索系 を、メインのコンテキストを汚さず並列実行できます。

「毎回違うことは Sub-agent に」「毎回同じことは CLAUDE.md に」 というシンプルな線引きで迷いません。「コミットメッセージは日本語」は CLAUDE.md に、「今日のリリースノート用に過去 1 週間のコミットを英訳」は Sub-agent に。

CLAUDE.md のメンテナンス — いつ・どう更新するか

CLAUDE.md は 書いたら終わり ではなく、プロジェクトが進化するたびに 古くなっていくドキュメント です。次のような場面では必ず見直します。

• 新しい技術スタックを導入 したとき（Tailwind を追加、ORM 切替）
• コマンドが変わった とき（npm → bun、テストフレームワーク変更）
• ディレクトリ構造を変えた とき（pages → app に移行、モノレポ化）
• Claude Code が同じ間違いを 2 回 したとき（その挙動を禁止事項に追加）

特に最後の 「2 回間違えたら CLAUDE.md に追記」 は強力な習慣です。1 回の間違いは事故、2 回はパターン。パターンを CLAUDE.md で塞ぐ と、Claude Code が学習したかのように振る舞います。

更新は Claude Code 自身に頼める のが面白いところです。

最近の作業で、CLAUDE.md に書いておいたほうが良さそうな
ルールや知見はある？ 5 つ以内で挙げて、追記案を作って。

これを 週 1 回 投げると、Claude Code が直近の会話を振り返って改善案を出してくれます。AI に AI 用の取扱説明書を書かせる というメタな運用です。

チームでの CLAUDE.md 運用 — 3 層の使い分け

ここまでは個人開発を前提に書きましたが、チーム開発 ではもう一歩踏み込んだ運用が必要です。

==~/.claude/CLAUDE.md== にはあなた個人の好み（「コミットメッセージは日本語」など）を書きます。複数プロジェクトで共有したいパーソナル設定です。

==CLAUDE.md はリポジトリにコミットして チーム全員で共有== します。「うちのチームではこういう書き方をする」というルール集です。

==CLAUDE.local.md はあなたのマシンだけに置く 実験的な設定 や、ローカル DB の接続文字列のような 共有したくない情報== を入れます。

チーム CLAUDE.md を書くコツ

個人用と違って、「誰が読んでも同じように動く」記述 が必要です。

• 「私が好き」ではなく「チームで合意した」 ルールだけ書く
• 背景理由を 1 行添える（「Tailwind v4 採用は Vite Plugin が安定したため」）
• 変更履歴を末尾に残す と後から追える

GitHub の PR テンプレに ==- [ ] CLAUDE.md の更新は必要か確認した== の 1 行を入れておくと、ドキュメントが腐りません。

CLAUDE.md にまつわるよくある質問

Q1. CLAUDE.md は必須ですか？ — 必須ではないですが、本格的に使うなら 100% 書いたほうがいいです。書かないと毎回同じ説明を繰り返すことになり、トークン代と時間 が両方かかります。

Q2. README.md と何が違う？ — README は人間向け、CLAUDE.md は AI 向けです。README は説明調（「○○を実現するためのものです」）、CLAUDE.md は命令調（「○○を使ってください」）。両方を持っていて構いません。

Q3. 書く順番に決まりは？ — Claude Code は上から順に読むので、重要な禁止事項は冒頭近く に置くのが効果的です。「.env をコミットしない」のような絶対ルールはファイルの先頭付近に書きましょう。

Q4. CLAUDE.md だけで挙動を完全に制御できる？ — できません。CLAUDE.md は強い前提を作りますが、絶対の命令ではありません。プロンプト側で上書きすれば Claude Code はプロンプトに従います。絶対に守らせたいルールは CI のテスト や git hooks で機械的に弾く層も併用してください。

Q5. CLAUDE.md を書いても効いてないように見える — 3 つの可能性があります。読み込まれていない（ファイル名・配置を確認）、書き方が曖昧（「丁寧に」ではなく「○○を使う」と命令形に）、プロンプト側で打ち消されている（プロンプトと CLAUDE.md の矛盾を確認）。

まとめ

このレッスンで身につけた知識を 7 点で振り返ります。

1. CLAUDE.md は Claude Code の "脳" を育てるファイル。プロジェクトの前提・規約・コマンドを集約する場所
2. ==~/.claude/ / プロジェクト / CLAUDE.local.md の 3 層が 足し算== でマージされる
3. 5 セクション構造（概要 / 規約 / ディレクトリ / コマンド / 禁止）で書くと迷わない
4. Web アプリ / Python データ分析 / Go API の 3 実例を、ベースに使えばすぐ始められる
5. CLAUDE.md は「常設の前提」、プロンプトは「今回の具体」== — 両方で補完し合う
6. プロンプトの失敗パターン 5 つ（「いい感じに」「全部やって」「直して」「全部読んで」「もうちょっと」）には、必ず具体化で対処
7. CLAUDE.md は 書きっぱなしにせず、週 1 で見直し。Claude Code が 2 回間違えたパターンは即追記

<Quiz question="CLAUDE.md について正しい説明はどれですか？" options={["Claude Code がセッション開始時に自動で読み込み、プロジェクト全体の前提として扱う","Claude Code の API キーを保存するためのファイルで、必ず暗号化が必要","Claude Code に質問するたびに手動で読み込ませる必要がある"]} answer={0} />

<Quiz question="CLAUDE.md の運用で適切でないものはどれですか？" options={["本番 API キーや .env の中身を直接書く","Claude Code が 2 回同じ間違いをしたら、その挙動を禁止事項に追加する","個人の好みは ~/.claude/CLAUDE.md、チーム共通はリポジトリの CLAUDE.md に分ける"]} answer={0} />

次のレッスン 5-2: 効果的な指示のコツ では、CLAUDE.md で土台を整えた上で、毎回のプロンプト を磨くテクニックを 4 つのテクニックに分けて深掘りします。