AI コーディング アシスタントが初めてリポジトリを開く。ファイル構造、依存関係、README をスキャンする。その後、既存のレイアウト システムを破壊するルーター設定を提案し、3 スプリント前に廃止したパッケージをインポートし、昨年チームが放棄したスタイルでテストを書く。アシスタントは馬鹿ではなく、盲目である。Claude Code、Cursor、Copilot、Cody — すべての AI ペア プログラマーは同じ壁に衝突する。コミット履歴だけではチームのコンテキストを読み取ることができない。プロジェクト ルートの単一の CLAUDE.md ファイルはこれを変える。これはアシスタントが慣例と戦うことと、あたかも何ヶ月間もあなたと共に出荷してきたシニア開発者のようにそれらを拡張することの違いである。しかし、ほとんどのチームは AI が実際に使用できない CLAUDE.md ファイルを作成している。

Claude Code にプロンプトを投げて、一般的で、間違った、または不満な結果を得ている場合、このガイドはあなたのためである。CLAUDE.md を構造化する方法、含めるもの、除外するもの、および Social Animal で出荷した本番プロジェクトの実例を共有します。

目次

CLAUDE.md とは何か、そしてなぜそれが重要なのか

CLAUDE.md はリポジトリのルートに配置するマークダウン ファイルで、Claude Code がセッションを開始するたびに自動的に読み取る。新しい AI ペア プログラマーのオンボーディング ドキュメントと考えてください。新しい開発者がチームに参加するとき、ノートパソコンを渡して「図を出してください」とは言いません。アーキテクチャを説明し、奇妙な部分を説明し、地雷を指摘します。CLAUDE.md も Claude に対して同じことをします。

なくても、Claude Code はファイル構造、package.json、および読むことになるどのファイルからかすべてを推測する必要があります。これはランダムなソース ファイルを読むだけでシステム全体を理解するように新入社員に頼むようなものである。いくつかはうまくいくが、みんなの時間を無駄にする仮定も立てます。

堅実な CLAUDE.md があれば、初回の試行でタスク完了の精度が約 60% から 90% 以上に向上するのを見ました。これは小さな改善ではありません — AI 補助開発が生産性の倍数であることと、イライラさせられる時間の無駄になることの違いである。

Claude Code がプロジェクト コンテキストを読む方法

Claude Code には、コンテキストを読み込むための特定の階層がある。これを理解することは、プロジェクト メモリを整理する方法に影響するため重要である。

コンテキスト読み込み順序

  1. ~/.claude/CLAUDE.md — グローバル環境設定（すべてのプロジェクトに適用）
  2. ./CLAUDE.md — リポジトリ ルートのプロジェクト レベル ファイル
  3. ./subdirectory/CLAUDE.md — ディレクトリ固有のオーバーライド
  4. .claude/settings.json — プロジェクト固有のツール権限と設定
  5. セッション コンテキスト — 現在の会話で Claude に伝えたこと

プロジェクト レベルの CLAUDE.md がほとんどの時間を費やす場所である。グローバル ファイルは個人的な環境設定に適しています（「関数型コンポーネントを好む」または「常に TypeScript strict モードを使用する」）が、本当の価値はプロジェクトごとのコンテキストにあります。

重要なこと: Claude Code はセッションの開始時に CLAUDE.md を読み取りますが、コンテキスト ウィンドウ スペースも制限されています。CLAUDE.md が 5,000 単語の不毛なドキュメント化である場合、実際のコード推論に使用できるトークンを消費しています。簡潔に。具体的に。すべての行はその場所を稼ぐ必要があります。

優れた CLAUDE.md ファイルの構造

Dozens of projects — Next.js apps、Astro sites、headless CMS integrations、API services — で CLAUDE.md ファイルを書いて改善した後、一貫性のある構造にたどり着きました。

理想的な構造

# プロジェクト名

