CLAUDE.md 完全攻略

CLAUDE.mdに関するアドバイスの多くは、このファイルの役割を誤解している。よく言われるのは、Claude をコードベースにオンボーディングするために使うべきだということだ。技術スタックをリストアップする。主要なコマンドを書き込む。フォルダ構成を概説する。60行以内に収めるよう推奨するガイドもある。

そのような考え方は、このファイルの本来の目的を読み違えている。

CLAUDE.mdはClaudeの動作を制御するファイルだと考えよう。 モデルの実行方法、会話の管理方法、中央エージェントとそのヘルパー間でどのように作業を移動させるかを定義する。スタックに関する情報は別の場所に置くべきだ。スキルがその場所だ。スキルはオンデマンドで読み込まれ、必要なものだけを持ち込み、作業が完了したら退場する。

2つのパラダイム: オンボーディングとオーケストレーション

劣ったアプローチ: プロジェクトオンボーディング

従来の解釈では、CLAUDE.mdは「Claude をコードベースにオンボーディングする」ためのものとされている。モデルに対して3つの質問に答える形式だ。技術スタックが何か、プロジェクトがなぜ存在するのか、どのように実行するか。60行以内に収めることを推奨するガイドもある。

このやり方には複数の問題がある:

優先度の飽和: CLAUDE.md の内容はすべてコンテキストウィンドウで高優先度として扱われる。モデルはファイル全体を権威あるものとして扱う。すべてのルールを詰め込むと、すべての行が同じトップスロットを奪い合う。データベースのマイグレーション中に、React のメモと API の規約が衝突する。すべてが高優先度なら、何も高優先度ではない。

コンテキストの無駄: React アプリ向けの React パターンで満たされた CLAUDE.md は、すべてのセッションで読み込まれる。デプロイスクリプトやスキーマ変更の作業であっても。

動作制御の欠如: 技術スタックのリストアップは、Claude が問題にどうアプローチすべきかを何も語らない。作業の委任についても、複数ステップのジョブのペースについても何も言わない。

プロジェクト間での繰り返し: 新しいリポジトリごとに新しい CLAUDE.md が生まれ、それぞれが前のものと乖離していく。AI はプロジェクトによって異なる振る舞いをすることになる。

静的な知識: プロジェクトのドキュメントは劣化する。半年前に書いた API パターンが、今日のコードの動き方と全く関係なくなっている可能性がある。

オンボーディングの枠組みは、Claude をその日の朝の作業についてブリーフィングを受ける請負業者のように扱う。オーケストレーションの枠組みは、Claude をパラメータを設定する必要がある実行中のシステムとして扱う。

優れたアプローチ: オーケストレーション層

CLAUDE.md が定義すべきもの:

1. 運用ワークフロー - すべてのリクエストに対して Claude が従うシーケンス
2. コンテキスト管理戦略 - コンテキストを効率的に節約・配分する方法
3. 委任パターン - サブエージェントをいつ使うか、直接処理するか
4. 品質基準 - コーディングの実践、エラーハンドリング、セキュリティ要件
5. 調整プロトコル - 並列作業と逐次作業の管理方法

スタック、パターン、規約は、関連性があるときに動的に読み込まれるスキルの中に置く。このように分割することで得られるメリット:

• すべてのプロジェクトで一貫したAIの動作
• 効率的なコンテキスト使用 - ドメイン知識は必要なときだけ読み込まれる
• ポータブルな専門知識 - スキルはプロジェクト間で転用できる
• 保守しやすい知識 - スキルを1回更新すれば、どこでも恩恵を受けられる

CLAUDE.md の構造化

コア原則セクション

AIに求める基本的な動作から始める。これらはどのプロジェクトやタスクにも普遍的に適用されるべきものだ。

## Core Principles
 
### Skills-First Workflow
 
**EVERY user request follows this sequence:**
 
Request → Load Skills → Gather Context → Execute
 
Skills contain critical workflows and protocols not in base context.
Loading them first prevents missing key instructions.
 
