ほとんどの CLAUDE.md は同じ理由で失敗する: プロジェクトを抽象的に説明して、詳細は Claude が判断するだろうと期待している。Claude は詳細を判断しない。明示的な指示に従う。
このガイドは100以上の本番リポジトリの CLAUDE.md を分析して抽出した12の具体的なパターンだ。コードスタイルの一貫性向上、リジェクトの減少、セッションをまたいだコンテキスト再説明の削減——実際に Claude の挙動を改善するパターンだけを集めた。
分析対象は著名なオープンソースプロジェクト（Next.js、Deno、LangChain、Excalidraw）に加えて、Claude Code コミュニティの開発者が共有した数十のプライベートコードベースを含む。
なぜほとんどの CLAUDE.md は効果が薄いのか
パターンの前に、何が失敗を引き起こすかを理解する。
問題1: 指示ではなくプロジェクト説明。 最も多い CLAUDE.md の失敗は、Claude 向けのルールブックではなく README を書くことだ。「TypeScript と PostgreSQL を使った Next.js アプリ」はプロジェクトが何かを伝えるが、どう作業するかは伝えない。Claude はすでにファイルからスタックを推測できる。
問題2: 結果を伴わないルール。 「既存のコードスタイルに従う」は Claude が実行できるルールではない。サンプルからスタイルを推測することを求めるが、それは一貫性がない。有効な等価表現: 「文字列はシングルクォート、セミコロンなし、2スペースインデント。既存ファイルのパターンを正確にマッチさせる」。
問題3: 有用性を超えた長さ。 2000行を超える CLAUDE.md がある。その長さでは最重要ルールが埋もれる。Claude の注意は長いドキュメント末尾の低優先度項目で劣化する。網羅性より容赦ない編集が勝る。
問題4: 動的なコードベースに対する静的なファイル。 CLAUDE.md は手動でメンテナンスされる。テストフレームワークが Jest から Vitest に変わって CLAUDE.md を誰も更新しなければ、Claude は npx jest コマンドを生成し続ける。
問題5: 否定空間の欠如。 何をすべきかのルールは必要だ。だが何をすべきでないかのルールは往々にしてより高いインパクトを持つ。優れた CLAUDE.md はアンチパターン——このコードベース固有の Claude が間違えがちな具体的な事柄——に実質的なスペースを割く。
パターン1: コンテキストより先にコマンドを置く
トップリポジトリで最も普遍的に実践されているパターンは、コマンドを冒頭に置くことだ。ビルド・テスト・lint コマンドは、散文的な説明より前にトップに来るべきだ。
# Project
## Commands
- Install: `pnpm install`
- Dev server: `pnpm dev`
- Build: `pnpm build`
- Test: `pnpm test`
- Test single file: `pnpm test path/to/file.test.ts`
- Lint: `pnpm lint`
- Type check: `pnpm typecheck`
- Format: `pnpm format`なぜ効くか: Claude Code は変更の検証・テスト実行・型チェックのためにコマンドを常に実行する。コマンドが300行目に埋まっていると、Claude は推測するか（間違える）、package.json を探索するためにコストの高いツール呼び出しを使う。冒頭への配置でエラーとトークン消費が減る。
アンチパターン: コマンドを末尾の「Technical Details」セクションに置く。オープンソースで最も効果的な CLAUDE.md のひとつである Deno の CLAUDE.md は、他のコンテンツより前にビルドとテストコマンドから始まる。
パターン2: 境界を明示的に定義する
分析した効果的な CLAUDE.md のほぼすべてに、Claude が触れてはいけないものの専用セクションがあった。曖昧な警告ではなく、具体的なディレクトリ・ファイル・操作。
## Off-Limits
### ディレクトリ（絶対に変更しない）
- `generated/` — protobuf コンパイルの自動生成物
- `dist/` — ビルド出力
- `vendor/` — Go の vendored 依存関係
- `.github/workflows/` — CI パイプライン、人間のレビューが必要
### 操作（明示的な指示なしに実行しない）
- データベースマイグレーションの実行
- `package.json` の依存関係バージョン変更
- TypeScript 設定の変更
- `package.json` への新しい npm スクリプト追加
### ファイル（絶対に削除しない）
- `*.lock` ファイル — lockfile の変更は必ずコミット
- `.env.example` — 環境セットアップのテンプレート具体性が機能させる。「生成済みファイルに触るな」は Claude にどのファイルが生成物か推測させる。「generated/ に触るな」は明確だ。
いくつかのリポジトリ（Excalidraw を含む）は各境界に短い理由を添える。「protobuf コンパイルの自動生成物」は規則が存在する理由を伝え、エッジケースが生じたときの遵守率を高める。
パターン3: よくある失敗モードのためのアンチパターンブロック
どのコードベースにも、AI コーディングアシスタントが確実に間違えがちな固有のパターンがある。優れた CLAUDE.md ファイルはそれを明示的に記述する。
TypeScript プロジェクトの例:
## Anti-Patterns（絶対にやらないこと）
- `any` 型なし — `unknown` を使い型ガードで絞り込む
- `as` 型アサーションなし — アサーションではなく絞り込みで
- `// @ts-ignore` なし — 根本的な型の問題を修正する
- 本番コードに `console.log` なし — Logger サービスを使う
- JSX のインラインイベントハンドラなし — 名前付き関数に抽出する
- `localStorage` への直接アクセスなし — ストレージサービス抽象化を使うGo プロジェクトの例:
## Anti-Patterns
- 真に回復不能な状態（起動時設定エラー）以外での `panic` なし
- `init()` 関数なし — main での明示的な初期化
- グローバル変数なし — 依存性注入を使う
- エラーメッセージ: 小文字、末尾の句読点なし
- コンテキスト伝播: 常に ctx を最初の引数として渡す、構造体に格納しないこのパターンはほとんどの平均的な CLAUDE.md には存在しないが、高パフォーマンスなほぼすべての CLAUDE.md に存在する。「init() 関数なし」の具体性は「Go のイディオムに従う」を実際の運用で大きく上回る。
パターン4: テストの契約
テストをどう書き、実行し、検証するかは、CLAUDE.md で指定する中で最も高いレバレッジを持つ事柄のひとつだ。AI 生成テストは往々にして表面的だったり、挙動ではなく実装の詳細をテストしたりする。明示的なテスト契約がこれに対処する。
## Testing
### フレームワーク
コンポーネントテストに Vitest + React Testing Library、API モックに MSW。
### テストする対象
- パブリック API の挙動（入力→出力）、実装の内部ではない
- ユーザーに見えるエラーを引き起こすエッジケース
- エラーパスと境界条件
- データベース操作の統合テスト（ロールバックするテストトランザクション使用）
### テストしない対象
- プライベート関数 — パブリックインターフェースを通してテストする
- リファクタリング中に変わりうる実装の詳細
- サードパーティライブラリの内部
### 規約
- テストファイルはソース横に: `auth.ts` → `auth.test.ts`
- 関連テストのグループ化に `describe` ブロック
- テスト名: 「should [期待される挙動] when [条件]」
- コミット済みコードで `test.only` や `describe.only` は使わない
### テストの実行
- 全スイート: `pnpm test`
- ウォッチモード: `pnpm test --watch`
- 単一ファイル: `pnpm test src/auth/auth.test.ts`
- カバレッジ: `pnpm test --coverage`パターン5: 実行可能なルールとしてのコードスタイル
曖昧なスタイルガイダンス（「既存のコードスタイルに従う」）はほぼ無意味だ。効果的な CLAUDE.md ファイルはスタイルを明示的なルールとして記述する。
## Code Style
### フォーマット（Prettier が強制、オーバーライドしない）
- 文字列はシングルクォート
- セミコロンなし
- 2スペースインデント
- 行長100文字
- 複数行構造の末尾カンマ
### 命名
- ファイル: kebab-case（`user-service.ts`、`UserService.ts` や `userService.ts` ではない）
- React コンポーネント: PascalCase ファイルに PascalCase
- フック: `use` プレフィックスの camelCase（`useAuthState`）
- 型/インターフェース: PascalCase、`I` プレフィックスなし（`User`、`IUser` ではない）
- 定数: モジュールレベルのプリミティブにのみ SCREAMING_SNAKE_CASE
### インポート
- グループ: 外部パッケージ → 内部パッケージ → 相対インポート
- ユーティリティファイルからのデフォルトエクスポートなし — 名前付きエクスポートを使うPrettier や Black でフォーマットを強制するリポジトリはこのセクションを大幅に短縮できる。「コミット前に prettier --write を実行する」で Claude は制約を内面化する。
パターン6: コンテキストとしてのアーキテクチャ
高品質な CLAUDE.md ファイルには、ルールが何かだけでなくなぜ存在するかを Claude が理解できるだけのアーキテクチャコンテキストが含まれる。
## Architecture
ヘキサゴナルアーキテクチャ（ポートとアダプタ）。主な含意:
- ドメイン層（`src/domain/`）はインフラ層（`src/infra/`）をインポートしてはいけない
- `src/application/` のユースケースがドメインオブジェクトを調整する
- インフラアダプタはドメインで定義されたインターフェースを実装する
### データフロー
Request → Router → Controller → Use Case → Domain Service → Repository Interface
↑ HTTP アダプタ ↑ 調整 ↑ ドメインロジック ↑ インフラアダプタ
### 状態管理
- サーバー状態: React Query（データフェッチに useEffect は使わない）
- クライアント UI 状態: Zustand ストア、機能ごとに1つ
- フォーム状態: React Hook Form（フォーム状態を手動管理しない）このレベルのコンテキストは特定の失敗モードを防ぐ: ローカルに正しいが アーキテクチャ的に間違った変更をする Claude。ドメイン/インフラ境界の説明なしに、Claude はドメインコードにインフラアダプタを直接インポートするかもしれない。
パターン7: PR チェックリストパターン
高パフォーマンスな CLAUDE.md ファイルのいくつかには、タスクが完了とみなせる前に Claude が確認すべき明示的な基準が含まれる。
## タスク完了前の確認事項
- [ ] テストが通る: `pnpm test`
- [ ] TypeScript エラーなし: `pnpm typecheck`
- [ ] lint エラーなし: `pnpm lint`
- [ ] 新しい `any` 型が追加されていない
- [ ] すべての新しいパブリック関数に JSDoc コメントがある
- [ ] エラーパスが処理されている（未処理の Promise リジェクションなし）
- [ ] config や定数に属すべきハードコードされた値がないこれはコマンドを列挙するだけとは質的に異なる。作業を戻す前に Claude が自己検証することを期待し、「完了」の定義を明確にする。このパターンを使うリポジトリはコードレビューの往復が少ないと報告している。
パターン8: 依存関係ポリシー
AI コーディングアシスタントは何も考えずに依存関係を追加しがちだ。CLAUDE.md の1行がほとんどを防げる:
## Dependencies
明示的に依頼された場合を除き、新しい npm パッケージを追加しない。
タスクが新機能を必要とする場合、以下を優先する:
1. package.json に既にある既存パッケージを使う
2. 標準ライブラリ / Web API で実装する
3. 依存関係を追加する前に確認する
禁止パッケージ: moment.js（date-fns を使う）、lodash（ネイティブメソッドを使う）、request（fetch を使う）「禁止パッケージ」セクションはレガシー依存関係から移行中のコードベースで特に価値がある。それなしには、Claude は何百万ものリポジトリで使われているという理由で lodash に手を伸ばし続ける。
パターン9: 環境と設定
## Environment
### ローカルセットアップ
- `.env.example` を `.env.local` にコピーしてローカル開発用にする
- DB: PostgreSQL 16、接続文字列は `DATABASE_URL`
- Redis: セッションストレージに必要、env に `REDIS_URL`
### 環境変数（絶対にハードコードしない）
- `.env` ファイルをコミットしない
- 認証情報・トークン・接続文字列をハードコードしない
- `src/config/` の設定サービス経由で `process.env.VARIABLE_NAME` を使うこのセクションは最も危険な AI コーディングミス——ハードコードされた認証情報や環境固有の値のバージョン管理へのコミット——を防ぐ。
パターン10: バージョン固定と非推奨メモ
## Tech Stack（固定バージョン）
- Node.js: 22.x (LTS) — v23+ の機能は使わない
- TypeScript: 5.7 — 有効な機能は tsconfig.json を参照
- React: 19.x — 適切な場所で新機能（Server Components、use() フック）を使う
## 非推奨パターン（使わない）
- `getServerSideProps` — React Server Components を使う
- データフェッチに `useEffect` — React Query を使う
- クラスコンポーネント — 関数コンポーネントのみ
- Moment.js — date-fns を使う
- `var` — `const` または `let` を使うバージョン固定により、コードベースがサポートしない新しいバージョンの機能を Claude が使うことを防ぐ。非推奨リストは App Router と Pages Router が共存する Next.js プロジェクトで特に価値がある——明示的なガイダンスなしに Claude は両方のパターンを混在させがちだ。
パターン11: モノレポ固有のスコーピング
モノレポでは、ルートからのインポートを持つパッケージ別 CLAUDE.md ファイルが最も効果的だった。
ルート CLAUDE.md:
# Monorepo
4パッケージの pnpm workspaces。
## Workspace コマンド
- 全インストール: `pnpm install`
- 全ビルド: `pnpm -r build`
- 全テスト: `pnpm -r test`
- 特定パッケージ: `pnpm --filter @org/package-name <command>`
## クロスパッケージルール
- 共有型は `@org/types` に — 型定義を重複させない
- パッケージ間の循環依存を作らない
@packages/web/CLAUDE.md
@packages/api/CLAUDE.md
@packages/shared/CLAUDE.md各パッケージの CLAUDE.md にはパッケージ固有のルールのみ含める。インポートシステムが乖離を防ぐ: packages/api/CLAUDE.md を更新すれば、すべてのエージェントが更新済み API ルールを自動的に受け取る。
パターン12: 「最小変更」原則
多くの効果的な CLAUDE.md 全体で見つかった最もインパクトのある1行:
## Working Style
最小限の的を絞った変更を優先する。現在のタスクのスコープ外のコードをリファクタリングしない。
改善できそうなコードを見つけたら言及するが、依頼されない限り変更しない。これはよくある不満を防ぐ: 1つのバグを直すよう頼んで15ファイルに触れた diff が返ってくること。最小変更原則でレビュー可能な diff と限定されたリグレッションを保つ。
まとめ: 完全な例
12のパターンをすべて取り入れた、現実的なサイズの CLAUDE.md（50行で何も言わないでも、誰も読まない2000行でもない）:
# Project
SaaS 分析ダッシュボード。React 19 + TypeScript、Go API、PostgreSQL。
## Commands
- Install: `pnpm install`（ルート）、`go mod download`（api/）
- Frontend dev: `pnpm --filter web dev`
- API dev: `cd api && go run ./cmd/server`
- Test frontend: `pnpm --filter web test`
- Test API: `cd api && go test ./... -race`
- Lint all: `pnpm lint && cd api && golangci-lint run`
## Architecture
`apps/web/` にフロントエンド、`api/` に Go API、`db/` に共有 DB スキーマ。
フロントエンドは `apps/web/src/api/` の生成 OpenAPI クライアント経由でのみ API と通信する。
## Off-Limits
- `api/generated/` — `make generate` で再生成される OpenAPI クライアント
- `db/migrations/` — `make migration name=description` で新規作成
- `apps/web/src/api/` — 生成 OpenAPI クライアント
## Anti-Patterns（絶対にやらないこと）
- フロントエンド: `any` なし、データフェッチに `useEffect` なし（React Query を使う）
- API: ハンドラで `panic` なし、グローバル変数なし、context は常に最初の引数
- 両方: ハードコードされた値なし
## Testing
- フロントエンド: Vitest + React Testing Library。挙動をテスト、実装ではない。
- API: 標準 Go テスト。テーブル駆動テスト。
- タスク完了前: tests + typecheck + lint 全部通過
## タスク完了前の確認事項
- [ ] テスト通過
- [ ] 型エラーなし
- [ ] lint エラーなし
- [ ] 最小 diff — 依頼されていないリファクタリングなし55行。具体的で、スコープ内で完全で、メンテナンスできる。会社の歴史とチーム構造を説明する500行の CLAUDE.md と比較して — 55行版が毎回より良い挙動をもたらす。
関連リソース
プロジェクトタイプ別のコピーペースト出発点は 用途別 CLAUDE.md テンプレート10選 を参照。CLAUDE.md と AGENTS.md・CONVENTIONS.md の比較は 3フォーマット比較ガイド で。Python 固有のパターンは Python 向け CLAUDE.md ガイド で詳しく解説している。