## 概要
このプロジェクトが何をしているのか、誰のためにあるのかを説明する 1 段落。

## テック スタック
正確なバージョンとフレームワーク。

## アーキテクチャ
ピースがどのように組み合わさるか。

## 主要な慣例
コーディング標準、命名パターン、ファイル組織ルール。

## 一般的なコマンド
ビルド、テスト、デプロイ、開発コマンド。

## 重要なコンテキスト
コードから明らかでないもの。

## 既知の問題 / 注意点
避けるべき地雷。

## しないこと
AI がしてはいけない明示的なこと。

各セクションを掘り下げましょう。

セクション別の詳細説明

概要

これを最大 2〜3 文に保ちます。Claude は製品ロードマップは必要ありません — コンテキストに適切な決定を下すためにドメインを理解する必要があります。

## 概要
これは Acme Corp のマーケティング サイトで、サプライ チェーン管理向けの B2B SaaS プラットフォームです。サイトは静的に生成され、フォーム処理とリード キャプチャ用の動的 API ルートがあります。コンテンツはマーケティング チームによって Sanity CMS を通じて管理されます。

テック スタック

正確であること。「React」と言わないでください — バージョン、フレームワーク、レンダリング戦略を指定してください。これは Claude が React 18 で機能するが React 19 で破壊するパターンを提案したり、App Router 上にあるときに Pages Router を推奨することを防ぎます。

## テック スタック
- **フレームワーク**: Next.js 15.1 (App Router、デフォルトで RSC)
- **言語**: TypeScript 5.7 (strict モード)
- **スタイリング**: CSS ファースト設定を備えた Tailwind CSS v4
- **CMS**: ライブ プレビュー付き Sanity v3
- **デプロイ**: Vercel (本番環境とプレビュー環境)
- **パッケージ マネージャー**: pnpm 9.x
- **Node**: v22 LTS
- **テスト**: Vitest + Playwright
- **状態管理**: Zustand (最小限、クライアント側の UI 状態のみ)

アーキテクチャ

ほとんどの人はあまりにも少なく、またはあまりにも多くを書いています。システム設計ドキュメントを書いていません。Claude にメンタル モデルを与えています。

## アーキテクチャ
- `app/` — Next.js App Router ページとレイアウト
- `app/api/` — API ルート (フォーム送信、ウェブフック)
- `components/` — 共有 UI コンポーネント (アトミック設計: atoms/、molecules/、organisms/)
- `lib/` — ユーティリティ関数、API クライアント、型定義
- `lib/sanity/` — Sanity クライアント、クエリ (GROQ)、型生成
- `content/` — ブログ投稿用の MDX ファイル (フロントマターと共に配置)
- `public/` — 静的アセット (すべての画像に next/image を優先)

データ フロー: Sanity CMS → lib/sanity/queries.ts 内の GROQ クエリ → サーバー コンポーネント → クライアント コンポーネント (インタラクティビティが必要な場合のみ)

/blog/[slug]/preview を除くすべてのページはビルド時に静的に生成されます。これはドラフト モードを使用します。

主要な慣例

このセクションが最も多くの時間を節約します。それがなければ、Claude は一般的なベスト プラクティスに従い、チームの選択と矛盾するかもしれません。

## 主要な慣例
- コンポーネントは PascalCase で名前が付けられ、ファイルごとに 1 つのコンポーネント
- 名前付きエクスポートを使用し、デフォルト エクスポートは使用しない (ページ/レイアウトを除く)
- すべてのデータ フェッチはサーバー コンポーネントで発生します — useEffect でデータ フェッチに使用しないでください
- API レスポンス型は lib/types/ に存在し、Sanity スキーマから自動生成されます
- 条件付きクラスのマージには `cn()` ユーティリティ (lib/utils.ts) を使用し、テンプレート リテラルは使用しません
- エラー バウンダリは各主要ページ セクションをラップします。ページ全体をラップしません
- すべてのフォーム処理は react-hook-form + zod 検証スキーマを使用します
- コミット メッセージは従来のコミット (feat:、fix:、chore:) に従います

