はじめに
こんばんは、mirukyです。
Claude Codeを使っている方、CLAUDE.mdは書いていますか？
最近、Redditで「The 5 Levels of Claude Code」という投稿が話題になりました。投稿者のDevMoses氏は、 198エージェントを32セッションで並列実行し、マージコンフリクト率わずか3.1% という驚異的な運用を行っています。
その核心は「Claude Codeには5つの習熟レベルがある」というフレームワークです。多くの人はLevel 2のCLAUDE.mdで止まっていますが、その先にはSkills・Hooks・Orchestrationというまったく別次元の世界が広がっています。
本記事では、公式ドキュメントとコミュニティの知見をもとに、Claude Codeの5つのレベルを体系的に解説します。
出典：The 5 levels of Claude Code - Reddit r/ClaudeAI / Claude Code公式ドキュメント
目次
- 5つのレベルの全体像
- Level 1：Raw Prompting（素のプロンプト）
- Level 2：CLAUDE.md（プロジェクト記憶）
- Level 3：Skills（オンデマンドスキル）
- Level 4：Hooks（ライフサイクル自動化）
- Level 5：Orchestration（並列エージェント統制）
- レベルアップのためのロードマップ
1. 5つのレベルの全体像
1-1. フレームワーク概要
Claude Codeの習熟度は、5段階のレベルで捉えることができます。各レベルは前のレベルの課題を解決する形で積み上がっており、スキップすることはできません。
| レベル | 名称 | 核心 | トークン消費 |
|---|---|---|---|
| Level 1 | Raw Prompting | 指示をその都度手入力 | 毎回繰り返し |
| Level 2 | CLAUDE.md | プロジェクトルールを永続化 | セッション開始時に読み込み |
| Level 3 | Skills | 手順書をオンデマンドで注入 | 呼び出し時のみ消費 |
| Level 4 | Hooks | ライフサイクルに自動処理を挟む | ほぼゼロ（外部スクリプト） |
| Level 5 | Orchestration | 複数エージェントの並列統制 | エージェント数に比例 |
1-2. 「卒業」の仕組み
DevMoses氏の重要な洞察は、 「自分で次のレベルに進むのではない。天井にぶつかって摩擦に押し上げられる」 という点です。
You don't graduate by deciding to. You graduate because you hit a ceiling and the friction forces you up.
つまり、Level 2のCLAUDE.mdが150行を超えて遵守率が下がったとき、自然とLevel 3のSkillsが必要になります。Skillsだけでは品質が保証できないとき、Level 4のHooksに進む、という流れです。
2. Level 1：Raw Prompting（素のプロンプト）
2-1. どういう状態か
Claude Codeをインストールして、そのまま使っている段階です。
claude
> このReactアプリにダークモードを追加して。
> Tailwind CSSを使って、トグルボタンも作って。
小規模なタスクでは十分に機能します。Claude Codeは優秀なので、1ファイルの変更程度なら問題なく処理できます。
2-2. なぜ天井にぶつかるのか
プロジェクトが成長すると、以下の問題が発生します。
| 問題 | 具体例 |
|---|---|
| 毎回同じ指示の繰り返し | 「TypeScriptで書いて」「テストも書いて」「ESLintを通して」 |
| コーディング規約の不統一 | セッションごとにスタイルがブレる |
| コンテキストの断絶 | 新しいセッションを開くたびにプロジェクト構成を説明し直す |
この摩擦が十分に溜まったとき、Level 2に進む準備ができています。
3. Level 2：CLAUDE.md（プロジェクト記憶）
3-1. CLAUDE.mdとは
CLAUDE.mdは、Claude Codeがセッション開始時に自動で読み込むマークダウンファイルです。プロジェクトのルール、コーディング規約、ビルドコマンドなどを記載しておくと、毎回指示しなくてもClaudeが従ってくれます。
# プロジェクト概要
フロントエンド: React 19 + TypeScript + Tailwind CSS
バックエンド: Hono + Drizzle ORM
テスト: Vitest
# コーディング規約
- 関数コンポーネントのみ使用（クラスコンポーネント禁止）
- 型定義は`types/`ディレクトリに集約
- インポートはエイリアス`@/`を使用
# コマンド
- ビルド: `pnpm build`
- テスト: `pnpm test`
- リント: `pnpm lint`
3-2. 配置場所とスコープ
CLAUDE.mdは複数の場所に配置でき、それぞれスコープが異なります。
| 配置場所 | スコープ | 用途 |
|---|---|---|
./CLAUDE.md |
プロジェクト全体 | チーム共有のコーディング規約・ビルド手順 |
./.claude/CLAUDE.md |
プロジェクト全体 | 上記と同等（.claude/内に隠せる） |
~/.claude/CLAUDE.md |
全プロジェクト共通 | 個人の好みやワークフロー |
サブディレクトリのCLAUDE.md
|
そのディレクトリ以下 | パッケージ固有の規約（モノレポ向け） |
/initコマンドで自動生成
/initを実行すると、Claude Codeがコードベースを分析してCLAUDE.mdのたたき台を自動生成してくれます。既にCLAUDE.mdがある場合は改善提案をしてくれます。
3-3. .claude/rules/によるモジュール化
CLAUDE.mdが長くなってきたら、.claude/rules/ディレクトリにトピック別のファイルとして分割できます。
your-project/
├── .claude/
│ ├── CLAUDE.md # メインの指示（簡潔に）
│ └── rules/
│ ├── code-style.md # コーディング規約
│ ├── testing.md # テスト規約
│ └── security.md # セキュリティ要件
さらに、pathsフロントマターを使えば特定のファイルパターンにのみ適用されるルールを定義できます。
---
paths:
- "src/api/**/*.ts"
---
# API開発ルール
- 全エンドポイントに入力バリデーションを実装
- 標準エラーレスポンス形式を使用
- OpenAPIドキュメントコメントを含める
3-4. なぜ天井にぶつかるのか
Anthropic公式は200行以下を推奨しています。コミュニティでは77行程度が最適という報告もあります。
| 問題 | 原因 |
|---|---|
| 遵守率の低下 | CLAUDE.mdが長くなるほど、後半のルールが無視されやすい |
| トークンの常時消費 | CLAUDE.mdは毎セッション全文読み込まれる |
| すべてを1ファイルに詰め込めない | デプロイ手順、レビュー基準、テスト戦略…役割が違う |
ここで必要になるのが、「必要なときだけ読み込まれる」スキルファイルです。
4. Level 3：Skills（オンデマンドスキル）
4-1. Skillsとは
Skillsは、.claude/skills/ディレクトリに配置するマークダウンファイルで、特定のタスクの手順書をClaude Codeに教えるものです。CLAUDE.mdとの最大の違いは、呼び出されたときだけコンテキストに読み込まれる点です。
使わないとき → トークン消費ゼロ
呼び出し時 → 手順書がコンテキストに注入される
4-2. スキルファイルの構造
スキルファイルはSKILL.mdという名前で、YAMLフロントマターとマークダウン本文で構成されます。
.claude/skills/
├── deploy/
│ └── SKILL.md # デプロイ手順書
├── code-review/
│ └── SKILL.md # コードレビュー手順書
└── fix-issue/
└── SKILL.md # Issue修正手順書
4-3. スキルファイルの書き方
以下は、GitHub Issueを修正するスキルの例です。
---
name: fix-issue
description: GitHub Issueを修正する
disable-model-invocation: true
---
GitHub Issue $ARGUMENTS を以下の手順で修正してください。
1. Issueの内容を確認
2. 関連コードを調査
3. 修正を実装
4. テストを作成
5. コミットを作成
| フロントマター | 説明 |
|---|---|
name |
/コマンドの名前（/fix-issueで呼び出せる） |
description |
Claudeが自動判断で使うかどうかの説明文 |
disable-model-invocation |
trueにすると手動呼び出しのみ（Claudeが勝手に使わない） |
allowed-tools |
スキル実行中にClaudeが使えるツールを制限 |
context |
forkにするとサブエージェントで実行 |
4-4. 実用的なスキル例
リードオンリーリサーチャー
---
name: deep-research
description: コードベースを深くリサーチする
context: fork
agent: Explore
---
$ARGUMENTS について徹底的に調査してください。
1. Glob と Grep で関連ファイルを発見
2. コードを読み込んで分析
3. 具体的なファイル参照付きで調査結果をまとめる
PR要約スキル（動的コンテキスト注入）
---
name: pr-summary
description: PRの変更内容を要約する
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---
## PRの情報
- PRの差分: !`gh pr diff`
- PRのコメント: !`gh pr view --comments`
- 変更ファイル一覧: !`gh pr diff --name-only`
## タスク
このPRを要約してください...
!コマンド構文
!<command>は、スキル内容がClaudeに送られる前にシェルコマンドを実行し、その出力で置換します。Claudeはコマンドではなく、実行結果のデータを受け取ります。
4-5. CLAUDE.md vs Skills の使い分け
| 観点 | CLAUDE.md / rules | Skills |
|---|---|---|
| 読み込みタイミング | 毎セッション自動読み込み | 呼び出し時のみ |
| トークン消費 | 常時消費 | 使用時のみ |
| 適した内容 | コーディング規約、ビルドコマンド | デプロイ手順、レビューフロー、Issue修正 |
| 呼び出し方 | 自動 |
/skill-name or Claudeの自動判断 |
Skillsの詳細な実践テクニック
筆者が別記事でSkillsの実践的な活用パターンを10個まとめています。具体的なスキルファイルの書き方をもっと知りたい方はこちらもご覧ください。
→ 【2026年最新版】Claude Code Skills実践テクニック 10選
4-6. なぜ天井にぶつかるのか
Skillsは「Claudeに何をすべきか教える」ものですが、「Claudeがやったことを検証する」仕組みではありません。 Claudeにテストを実行するよう指示しても、忘れることがあります。
Skillsの限界：「テストを実行して」と伝えることはできる。だが、Claudeがそれを確実に実行する保証はない。
5. Level 4：Hooks（ライフサイクル自動化）
5-1. Hooksとは
Hooksは、Claude Codeのライフサイクルの特定のポイントで自動実行されるスクリプトです。「Claudeにバリデーションするよう指示する」のではなく、**「バリデーションするインフラそのもの」**を構築します。
Skills: 「ファイル編集後にリントを実行して」と指示する
Hooks: ファイル編集後にリントが"自動で"実行される仕組みを作る
5-2. Hooksの種類
Hooksは、Claude Codeのライフサイクル全体をカバーする豊富なイベントを持っています。
| イベント | タイミング | 主な用途 |
|---|---|---|
| SessionStart | セッション開始時 | 開発環境のセットアップ、環境変数の設定 |
| PreToolUse | ツール実行前 | 危険なコマンドのブロック、バリデーション |
| PostToolUse | ツール実行後 | リント、型チェック、テスト自動実行 |
| Stop | Claude応答完了時 | 品質ゲート（全タスク完了の確認） |
| SubagentStart/Stop | サブエージェント起動/終了時 | サブエージェント監視 |
| TaskCompleted | タスク完了時 | テスト合格の強制 |
| UserPromptSubmit | プロンプト送信時 | プロンプトの検証・コンテキスト追加 |
5-3. 実践例①：危険なコマンドのブロック
rm -rfを含むBashコマンドを自動でブロックするHookです。
設定ファイル（.claude/settings.json）：
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-rm.sh"
}
]
}
]
}
}
スクリプト（.claude/hooks/block-rm.sh）：
#!/bin/bash
COMMAND=$(jq -r '.tool_input.command' < /dev/stdin)
if echo "$COMMAND" | grep -q 'rm -rf'; then
echo "Blocked: rm -rf commands are not allowed" >&2
exit 2 # exit 2 = ブロック
fi
exit 0 # exit 0 = 許可
5-4. 実践例②：ファイル編集後の自動リント
Claudeがファイルを編集するたびに、自動でリントスクリプトを実行します。
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-style.sh"
}
]
}
]
}
}
5-5. 実践例③：品質ゲート（Stopフック）
Claudeが「完了した」と判断して停止しようとしたとき、本当に完了しているか検証するHookです。Prompt型フックを使うと、別のLLMに判定させることができます。
{
"hooks": {
"Stop": [
{
"hooks": [
{
"type": "prompt",
"prompt": "以下のコンテキストを評価してください: $ARGUMENTS\n\n1. ユーザーが依頼した全タスクが完了しているか\n2. エラーが残っていないか\n3. フォローアップが必要ないか\n\nJSON形式で回答: {\"ok\": true} で停止許可、{\"ok\": false, \"reason\": \"理由\"} で継続",
"timeout": 30
}
]
}
]
}
}
5-6. 4種類のHookハンドラ
| タイプ | 動作 | 用途 |
|---|---|---|
command |
シェルコマンドを実行 | リント、テスト、ファイル検証 |
http |
HTTPエンドポイントにPOSTリクエスト | 外部サービス連携、ログ送信 |
prompt |
別のLLMに単一ターンで問い合わせ | 品質判定、セキュリティチェック |
agent |
ツール使用可能なサブエージェントを起動 | コードを読んで検証する複雑なチェック |
非同期Hookも可能
"async": trueを設定すると、HookがバックグラウンドでClaudeの作業をブロックせずに実行されます。テストスイートの実行など、時間のかかる処理に最適です。
Hooksの全イベント解説
筆者が別記事でHooksの全21イベントを網羅的に解説しています。本記事では主要なイベントのみ紹介していますので、全容を知りたい方はこちらもご覧ください。
→ 【保存版】Claude Code Hooks全21イベント完全解説 ！イベント駆動でAI開発ワークフローを自動化しよう
5-7. HookはSkillのフロントマターにも定義できる
Skillファイルのフロントマター内にHookを定義すると、そのSkillがアクティブな間だけHookが有効になります。
---
name: secure-operations
description: セキュリティチェック付きで操作する
hooks:
PreToolUse:
- matcher: "Bash"
hooks:
- type: command
command: "./scripts/security-check.sh"
---
5-8. なぜ天井にぶつかるのか
Hooksは品質をインフラレベルで保証しますが、1つのClaude Codeセッションでは処理できる作業量に限界があります。大規模なリファクタリング、数十ファイルにまたがる変更、複数観点からのレビューを1セッションで行うのは非現実的です。
ここで必要になるのが、複数のエージェントを並列で動かす仕組みです。
6. Level 5：Orchestration（並列エージェント統制）
6-1. なぜ並列化が必要か
Level 4までは「1つのClaudeセッション」の中での最適化でした。しかし、現実のプロジェクトでは以下のシナリオに直面します。
| シナリオ | 単一セッションの限界 |
|---|---|
| 大規模リファクタリング | コンテキストウィンドウに収まらない |
| 並列コードレビュー | セキュリティ・パフォーマンス・テストを同時に見れない |
| 複数仮説の調査 | 1つの仮説に固定されてしまう |
| フロントエンド/バックエンド同時開発 | 同じファイルの競合が発生 |
6-2. Subagents（サブエージェント）
Claude Codeにはビルトインのサブエージェントが含まれており、Claudeが自動的にタスクを委譲します。
| サブエージェント | モデル | 用途 |
|---|---|---|
| Explore | Haiku（高速） | ファイル検索、コードベース探索（読み取り専用） |
| Plan | ― | 計画立案 |
| General-purpose | ― | 汎用タスク |
カスタムサブエージェントの定義
.claude/agents/にマークダウンファイルを作成して、独自のサブエージェントを定義できます。
---
name: code-reviewer
description: コード品質とベストプラクティスをレビューする
tools: Read, Grep, Glob, Bash
model: sonnet
---
あなたはシニアコードレビュアーです。起動されたら：
1. git diff で最近の変更を確認
2. 変更されたファイルに集中
3. すぐにレビューを開始
レビューチェックリスト：
- コードが明確で読みやすいか
- 適切なエラーハンドリング
- セキュリティ上の問題がないか
- テストカバレッジ
サブエージェントはサブエージェントを生成できない
サブエージェントは他のサブエージェントを生成することはできません。ネストされた委譲が必要な場合は、メインの会話からチェーンしてください。
6-3. Agent Teams（エージェントチーム）
Agent Teamsは、複数のClaude Codeインスタンスがチームとして連携する仕組みです。サブエージェントとの最大の違いは、チームメイト同士が直接コミュニケーションできる点です。
| 比較 | Subagents | Agent Teams |
|---|---|---|
| コンテキスト | 結果のみ親に返す | 各自独立のコンテキスト |
| コミュニケーション | 親エージェントへの報告のみ | チームメイト間で直接メッセージ |
| 調整 | 親エージェントが管理 | 共有タスクリストで自己調整 |
| 最適な用途 | 結果だけ欲しい集中タスク | 議論・協調が必要な複雑タスク |
Agent Teamsの有効化
Agent Teamsは実験的機能で、デフォルトでは無効です。
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}
使用例：並列コードレビュー
Create an agent team to review PR #142. Spawn three reviewers:
- One focused on security implications
- One checking performance impact
- One validating test coverage
Have them each review and report findings.
リードがチーム全体を統括し、各チームメイトが独立して作業。結果をリードが統合します。
6-4. /batchスキル — 大規模並列変更
Claude Code組み込みの/batchスキルは、大規模な変更を並列エージェントで実行するためのものです。
/batch migrate src/ from Solid to React
これを実行すると、Claude Codeは以下を行います：
- コードベースを調査
- 作業を5〜30の独立した単位に分解
- 計画を提示（承認待ち）
- 承認後、各単位ごとに独立したgit worktreeでエージェントを生成
- 各エージェントが実装・テスト・PR作成
6-5. DevMoses氏の運用実績
Redditで話題になった投稿者DevMoses氏は、以下の実績を報告しています。
| メトリクス | 数値 |
|---|---|
| 並列エージェント数 | 198 |
| フリートセッション数 | 32 |
| マージコンフリクト率 | 3.1% |
この運用は、Citadelというオープンソースシステムを使って実現されています。
Level 5の注意点
- トークン消費がエージェント数に比例して増大する
- 同じファイルを複数エージェントが編集するとコンフリクトが発生する
- 3〜5チームメイトから始めることが推奨される
- Agent Teamsは実験的機能であり、セッション再開時にチームメイトが復元されない場合がある
7. レベルアップのためのロードマップ
7-1. 段階的に進める
最も重要な原則：レベルをスキップしないこと。
各レベルのインフラが次のレベルを可能にしています。CLAUDE.mdなしにSkillsを書いても、基本的な規約が統一されていなければスキルの品質も安定しません。
Step 1：CLAUDE.mdを書く（/init で自動生成 → 改善）
↓
Step 2：CLAUDE.mdが長くなったら .claude/rules/ に分割
↓
Step 3：繰り返すワークフローをSkillsに切り出す
↓
Step 4：品質を保証したい箇所にHooksを設置
↓
Step 5：Subagentsでタスク委譲 → Agent Teamsで並列化
7-2. 今日から始めるアクションリスト
| 現在地 | 次のアクション | 所要時間 |
|---|---|---|
| Level 0（Claude Code未導入） | npm install -g @anthropic-ai/claude-code |
5分 |
| Level 1（CLAUDE.mdなし） |
/initでCLAUDE.mdを自動生成 |
10分 |
| Level 2（CLAUDE.mdあり） | よく繰り返すワークフローを1つSkillにする | 30分 |
| Level 3（Skillsあり） | PostToolUseフックでリント自動実行を設定 | 30分 |
| Level 4（Hooksあり） | Subagentを1つ定義して委譲を試す | 30分 |
7-3. 公式ドキュメントで深掘りすべきページ
| レベル | ドキュメント |
|---|---|
| Level 2 | How Claude remembers your project |
| Level 3 | Extend Claude with skills |
| Level 4 | Hooks reference / Hooks guide |
| Level 5 | Create custom subagents / Agent teams |
おわりに
ここまでお読みいただきありがとうございます。
Claude Codeの5つのレベルのポイントをまとめます。
- Level 1（Raw Prompting）：素のClaude Code。小タスクには十分だが、プロジェクトが育つと限界に達する
- Level 2（CLAUDE.md）：プロジェクトルールの永続化。200行以下で簡潔に保つ
- Level 3（Skills）：オンデマンドで読み込まれる手順書。使わないときはトークン消費ゼロ
- Level 4（Hooks）：ライフサイクルに品質ゲートを組み込む。「指示する」から「インフラで保証する」への転換
-
Level 5（Orchestration）：Subagents・Agent Teams・
/batchによる並列統制
重要なのは、「今日すべてを導入する」必要はないということです。天井にぶつかったときが、次のレベルに進むタイミングです。まずはCLAUDE.mdを書くところから始めてみてください。
ではまた、お会いしましょう。
参考リンク
公式ドキュメント
- Claude Code Overview
- How Claude remembers your project（CLAUDE.md）
- Extend Claude with skills
- Hooks reference
- Automate workflows with hooks（Guide）
- Create custom subagents
- Orchestrate teams of Claude Code sessions