CLAUDE.mdの書き方完全版｜AIエージェントにプロジェクト知識を渡す技術

Claude Codeに「ユーザー登録のバリデーション関数を作って」と指示したとき、プロジェクトではZodを使っているのにJoiで書かれたコードが返ってきた経験はないでしょうか。あるいは、命名規則がcamelCaseなのにsnake_caseで生成された、テストがJestで書かれたがプロジェクトはVitest — こうした「的外れな出力」を根本から防ぐのが CLAUDE.md です。

本記事では、CLAUDE.mdに何を書くべきか、どう書けば出力品質が変わるかを、良い例・悪い例のBefore/Afterとともに掘り下げます。Claude Codeの基本についてはClaude Code完全ガイドを参照してください。

2026年9月26日更新: 2026年9月25日公開の Claude Code v2.1.283 で、CLAUDE.md・skills・agents・commands に残った「古いモデル向けの書き方」を洗い出す /doctor prompt-audit が追加されました。v2.1.283 以降に更新したら、セッション内で一度実行して結果を確認してください。使い方は/doctor prompt-audit の節にまとめています。

結論 — CLAUDE.mdは「プロジェクト固有のシステムプロンプト」

CLAUDE.mdは、リポジトリ直下に配置するMarkdownファイルで、Claude Codeがセッション開始時に自動読み込みするプロジェクトの前提知識です。 LLMのシステムプロンプトをプロジェクト単位でカスタマイズする仕組み、と考えるとわかりやすいでしょう。

CLAUDE.mdなしのClaude Codeは「優秀だがプロジェクトを知らない外部コンサルタント」です。CLAUDE.mdを整備したClaude Codeは「プロジェクトの規約を熟知したチームメンバー」になります。

配置場所と読み込み順序

CLAUDE.mdは複数の場所に配置でき、読み込み順序と適用範囲が異なります。

API 開発でスキーマファーストに進める場合の書き分けは、Claude Code × API開発ガイドで設計から実装・テストまでの流れとあわせて解説しています。

複数の CLAUDE.md は上書きし合わず、すべてつなげて読み込まれます。 ディレクトリ階層では上位から順に並び、Claude Code を起動したディレクトリに近いファイルほど後ろに入ります。上書きではないため、~/.claude/CLAUDE.md に「any型OK」、./CLAUDE.md に「any型禁止」と矛盾する指示を書くと、どちらに従うかは保証されません。公式ドキュメントも、矛盾するルールは Claude がどちらかを任意に選ぶことがあるとしています（出典: Claude Code Docs - Memory）。個人設定とプロジェクトのルールが食い違わないように書き分けてください。

Gotcha: サブディレクトリのCLAUDE.mdが読み込まれないケース

サブディレクトリのCLAUDE.md（例: src/api/CLAUDE.md）は、Claude Codeがそのディレクトリのファイルを操作しているときにのみ読み込まれます。 プロジェクト全体に適用したいルールをサブディレクトリに置いても反映されないため注意が必要です。

必須セクション1 — 技術スタックとバージョン

プロジェクトで使用している言語、フレームワーク、主要ライブラリをバージョン付きで明記します。

Good

## Tech Stack
- Language: TypeScript 5.7 (strict mode enabled)
- Framework: Next.js 16 with App Router (NOT Pages Router)
- Styling: Tailwind CSS v4 with @plugin syntax
- UI: shadcn/ui v4 (Base UI primitives, NOT Radix)
- Animation: motion v12+ (formerly framer-motion, import from "motion/react")
- Testing: Vitest 3.x + Testing Library
- ORM: Prisma 6.x with PostgreSQL
- Package manager: pnpm (NOT npm, NOT yarn)

Bad

## 技術
React系のフロントエンドです。テストも書いています。

Bad → Good にすると何が変わるか

Badの状態で「フォームのバリデーション関数を作って」と指示すると、Claude Codeは一般的な知識に基づいてReact Hook FormとYupの組み合わせを生成するかもしれません。Goodの状態であれば、Zodバリデーション + TypeScript strictモードの型推論を活かしたコードが生成されます。

バージョン番号が特に重要です。 motion v12+ と書くことで、旧名の framer-motion ではなく motion/react からのインポートが生成されます。