一般的なコマンド

これは基本的に見えるかもしれませんが、Claude Code は実際にこれらのコマンドを実行します。正しいものがわからない場合、推測しますが、多くの場合推測は間違っています。

## 一般的なコマンド
- `pnpm dev` — 開発サーバーを起動 (ポート 3000)
- `pnpm build` — 本番ビルド
- `pnpm lint` — ESLint + Prettier チェック
- `pnpm test` — Vitest ユニット テストを実行
- `pnpm test:e2e` — Playwright E2E テストを実行
- `pnpm sanity:typegen` — スキーマ変更後に Sanity 型を再生成
- `pnpm db:migrate` — Drizzle ORM マイグレーションを実行

重要なコンテキスト

これはClaude がコードを読むだけでは理解できないもの用です。ビジネス ロジック、外部制約、人間のレビュアーが 30 分かかって説明する必要があるもの。

## 重要なコンテキスト
- すべての CMS ページに ISR (revalidate: 3600) を使用します。絶対に必要でない限り、`force-dynamic` を使用しないでください。
- /api/revalidate の Sanity ウェブフックはオンデマンド再検証を処理します — 手動再検証ロジックを追加しないでください。
- 画像の最適化は Sanity の CDN (cdn.sanity.io) を通じて行われます。CMS コンテンツには next/image を使用しません。
- 認証は Clerk によって処理されます — カスタム認証フローを構築しないでください。
- /api/leads エンドポイントは Upstash Redis 経由のレート制限があります。レート制限ミドルウェアを削除しないでください。

既知の注意点

すべてのプロジェクトには奇妙なものがあります。ここに置くと Claude がそれをつまずきません。