### Context Management Strategy
 
**Central AI should conserve context to extend pre-compaction capacity**:
 
- Delegate file explorations and low-lift tasks to sub-agents
- Reserve context for coordination, user communication, and strategic decisions
- For straightforward tasks with clear scope: skip heavy orchestration, execute directly
 
**Sub-agents should maximize context collection**:
 
- Sub-agent context windows are temporary
- After execution, unused capacity = wasted opportunity
- Instruct sub-agents to read all relevant files, load skills, and gather examples

これらはすべてのやり取りで発火する動作だ。今日に関係するかもしれないし、そうでないかもしれないプロジェクトの雑学ではない。

ルーティングと委任のロジック

Claude が直接作業を処理すべきか、スペシャリストに委任すべきかを定義する:

### Routing Decision
 
**Direct Execution**:
 
- Simple/bounded task with clear scope
- Single-component changes
- Quick fixes and trivial modifications
 
**Sub-Agent Delegation**:
 
- Complex/multi-phase implementations
- Tasks requiring specialized domain expertise
- Work that benefits from isolated context
 
**Lead Orchestrator**:
 
- Ambiguous requirements needing research
- Architectural decisions with wide impact
- Multi-day features requiring session management

ルーティングが書き下ろされることで、Claude は誰が何をするかについて実際の判断を下せる。何でも一人でやることも、理由なく作業を丸投げすることもなくなる。

運用プロトコル

特に並列処理が可能な場合に、Claude がどのように作業を調整すべきかを定義する:

## Operational Protocols
 
### Agent Coordination
 
**Parallel** (REQUIRED when applicable):
 
- Multiple Task tool invocations in single message
- Independent tasks execute simultaneously
- Bash commands run in parallel
 
**Sequential** (ENFORCE for dependencies):
 
- Database → API → Frontend
- Research → Planning → Implementation
- Implementation → Testing → Security
 
### Quality Self-Checks
 
Before finalizing code, verify:
 
- All inputs have validation
- Authentication/authorization checks exist
- All external calls have error handling
- Import paths verified against existing codebase examples

コーディング標準と実践

すべての作業を支配すべき普遍的なコーディング原則を含める:

## Coding Best Practices
 
**Priority Order** (when trade-offs arise):
Correctness > Maintainability > Performance > Brevity
 
### Task Complexity Assessment
 
Before starting, classify:
 
- **Trivial** (single file, obvious fix) → execute directly
- **Moderate** (2-5 files, clear scope) → brief planning then execute
- **Complex** (architectural impact, ambiguous requirements) → full research first
 
Match effort to complexity. Don't over-engineer trivial tasks or under-plan complex ones.
 
### Integration Safety
 
Before modifying any feature:
 
- Identify all downstream consumers using codebase search
- Validate changes against all consumers
- Test integration points to prevent breakage

rules ディレクトリ: モジュール式の指示

Claude Code v2.0.64 以降、指示を整理するための別のオプションとして .claude/rules/ ディレクトリが使える。rules は、スコープの狭いファイルにわたって高優先度の指示を分散させることで、飽和の罠を解消する。

Anthropic からの重要な洞察: rules ファイルは CLAUDE.md ファイルと同じ高優先度で扱われる。変わるのは、パスパターンでその優先度を狙い撃ちできるという点だ。ルールは、一致するファイルがスコープ内にある間だけ有効になる。

rules が CLAUDE.md より効果的な場合

指示にドメイン境界がある時点で rules が役に立つ:

.claude/rules/
├── api-guidelines.md     # Only relevant for API work
├── react-patterns.md     # Only relevant for frontend
├── testing-rules.md      # Only relevant for test files
└── security-rules.md     # Only relevant for auth/payment code

各ファイルはプロジェクトメモリに存在する。違いは、ルールをファイルパターンに固定できることだ:

---
paths: src/api/**/*.ts
---
 
# API Development Rules
 
- All endpoints must validate input with Zod
- Return consistent error shapes