必須セクション2 — コマンド一覧

テスト実行、ビルド、型チェック、lint、開発サーバー起動のコマンドを正確に記載します。Claude Codeはこれらのコマンドを実行してフィードバックループを回すため、コマンドが正確でないと自己修正が機能しません。

Good

## Commands
- Dev server: `pnpm dev` (Turbopack, port 3000)
- Build: `pnpm build`
- Test all: `pnpm test`
- Test single file: `pnpm test -- src/utils/calculate.test.ts`
- Test with coverage: `pnpm test -- --coverage`
- Type check: `pnpm typecheck` (runs tsc --noEmit)
- Lint: `pnpm lint` (ESLint + Prettier)
- Lint fix: `pnpm lint --fix`
- Format: `pnpm format`

Bad

## テスト
Vitestで動きます。`npm test` で実行してください。

Before / After

Before（コマンド不正確）: Claude Codeが npm test を実行 → pnpm プロジェクトなので lockfile not found エラー → Claude Codeが混乱して npm install を実行しようとする → package-lock.json が生成されて .gitignore に引っかかる

After（コマンド正確）: Claude Codeが pnpm test を実行 → テストが走る → 失敗があればコードを修正 → 再テスト → 全パス

パッケージマネージャの違いは些細に見えますが、ワークフロー全体に影響します。

必須セクション3 — コーディング規約

命名規則、ファイル構成、禁止される構文を具体的に列挙します。

Good

## Coding Conventions

### Naming
- Variables/functions: camelCase (`getUserById`, `isActive`)
- Types/interfaces: PascalCase (`UserProfile`, `SessionRepository`)
- Constants: UPPER_SNAKE_CASE (`MAX_RETRY_COUNT`)
- Files: kebab-case (`user-profile.ts`, `calculate-score.test.ts`)
- Booleans: is/has/should/can prefix (`isActive`, `hasPermission`)

### Structure
- One component per file
- Colocate tests: `foo.test.ts` next to `foo.ts`
- Use `interface` for object shapes, `type` for unions and utilities
- Imports order: external → internal → types

### Immutability
- Use spread operator for object/array updates (no direct mutation)
- Use `Readonly<T>`, `ReadonlyArray<T>` for function parameters
- Never mutate function arguments

### Error Handling
- Use async/await + try-catch (no .then chains)
- Treat catch `error` as `unknown`, narrow with `instanceof`
- Never swallow errors silently — log or rethrow

Bad

## 規約
きれいなコードを書いてください。変数名は適切に。

「きれいなコード」「適切な変数名」は、人によって解釈が異なります。Claude Codeに曖昧な指示を出すと、セッションごとに異なるスタイルのコードが生成され、コードベースの一貫性が崩れます。

必須セクション4 — 禁止事項（Do NOT）

Claude Codeにやってほしくないことを Do NOT で明示します。否定形の指示は肯定形よりも遵守率が高い傾向があります。

Good

## Do NOT
- Do NOT use `any` type — use `unknown` with type guards
- Do NOT use `as` type assertions — use type guards or Zod validation
- Do NOT use `!` (non-null assertion) — use `?? fallback` or early return
- Do NOT use `enum` — use union types with `as const`
- Do NOT use `console.log` in production code
- Do NOT modify files under `src/legacy/` (scheduled for removal in Q3)
- Do NOT add new npm dependencies without explicit approval
- Do NOT modify `.env` or `.env.*` files
- Do NOT use default exports — use named exports only
- Do NOT commit files with `// TODO: remove` comments

Bad

## 注意
気をつけてコードを書いてください。レガシーコードには触らないように。

Workaround: 禁止事項が無視される場合

禁止事項が多すぎると、後半の項目が無視されやすくなります。対策として、以下の構造が有効です。

## Do NOT (CRITICAL — violation = immediate rejection)
- Do NOT use `any` type
- Do NOT use `as` type assertions
- Do NOT modify `.env` files

## Do NOT (WARNING — should fix before commit)
- Do NOT use default exports
- Do NOT leave `// TODO: remove` comments

重要度別に分けることで、Critical項目の遵守率が上がります。