## 既知の注意点
- Sanity の portable text レンダラーは v3.2 でネストされたリストにバグがあります。components/portable-text/list-fix.tsx でカスタム シリアライザーを使用します
- Tailwind v4 はモジュール CSS ファイルで `@apply` ディレクティブをサポートしていません — 代わりにインライン クラスを使用します
- vercel.json rewrites /docs/* は Mintlify ドキュメント サイトにプロキシします。チームに確認せずに修正しないでください。
- NEXT_PUBLIC_ で始まる環境変数はクライアント側で利用できる唯一のものです。API シークレットを決してこの方法で公開しないでください。

「しないこと」セクション

これはおそらく最も重要なセクションです。ネガティブな指示は AI モデルに対して非常に効果的です。

## しないこと
- 最初に尋ねずに新しい依存関係をインストールしないでください
- `any` 型を使用しないでください — 適切な型を見つけるか作成してください
- サーバー コンポーネントで実行できることのために新しい API ルートを作成しないでください
- 移行計画を確認せずに Sanity スキーマ ファイルを修正しないでください
- コンポーネントがブラウザ API またはイベント ハンドラーを本当に必要としない限り、`"use client"` を使用しないでください
- CSS ファイルを作成しないでください — すべて Tailwind ユーティリティ クラス
- CMS から取得する必要がある文字列をハードコードしないでください

実際の CLAUDE.md 例

例: Next.js マーケティング サイト

これはクライアント プロジェクトで使用する CLAUDE.md の削減版です。特に headless CMS バックエンドで Next.js サイトを構築する場合。

# Acme マーケティング サイト

## 概要
Acme (acme.com) のマーケティング ウェブサイト。Next.js 15、Tailwind v4 でスタイル設定、Sanity CMS からのコンテンツ。目標: すべてのページで LCP を 2 秒以下にします。

## テック スタック
Next.js 15.1 | TypeScript 5.7 strict | Tailwind v4 | Sanity v3 | Vercel | pnpm

## アーキテクチャ
App Router with RSC。lib/sanity/queries.ts の GROQ クエリを通じてサーバー コンポーネントのすべてのデータ フェッチ。クライアント コンポーネントはインタラクティブ要素 (モーダル、フォーム、カルーセル) のみです。

ページ: / (ホーム)、/about、/pricing、/blog、/blog/[slug]、/contact

## 慣例
- 名前付きエクスポートのみ (page.tsx/layout.tsx を除く)
- コンポーネント: PascalCase、ファイルごとに 1 つ
- クラス マージに cn() を使用
- すべてのフォーム検証用の Zod スキーマ
- データ フェッチに useEffect を使用しないでください。決して。

## コマンド
pnpm dev | pnpm build | pnpm lint | pnpm test

## しないこと
- 正当化なく「use client」を追加しないでください
- 質問なしでパッケージをインストールしないでください
- コンポーネントにデフォルト エクスポートを使用しないでください
- 移行計画を確認せずに sanity/schema/ ファイルを修正しないでください
- any 型を使用しないでください

例: Astro コンテンツ サイト

Astro プロジェクトの場合、CLAUDE.md はアーキテクチャ パラダイムが異なるため、多少異なって見えます。

# テック ブログ — Astro

## 概要
500 以上の記事を持つ開発者ブログ。静的ファースト、デフォルトでゼロ JS。カスタム コンポーネント付き MDX をコンテンツ用に使用します。

## テック スタック
Astro 5.x | MDX | Tailwind v4 | Cloudflare Pages にデプロイ | Content Collections v2

## アーキテクチャ
src/content/ — Zod で検証されたフロントマター付き MDX 記事
src/components/ — Astro コンポーネント (ゼロ JS) と React アイランド (インタラクティブ)
src/layouts/ — 基本レイアウト
src/pages/ — ファイルベースのルーティング

## 主要なルール
- デフォルトを Astro コンポーネント (.astro) にします。インタラクティビティが必要なアイランドに React を使用します。
- ビューポート外のインタラクティブ コンポーネントの場合は client:visible
- 重大でないインタラクティブ コンポーネントの場合は client:idle
- 絶対に必要でない限り client:load ディレクティブを使用しないでください
- すべての画像は適切な width/height で Astro の Image コンポーネントを使用します
- RSS フィードはコンテンツ コレクションから自動生成されます — 手動フィード ロジックを構築しないでください

## しないこと
- Astro コンポーネントで機能する場合は React コンポーネントを追加しないでください
- client:load ディレクティブを使用しないでください
- 画像寸法をスキップしないでください (CLS を引き起こします)
- 既存のフロントマターを更新せずにコンテンツ コレクション スキーマを修正しないでください

AI コンテキストを台無しにする一般的なミス

これまでに多くの CLAUDE.md ファイルを見直してきました。一貫して悪い結果につながるパターンは次のとおりです。

ミス なぜそれが傷つくのか 修正
長すぎます (2000+ 単語) コンテキスト ウィンドウ トークンを消費し、重要な情報が失われます 800 単語以下に保ちます。深いダイブについては外部ドキュメントにリンクします。
あまりにも曖昧です (「React を使用します」) Claude はギャップを一般的なベスト プラクティスで埋めます 具体的にします: バージョン、パターン、正確なツール
ネガティブな指示がない Claude は「妥当な」ことをします。これはあなたの規則を破ります 常に「しないこと」セクションを含めます
README.md をコピーペーストする README は人間用です。AI コンテキスト用ではありません 最初から CLAUDE.md を書く。AI 固有のフレーミング付き
機密データを含める API キー、文脈内のシークレット CLAUDE.md にシークレットを入れないでください。代わりに .env.example を参照してください。
更新しない プロジェクトは進化し、コンテキスト ファイルは進化しません 毎回スプリントまたは主要なリファクターで CLAUDE.md を見直してください。
矛盾した指示 「サーバー コンポーネントを使用」 + useEffect フェッチの例 1 人が所有するファイル。一貫性のための確認

CLAUDE.md と他の AI コンテキスト ファイル

Claude Code は、プロジェクト コンテキスト ファイルを読み取る唯一の AI ツールではありません。2026 年の景観は次のようなものです:

ファイル ツール 自動読み取り スコープ
CLAUDE.md Claude Code はい、セッション開始時 プロジェクト全体
.cursorrules Cursor はい、ファイルを開く時 プロジェクト全体
.github/copilot-instructions.md GitHub Copilot はい、Copilot Chat で リポジトリ全体
.windsurfrules Windsurf (Codeium) はい プロジェクト全体
AGENTS.md OpenAI Codex CLI はい プロジェクト全体
.ai/context.md カスタム規則 いいえ (手動参照) 異なります

良いニュース: ほとんどのコンテンツは転送可能です。堅実な CLAUDE.md を書いたら、それを .cursorrules または copilot-instructions.md に変換するのに約 5 分かかります。構造と情報は同じです — ファイル名と軽微なフォーマットのみが異なります。

チームが複数の AI ツール (2026 年の多くの場合) を使用する場合は、真実の単一のソースを保守し、ツール固有のファイルを生成することを検討してください。シンプルなビルド スクリプトは、マスター コンテキスト ファイルをすべての適切な場所にコピーできます。

大規模プロジェクトの高度なパターン

ネストされた CLAUDE.md ファイル

モノレポ または大規模なコードベースの場合、サブディレクトリに CLAUDE.md ファイルを配置できます。Claude Code は、作業しているディレクトリの最も具体的なものを読み取ります。

project/
├── CLAUDE.md              # グローバル プロジェクト コンテキスト
├── apps/
│   ├── web/
│   │   └── CLAUDE.md      # Web アプリ固有コンテキスト
│   └── api/
│       └── CLAUDE.md      # API 固有コンテキスト
├── packages/
│   └── ui/
│       └── CLAUDE.md      # デザイン システム コンテキスト

ルート CLAUDE.md は共有アーキテクチャと規則をカバーします。各ネストされたファイルはそのパッケージの詳細を追加します。

/compact による動的コンテキスト

Claude Code の /compact コマンドは現在の会話を要約し、コンテキスト スペースを解放します。長いセッションでは、うまくいくパターンを見つけました:

  1. CLAUDE.md が自動的に読み込まれた状態で開始
  2. 機能を実行
  3. コンテキストが重くなったら /compact を実行
  4. 継続 — Claude は CLAUDE.md コンテキストと圧縮されたサマリーを保持

チーム共有 対 個人用コンテキスト

CLAUDE.md はバージョン管理に保存します (コミットされるべき)。しかし、個々の開発者は個人的な環境設定のために ~/.claude/CLAUDE.md も使用します:

# 個人設定
- 略語より詳細な変数名を優先
- コードを書く前に理由を表示
- 変更を提案するときは、完全なファイル diff を表示
- VS Code と Vim キーバインディングを使用します (IDE 固有のショートカットを提案しないでください)

この分離により、チーム ファイルは清潔で焦点を絞られたままになり、個人が自分の経験をカスタマイズできるようになります。

影響の測定

CLAUDE.md が機能しているかどうかをどのように知っていますか? 内部で追跡するメトリクス:

  • 初回の試行精度: Claude の最初の応答が 0 の修正が必要な頻度はどのくらいですか? 優れた CLAUDE.md はこれを 80% 以上にします。
  • 規則違反: Claude があなたのコーディング標準を破る回数を数えます。ゼロに向かって傾向があるべき。
  • コンテキスト質問: Claude が「これのフレームワークは何ですか?」または「App Router を使うべきですか?」を続けて尋ねた場合、CLAUDE.md に情報が足りません。
  • 取り消し頻度: Claude の変更を拒否またはリバースする必要がある頻度。低いほど良い。

中規模スタートアップのあるチームは、CLAUDE.md に 1 時間投資した後、平均 AI 補助タスク時間を 12 分から 4 分に短縮したと報告しました。それは 1 つのファイルからの 3 倍の改善です。

headless CMS 開発サービスを通じてプロジェクトを構築する場合、カスタマイズされた CLAUDE.md をすべてのプロジェクト ハンドオフの一部として含めます。進行中の開発ベロシティにとってそれほど重要です。

よくある質問

CLAUDE.md とは何ですか、どこに行きますか? CLAUDE.md はリポジトリ ルートに配置するマークダウン ファイルです。Claude Code はセッションの開始時に自動的にそれを読み取り、プロジェクトのアーキテクチャ、規則、テック スタック、制約を理解します。AI コーディング アシスタント専用に書かれたオンボーディング ドキュメントと考えてください。

CLAUDE.md ファイルはどのくらいの長さにすべきですか? 300〜800 単語を目指します。短いファイルは重要なコンテキストを逃していますが、1,000 単語を超えるものはコンテキスト ウィンドウを消費し始めます — 実際のコード推論に使用する方がよいスペース。簡潔で具体的。すべての文はその場所を稼ぐ必要があります。さらに深さが必要な場合は、埋め込むのではなく外部ドキュメントにリンクしてください。

CLAUDE.md をバージョン管理にコミットすべきですか? 絶対に。CLAUDE.md は他のプロジェクト ドキュメント — バージョン、レビュー、最新状態に保つようにされるべきです。個人的な環境設定は代わりに ~/.claude/CLAUDE.md に入ります。各開発者のマシンでローカルのままです。

CLAUDE.md は .cursorrules とどう違いますか? コンテンツはほぼ同じです — どちらもプロジェクト コンテキストを AI コーディング ツールに提供します。違いはどのツールがそれを読むかです。CLAUDE.md は Claude Code (Anthropic の CLI ツール) 用で、.cursorrules は Cursor IDE 用です。両方のツールを使用する場合は、1 つの真実のソースを保持し、ツール固有のフォーマット用に両方のファイルにコピーします。

CLAUDE.md の最も重要なセクションは何ですか? 「しないこと」セクション。ネガティブな指示は AI モデルに対して不釣り合いに効果的です。Claude が何をすべきかを避けるべきこと — any タイプを使用しないでください。不必要に "use client" を追加しないでください。質問なしで新しいパッケージをインストールしないでください — は、良いバンリストがポジティブな指示のページを節約します。

コード以外のプロジェクトに CLAUDE.md を使用できますか? はい。CLAUDE.md は Claude Code と相互作用するプロジェクトで機能します。ドキュメント リポジトリ、インフラストラクチャ-コード プロジェクト、データ分析パイプラインに対する有効なものを見てきました。原則は同じです: Claude に良い決定をするためにプロジェクトの特定のコンテキストを与えます。

CLAUDE.md をどのくらい頻繁に更新すべきですか? すべての主要なリファクターで、少なくともスプリントに 1 回見直してください。フレームワーク バージョンをアップグレードするか、重要な依存関係を変更するか、新しい規則を採用する場合は、ファイルを直ちに更新します。古いコンテキストは、AI を積極的に誤解させるため、コンテキストがないよりも悪いです。一部のチームは、インフラストラクチャ変更のための PR チェックリストに CLAUDE.md レビューを追加しました。

CLAUDE.md は Claude on the Web (claude.ai) で機能しますか? いいえ。CLAUDE.md は Claude Code、CLI ベースのコーディング ツールによって読み取られます。Web インターフェースまたは API を通じて Claude を使用する場合、コンテキストを手動で貼り付けるか、Projects フィーチャーを使用して知識ファイルとしてアタッチする必要があります。Claude Code の自動読み込みは、ファイルを非常に強力にするもの — ゼロの摩擦、すべてのセッション。