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

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

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

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

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

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

配置場所と読み込み順序

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

配置場所	適用範囲	読み込み優先度	用途
~/CLAUDE.md	個人の全プロジェクト	低（最初に読み込み）	個人の好み、共通設定
./CLAUDE.md	リポジトリ全体	中	プロジェクト共通ルール
./src/CLAUDE.md	特定ディレクトリ配下	高（最後に読み込み）	モジュール固有ルール
.claude/CLAUDE.md	リポジトリ全体	中	CLAUDE.md と同等（別配置）

後から読み込まれたものが優先されます。 つまり、~/CLAUDE.md で「any型OK」と書いていても、./CLAUDE.md で「any型禁止」と書いていれば、プロジェクト内ではany型が禁止されます。

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が繰り返し生成する「的外れな出力」がないか（あればルールを追加する）

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 で始め、重要度別に分ける
• ルールは英語、ドメイン用語は対訳で書く
• 月次でメンテナンスし、チームの規約と同期させる

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