必須セクション5 — ドメイン用語

プロジェクト固有の用語を定義します。これがないと、Claude Codeは一般的な意味で用語を解釈し、変数名やコメントでプロジェクトの用語体系からズレたコードを生成します。

Good

## Domain Terms
- Session: A single facilitated learning period (NOT an HTTP session, NOT a browser session)
- Score: Calculated evaluation value (0-100) computed after a Session ends
- Facilitator: The person who creates and manages Sessions (NOT "admin", NOT "manager", NOT "teacher")
- Participant: A user who joins a Session (NOT "student", NOT "member", NOT "attendee")
- Round: A subdivision of a Session, typically 5-15 minutes (NOT "turn", NOT "phase")

Bad（最も多いパターン）

ドメイン用語セクションそのものが存在しない。

ドメイン用語がないと何が起きるか

「Sessionの一覧を取得するAPIを作って」と指示した場合、ドメイン用語がないClaude Codeは getActiveSessions() のような一般的な命名で実装します。プロジェクトでは listFacilitatedSessions() が正しいかもしれません。変数名の修正だけならまだ良いですが、Session の概念がHTTPセッションと混同されると、認証ロジックとの混乱が起きます。

CLAUDE.mdのよくある失敗パターン5つ

1. 長すぎる（300行以上）

CLAUDE.mdが長すぎると、重要な情報が後半に埋もれて無視されます。200行以内を目安にし、タスク固有の詳細ルールはSubagentsに分離してください。

2. 曖昧な表現が多い

「適切に」「きれいに」「良い感じに」はClaude Codeに伝わりません。定量的な基準（「50行以内」「3レベル以内」）に書き換えてください。

3. 矛盾する指示がある

「パフォーマンスを最優先してください」と「可読性を最優先してください」が両方書いてあると、Claude Codeは判断に迷います。優先度を明記してください。

4. 古い情報が残っている

半年前に廃止したライブラリの使用方法が書いてあると、Claude Codeがそのライブラリを使ったコードを生成します。定期的に更新してください。

5. 日本語だけで書いている

Claude Codeの内部処理は英語ベースで動くため、日本語のCLAUDE.mdはトークン消費が増え、解釈精度がわずかに下がる傾向があります。ルールは英語、ドメイン用語は日本語と英語の対訳で書くハイブリッド方式が推奨です。

## Domain Terms
- セッション / Session: 学習の1単位（HTTPセッションではない）
- 進行役 / Facilitator: セッションを管理する人

チーム運用のワークフロー

CLAUDE.mdの変更はPRレビュー必須

CLAUDE.mdの変更はチーム全員のClaude Code出力に影響するため、コード変更と同じくPRレビューを経由してください。

# .github/CODEOWNERS
CLAUDE.md @tech-lead
.claude/ @tech-lead

オンボーディング資料との同期

新人向けオンボーディング資料がある場合、CLAUDE.mdと内容を同期させてください。人間に「camelCaseで書け」と教えておきながら、Claude Codeには規約がないためPascalCaseで生成される — この不整合がコードベースの混乱を招きます。

階層構造の活用

モノレポや大規模プロジェクトでは、ルートのCLAUDE.mdに共通ルールを、各パッケージのCLAUDE.mdにパッケージ固有のルールを配置する階層構造が有効です。

monorepo/
├── CLAUDE.md                    # 共通: TypeScript, 命名規則, 禁止事項
├── packages/
│   ├── frontend/
│   │   └── CLAUDE.md            # フロント固有: React, Tailwind, コンポーネント規約
│   ├── backend/
│   │   └── CLAUDE.md            # バックエンド固有: Express, Prisma, API規約
│   └── shared/
│       └── CLAUDE.md            # 共有ライブラリ固有: 互換性ルール

月次メンテナンスの推奨

月に1回、以下の観点でCLAUDE.mdを見直すことを推奨します。

1. 廃止されたライブラリやツールの記述が残っていないか
2. 新しく追加された規約が反映されているか
3. ドメイン用語に追加すべきものがないか
4. Claude Codeが繰り返し生成する「的外れな出力」がないか（あればルールを追加する）

/doctor prompt-audit で古いモデル向けの書き方を洗い出す