このルールは Claude が API ファイルに触れているときだけ有効になる。フロントエンドでは、API の規約は静かにしている。

指示の優先度階層

これをレイヤーとして想像してほしい。各レイヤーは優先度レベルと読み込みルールを組み合わせている:

CLAUDE.md は常に高優先度で必要な普遍的な動作を保持する。rules はドメイン固有のものを保持し、適切なファイルが開いているときだけその優先度を持つ。スキル はポータブルな専門知識を中優先度で保持し、オンデマンドで読み込まれる。

詳細なパスターゲティングと移行戦術については、rules ディレクトリガイドを読んでほしい。

追加ディレクトリからの CLAUDE.md の読み込み

Claude Code v2.1.20 以降、Claude はアクティブなプロジェクト外のディレクトリからも CLAUDE.md ファイルを取り込むことができる。モノレポ、共有チーム規約、マルチプロジェクトのセットアップに便利だ。

仕組み:

# Enable the feature and specify additional directories
CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared-standards
 
# Multiple directories work too
CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared-config ../team-rules

フラグをオンにすると、Claude は各追加ディレクトリからこれらのファイルを取り込む:

• CLAUDE.md ファイル
• .claude/CLAUDE.md ファイル
• .claude/rules/*.md ファイル

これが口頭でファイルを指示するより優れている理由:

--add-dir を通じて、外部の CLAUDE.md ファイルは会話の埋め草ではなく本物のシステムメモリになる。自動的に読み込まれ、セッション再起動後も存続し、優先度階層の中に位置する。

実用的なユースケース:

共有標準を持つモノレポ:

company/
├── shared-standards/
│   └── CLAUDE.md          # Company coding guidelines
├── apps/
│   ├── web/
│   │   └── CLAUDE.md      # Web-specific rules
│   └── api/
│       └── CLAUDE.md      # API-specific rules

web/ ディレクトリから:

CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../../shared-standards

プロジェクト横断の一貫性: 個人の開発基準を一つの中央フォルダに置き、どのプロジェクトにも取り込む。ファイルのコピーは不要。

チームオンボーディング: 新しいチームメンバーは、チーム規約の共有ディレクトリを指定する。「プロジェクトごとに CLAUDE.md が微妙に異なる」問題が解消される。

更新された優先度階層:

注意: この機能は CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 が設定されている場合にのみ有効になる。単独での --add-dir フラグは、それらのディレクトリへのファイルアクセスを許可するだけだ。その中の CLAUDE.md ファイルは読み込まれない。

@import 構文: よりシンプルな代替案

--add-dir は外部ディレクトリ全体を渡す。1ファイルずつ取り込むには、より軽量なオプションがある。CLAUDE.md ファイルはコンポーザブルなメモリのために @path/to/import 構文をサポートしている:

See @README for project overview and @package.json for available npm commands.
 
# Standards
 
- coding guidelines @docs/coding-standards.md
- git workflow @docs/git-instructions.md

相対パスと絶対パスの両方が使える。相対パスは、作業ディレクトリからではなく、インポートするファイルから解決される。

--add-dir との違い:

初回承認: Claude Code がプロジェクト内のインポートに初めて遭遇すると、各ファイルをリストする承認ダイアログが表示される。これはプロジェクトごとに1回だけだ。拒否するとダイアログは二度と表示されない。それらのインポートはオフのままになる。

再帰的インポート: インポートされたファイルはさらに別のファイルをインポートできる。最大深さは5ホップだ。これがレイヤード指示セットを構築する方法だ:

# CLAUDE.md imports standards.md
 
@.claude/standards.md
 
# standards.md imports sub-files
 
@.claude/standards/api.md
@.claude/standards/testing.md

マークダウンのコードスパンとフェンスコードブロック内のインポートはスキップされる。@path に言及するコード例が誤って読み込みを発火させることはない。

CLAUDE.local.md: 個人プロジェクトの設定

チームの共有ツリーに載せたくない設定には CLAUDE.local.md を使う。このファイルは自動的に .gitignore に追加され、CLAUDE.md と同じ優先度で並んで読み込まれる。

適した用途:

• ローカル開発サーバーの URL とサンドボックスエンドポイント
• 個人的なテストデータの設定
• 好みのブランチ命名規則
• セットアップに固有のエディタとツールの設定

git worktree のヒント: CLAUDE.local.md は1つの worktree にしか存在しない。ホームディレクトリからのインポートを追加すれば、同じ個人的な指示をすべての worktree で使い回せる:

# CLAUDE.local.md
 
@~/.claude/my-project-instructions.md

/memory でロードされたメモリを表示

/memory を実行すると、Claude のコンテキストに現在存在するファイルをリストアップするか、ロードされたメモリファイルをエディタで開ける。モデルの動作から指示が欠けているように見えるときに使おう。インポートチェーンと rules が正しく適用されていることを確認したいときにも使える。

スキル: ドメイン知識が住む場所

スキルはもう一方の柱だ。CLAUDE.md は Claude がどのように動作するかを定義する。スキルは特定のドメインについて Claude が何を知っているかを提供する。

スキルアーキテクチャ

Anthropic はこの区別を直接的に表現している。「プロジェクトは『これを知っておいてほしい』と言う。スキルは『これはこうやってやる』と言う。」

スキルはプログレッシブディスクロージャを使用する:

1. メタデータが最初に読み込まれる (~100トークン) - スキルがいつ関連するかを知るのに十分
2. 必要なときに全指示が読み込まれる (<5kトークン)
3. バンドルされたファイル・スクリプトは必要なときだけ読み込まれる

この設計により、コンテキストウィンドウを圧迫せずに何十ものスキルを手元に置ける。Claude は必要な瞬間に必要なピースだけを取り出す。

スキルに属するもの

技術パターン:

• フレームワークの規約 (React パターン、API 設計)
• データベース操作とマイグレーション
• テスト戦略とユーティリティ

ドメインワークフロー:

• 決済処理の統合
• 認証の実装
• デプロイ手順

プロジェクト固有のコンテキスト:

• コードベースのナビゲーションガイド
• アーキテクチャドキュメント
• チームの規約

例: 関心の分離

CLAUDE.md にこれを書く代わりに:

## About This Project
 
FastAPI REST API for user authentication.
Uses SQLAlchemy for database operations.
 
## Commands
 
uvicorn app.main:app --reload
pytest tests/ -v

backend-api スキルを作成する:

# Backend API Development Skill
 
## Framework
 
FastAPI with SQLAlchemy ORM, Pydantic validation.
 
## Development Commands
 
- `uvicorn app.main:app --reload` - Start dev server
- `pytest tests/ -v` - Run test suite
- `alembic upgrade head` - Apply migrations
 
## Patterns
 
[Detailed patterns, examples, conventions...]

CLAUDE.md がスキルシステムを参照する:

### Key Skills
 
`backend-api`, `frontend-react`, `database-ops`, `deployment`
 
Load relevant skills before beginning domain-specific work.

これにより、バックエンドの詳細はバックエンド作業中だけ表示される。コンテキストは残りの作業に使える。ClaudeFast の Code Kit はすでにこの形で本番対応の CLAUDE.md を同梱している。スキルファースストのルーティング、5段階の複雑さアセスメント、コンテキストの最適化がデフォルトで組み込まれている。

行数論争

CLAUDE.md を60行以内に収めるべきという意見がある。Claude はそれより長いものを「無視する」というのが理由だ。Claude がコンテキストをどう扱うかについてのその読み方は間違っている。

現実: Anthropic はスキルファイルを500行以内に収めることを推奨している。オンデマンドでしか読み込まれないスキルが500行を有効に使えるなら、常時読み込まれる CLAUDE.md は200〜400行の運用詳細を確かに吸収できる。

最適化すべきは簡潔さではない。関連性だ。今日のタスクに適用されない60行のプロジェクト雑学は、常に関連する300行の普遍的な運用ルールよりも実効コンテキストを消費する。

スイートスポットは200〜400行で構成される:

• 運用ワークフロー (常に関連する)
• ルーティングロジック (常に関連する)
• 品質基準 (常に関連する)
• 調整プロトコル (常に関連する)

プロジェクト固有の内容60行のうち半分はどのリクエストでも不要なもの、というのは最悪の組み合わせだ。

フレームワークの進化

自己改善のための指示をファイルに組み込む:

### Framework Improvement
 
**Recognize patterns that warrant updates:**
 
**Update existing skill when**:
 
- A workaround was needed for something the skill should have covered
- New library version changes established patterns
- A better approach was discovered during implementation
 
**Create new skill when**:
 
- Same domain-specific context needed across 2+ sessions
- A payment processor, API, or tool integration was figured out
- Reusable patterns emerged that will apply to future projects
 
**Action**: Prompt user with: "This [pattern/workaround/integration] seems
reusable. Should I update [skill] or create a new skill to capture this?"

結果として自己改善システムができあがる。Claude は新しいスキルを作成する価値があるか、既存のスキルをアップグレードする価値がある瞬間を検出する。

このアプローチが機能する理由

マルチエージェントオーケストレーション

現代の Claude Code の作業は、専門的なインスタンスが独立したジョブを実行するサブエージェントにますます依存している。CLAUDE.md は中央モデルにそのチームをどう運営するかを伝えるものだ。

Anthropic によると、Opus 4.5 はサブエージェントのチームを率いるために特別にトレーニングされている。CLAUDE.md の中でそのトレーニングを活用するために、以下を明記する:

• 委任するかどうか、直接処理するか
• サブエージェントのプロンプトの構築方法
• サブエージェントの結果がメイン会話に戻ってくる方法

コンテキストの経済学

コンテキストウィンドウには上限がある。CLAUDE.md に注ぎ込むプロジェクトドキュメントのすべてのバイトは、実際の作業に使えないバイトだ。オーケストレーションはそのバジェットを上手に使う方法だ:

• CLAUDE.md: 運用指示 (常に必要)
• スキル: ドメイン知識 (オンデマンドで読み込み)
• サブエージェント: 専門的な作業のための新鮮なコンテキスト

プロジェクト間の一貫性

ファイルがプロジェクトの雑学ではなく動作を体系化すると、AI はすべての作業で同じように振る舞う。ルーティング、品質基準、調整の習慣はすべて引き継がれる。React アプリは Python CLI ツールと同じ扱いを受ける。

クイックリファレンス

Request → Load Skills → Route Decision → Execute

ルーティング:

• シンプル・有界タスク → 直接実行
• 複雑・多フェーズ → サブエージェント委任またはセッション管理

CLAUDE.md の内容:

• 運用ワークフロー
• コンテキスト管理戦略
• ルーティングと委任ロジック
• 品質基準
• 調整プロトコル

スキルの内容:

• 技術スタックの詳細
• フレームワークパターン
• プロジェクトの規約
• ドメインワークフロー

次のステップ

1. 現在の CLAUDE.md を監査する: プロジェクトドキュメントか運用指示か?

2. ドメイン知識をスキルに移行する: 技術スタック、パターン、規約を CLAUDE.md から移動する

3. 運用ワークフローを定義する: すべてのリクエストに対して Claude はどうアプローチすべきか?

4. ルーティングロジックを確立する: Claude はいつ委任すべきか、直接処理すべきか?

5. 品質基準を設定する: すべての作業を支配すべき実践は何か?

覚えておこう: CLAUDE.md は Claude が読むドキュメントではない。Claude が動作するシステムだ。動作を定義し、知識をスキルに押し出し、時間とともに全体が自己改善し続けるようにしよう。

これらの原則の上に完全なプレイブックが欲しい? トップ開発者を差別化する5つの Claude Code ベストプラクティスを読んでほしい。