2025年初頭から Claude Code を毎日使用していますが、有用なアウトプットを得るための最も重要な要素はプロンプトエンジニアリングやテクニックではなく、コンテキストです。具体的には、プロジェクトのルートに配置された適切に作成された CLAUDE.md ファイルです。このファイル1つで、AI アシスタントがコードベースと戦う状態か、数ヶ月間チームに参加しているシニア開発者のように感じるかが変わります。

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 ファイルの構造

Next.js アプリ、Astro サイト、ヘッドレス CMS 統合、API サービスを含む数十のプロジェクト全体で CLAUDE.md ファイルを作成・改善した後、一貫して機能する構造に落ち着きました。

理想的な構造

# プロジェクト名

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

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

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

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

## 一般的なコマンド
ビルド、テスト、デプロイ、および dev コマンド。

## 重要なコンテキスト
コードからは明らかでないこと。

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

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

各セクションを詳しく見ていきましょう。

セクション別詳細解説

概要

これを最大 2～3 文に保ちます。Claude は製品ロードマップを必要としません。ドメインを理解して、文脈的に適切な決定を下すことができる必要があります。

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

テックスタック

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

## テックスタック
- **フレームワーク**: Next.js 15.1（App Router、RSC がデフォルト）
- **言語**: TypeScript 5.7（strict モード）
- **スタイリング**: Tailwind CSS v4（CSS ファースト設定）
- **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 コンポーネント
- named exports を使用、default exports は使用しない（pages/layouts を除く）
- すべてのデータ取得はサーバーコンポーネントで発生 — useEffect でデータ取得をしない
- API レスポンス型は lib/types/ に存在し、Sanity スキーマから自動生成される
- 条件付きクラスマージに `cn()` ユーティリティ（lib/utils.ts）を使用、テンプレートリテラルではない
- エラー境界は各主要ページセクションをラップ、ページ全体ではない
- すべてのフォーム処理は react-hook-form + zod 検証スキーマを使用
- コミットメッセージは Conventional Commits（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 の /docs/* リライトは Mintlify ドキュメントサイトにプロキシします。チームに確認せずに変更しないでください
- NEXT_PUBLIC_ で始まる環境変数のみがクライアント側で利用可能です。このように API シークレットを公開しないでください。

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

これはおそらく最も重要なセクションです。負の指示は AI モデルで非常に効果的です。

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

実例 CLAUDE.md

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

これは、特にヘッドレス CMS バックエンドを使用して Next.js サイトを構築するときにクライアントプロジェクトで使用する CLAUDE.md の削減版です。

# 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（RSC 付き）。lib/sanity/queries.ts の GROQ クエリ経由のサーバーコンポーネントでのすべてのデータ取得。クライアントコンポーネントは対話要素（モーダル、フォーム、カルーセル）のみ。

ページ：/（ホーム）、/about、/pricing、/blog、/blog/[slug]、/contact

## 慣例
- named exports のみ（page.tsx/layout.tsx を除く）
- コンポーネント：PascalCase、ファイルごとに 1 つ
- クラスマージ用 cn()
- すべてのフォーム検証用 Zod スキーマ
- データ取得に useEffect は使用しません。絶対に。

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

## してはいけないこと
- 正当な理由なく "use client" を追加しないでください
- 尋ねずにパッケージをインストールしないでください
- コンポーネントに default exports を使用しないでください
- マイグレーション確認なしに 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 ディレクティブを使用しないでください
- すべての画像に Astro の Image コンポーネントを使用し、適切な幅/高さを設定してください
- RSS フィードはコンテンツコレクションから自動生成されます。手動フィードロジックを作成しないでください

## してはいけないこと
- Astro コンポーネントが機能する場合は React コンポーネントを追加しないでください
- client:load ディレクティブを使用しないでください
- 画像サイズをスキップしないでください（CLS の原因となります）
- 既存フロントマターを更新せずにコンテンツコレクションスキーマを変更しないでください

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

この時点で多くの CLAUDE.md ファイルを確認しました。一貫して悪い結果につながるパターンを以下に示します。

間違い 悪い理由 修正方法
長すぎる（2000+ 語） コンテキストウィンドウトークンを消費し、重要な情報が失われる 800 語以下に保ちます。深掘りについては外部ドキュメントにリンクします。
曖昧すぎる（「React を使用する」） Claude がギャップを仮定で埋める 具体的にします：バージョン、パターン、正確なツール
負の指示がない Claude は慣例を破る「合理的な」ことをする 常に「してはいけないこと」セクションを含めます
README.md をコピー＆ペーストしている README はヒトのためで、AI コンテキストのためではない スクラッチから CLAUDE.md を書く（AI 固有のフレーミング）
機密データを含む API キー、スクラッチ .env.example の代わりに参照してください
更新しない プロジェクトは進化し、コンテキストファイルは進化しない スプリントごとまたは大規模なリファクター時に確認
矛盾した指示 「サーバーコンポーネントを使用する」+ useEffect 取得の例 1 人がファイルを所有し、一貫性を確認

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

Claude Code は、プロジェクトコンテキストファイルを読む唯一の AI ツールではありません。2025 年の状況は以下の通りです。

ファイル ツール 自動読み込み スコープ
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 ツールを使用する場合（2025 年は多くが使用しています）、単一の情報源を保守し、ツール固有のファイルから生成することを検討してください。簡単なビルドスクリプトは、マスターコンテキストファイルを正しい場所にコピーできます。

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

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

モノレポまたは大規模なコードベースの場合、サブディレクトリに CLAUDE.md ファイルを配置できます。Claude Code は操作中のディレクトリで最も固有のものを読みます。

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

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

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

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

  1. CLAUDE.md を自動で読み込んで開始
  2. 機能に取り組む
  3. コンテキストが重くなるときに /compact を実行
  4. 続行 — Claude は CLAUDE.md コンテキストと圧縮要約を保持

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

CLAUDE.md をバージョンコントロール内に保存します（コミットする必要があります）。ただし、個々の開発者は個人的な環境設定に ~/.claude/CLAUDE.md も使用します。

# 個人的な環境設定
- 短縮形より詳細な変数名を好みます
- コードを書く前に推論を示してください
- 変更を提案するとき、完全なファイル diff を表示します
- VS Code と Vim キーバインディングを使用します（IDE 固有のショートカットを提案しないでください）

この分離はチームファイルをクリーンで焦点を絞られたままに保ち、個人がエクスペリエンスをカスタマイズできるようにします。

影響度の測定

CLAUDE.md が機能していることをどのように知りますか？内部で追跡するメトリックは次のとおりです。

  • 初回試行精度：Claude の最初の応答が修正を必要としない頻度はどのくらいですか？優れた CLAUDE.md はこれを 80% 以上に取得します。
  • 慣例違反：Claude が コーディング標準を破った回数をカウントします。ゼロに向かうべき傾向。
  • コンテキスト質問：Claude が「これはどのフレームワークですか？」または「App Router を使用するべきですか？」と尋ね続ける場合、CLAUDE.md に情報がありません。
  • 復帰頻度：Claude の変更を却下したり、復帰したりする頻度。低い方が良い。

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

ヘッドレス CMS 開発サービスを通じてプロジェクトを構築している場合、テーラーメードの CLAUDE.md をすべてのプロジェクトハンドオフの一部として含めます。それは継続的な開発速度にとってそれほど重要です。

よくある質問

CLAUDE.md とは何か、どこに配置しますか？ CLAUDE.md はリポジトリのルートに配置するマークダウンファイルです。Claude Code は自動的に毎回セッション開始時に読み込みます。プロジェクトのアーキテクチャ、慣例、テックスタック、制約を理解するためです。AI コーディングアシスタント向けのオンボーディングドキュメントと考えてください。

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

CLAUDE.md をバージョンコントロールにコミットすべきですか？ 絶対に。CLAUDE.md は他のプロジェクトドキュメント同様、バージョン管理、確認、および最新に保つ必要があります。チーム全体が一貫した AI 動作から受益します。個人的な環境設定は代わりに ~/.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 をどのくらいの頻度で更新する必要がありますか？ 大規模なリファクター時に毎回スプリント時に確認します。フレームワークバージョンをアップグレードするたびに、主要な依存関係を変更するか、新しい慣例を採用する場合は、ファイルを直ちに更新します。古いコンテキストは非コンテキストより悪い。それは AI を積極的に誤解させるため。一部のチームは、インフラストラクチャ変更の PR チェックリストに CLAUDE.md レビューを追加しています。

CLAUDE.md は Claude ウェブ（claude.ai）で機能しますか？ いいえ。CLAUDE.md は特に Claude Code（CLI ベースのコーディングツール）によって読み込まれます。ウェブインターフェースまたは API 経由で Claude を使用している場合は、コンテキストを手動で貼り付けるか、Projects 機能を使用してナレッジファイルとして添付する必要があります。Claude Code の自動読み込みが、ファイルを強力にするものです。摩擦がなく、毎回セッション。 ```