/doctor prompt-audit（別名 /checkup prompt-audit）は、CLAUDE.md、skills、agents、commands に、古いモデル向けに書かれた指示の書き方が残っていないかを監査するコマンドです（出典: Claude Code changelog）。上の1〜4とは見る観点が違い、指示の書き方そのものを点検します。月次の見直しと合わせて実行してください。

/doctor prompt-audit

v2.1.283 のインストールファイルに含まれるこのコマンドの指示文を読むと、処理は Claude Code に同梱の claude-api スキルの prompt-audit に渡されます。公式のコマンド一覧は、/claude-api prompt-audit を「古いモデル向けに書かれた指示を指摘し、修正案を差分で提案する」ものと説明しています（出典: Claude Code Docs - Commands）。

同じ指示文から読み取れる監査の対象と扱いは次のとおりです。

プロジェクトの記述と、上位ディレクトリや ~/.claude/ のファイルの記述が食い違う場合は、プロジェクト外のファイルに修正案は出さず、指摘だけにとどめます。判定の基準になるのは、そのセッションで動いているモデルです。

同じ v2.1.283 では、古くなったパスや古いコマンド、互いに矛盾する指示ファイルがレポートの先頭に来るよう改善され、Claude Code が公式に説明している thinking のキーワードは修正対象から外されるようになりました（出典: Claude Code changelog）。本記事の失敗パターンのうち、「3. 矛盾する指示」の発見と、「4. 古い情報」のうちパスやコマンドの古さの発見に使えます。廃止したライブラリの記述などは、引き続き上の1〜4で確認してください。

注意点が2つあります。

• 同梱スキルを無効にしていると使えません。 claude-api スキルを skillOverrides でオフにしている場合や、disableBundledSkills 設定・CLAUDE_CODE_DISABLE_BUNDLED_SKILLS で同梱スキルをまとめて止めている場合は、監査は実行されず、その旨だけが表示されます。
• 修正案はそのまま適用せず、差分を読んでから反映してください。 CLAUDE.md の変更はチーム全員の出力に影響するため、前の節と同じく PR レビューを通すのが安全です。

/doctor prompt-audit の実行結果そのものは確認していません。この節の内容は、公式の changelog・コマンド一覧と、v2.1.283 のインストールファイルに含まれる指示文に基づいています。

CLAUDE.mdテンプレート（コピペ用）

以下は、新規プロジェクトで使えるテンプレートです。プロジェクトに合わせて内容を書き換えてください。

## Tech Stack
- Language: TypeScript X.X (strict mode)
- Framework: [Framework] with [Router/Pattern]
- Testing: [Test framework] + [Assertion library]
- Package manager: [pnpm/npm/yarn]

## Commands
- Dev: `pnpm dev`
- Build: `pnpm build`
- Test: `pnpm test`
- Test single: `pnpm test -- path/to/file.test.ts`
- Type check: `pnpm typecheck`
- Lint: `pnpm lint`

## Coding Conventions
- Variables/functions: camelCase
- Types/interfaces: PascalCase
- Files: kebab-case.ts
- [Add project-specific rules here]

## Do NOT
- Do NOT use `any` type
- Do NOT use `console.log` in production code
- [Add project-specific prohibitions here]

## Domain Terms
- [Term]: [Definition] (NOT [common misinterpretation])

よくある質問

まとめ — CLAUDE.mdは「AIを本気のチームメンバーにする」設定ファイル

CLAUDE.mdの有無と品質は、Claude Codeの出力品質に直結します。

• 5つの必須セクション（技術スタック・コマンド・規約・禁止事項・ドメイン用語）を必ず含める
• 具体的・定量的に書く — 曖昧な表現はAIに伝わらない
• 200行以内を目安に簡潔に維持する
• 禁止事項は Do NOT で始め、重要度別に分ける
• ルールは英語、ドメイン用語は対訳で書く
• 月次でメンテナンスし、チームの規約と同期させる。v2.1.283 以降は /doctor prompt-audit で古い書き方を洗い出す

まだCLAUDE.mdを作成していない場合は、本記事のテンプレートをそのままコピーして、プロジェクトの内容に書き換えるところから始めてください。