Claude Code の能力を10倍にする CLAUDE.md — AI エージェントのマネジメント哲学

紹介ポスト: チャエン @masahirochaen 解説記事: Zenn: Claude Codeの能力を10倍にする CLAUDE.md の中身を見てみた

はじめに

海外で大バズりした「Claude Code の能力を10倍にする CLAUDE.md」。Anthropic の Claude Code 開発者が実際に使っているベストプラクティスを、1つの CLAUDE.md ファイルに構造化したもの。

これは単なるプロンプトテンプレートではない。AI エージェントをどうマネジメントするかという哲学を、実装可能な形にまとめたファイルだ。

6つのワークフロー原則

1. Plan Mode デフォルト

「3ステップ以上、またはアーキテクチャ判断を伴うタスクは、必ず Plan Mode から始めよ」

Claude Code が実装に飛びつくのを防ぐ最も重要なルール。計画なしに実装を始めると、途中で方向修正が必要になったとき、修正の連鎖（カスケード失敗）が発生する。

やり方:

Shift+Tab を2回押して Plan Mode に入る
Claude の計画が納得できるまでやり取りを繰り返す
計画が固まったら Auto-Accept モードに切り替えて一気に実装

実行中に問題が起きたら:

すぐに Plan Mode に戻って再計画する
Plan Mode は「最初の設計」だけでなく「リカバリー」にも使う

2. サブエージェント戦略

「リサーチ、探索、並列分析はサブエージェントに委譲せよ」

メインのコンテキストウィンドウは有限のリソース。調査や分析をメインエージェントにやらせると、コンテキストが汚れて本来のタスクの品質が下がる。

サブエージェントに委譲すべきタスク:

コードベースの調査・探索
複数ファイルの並列分析
計算集約的な処理
独立した検証作業

メインエージェントに残すべきタスク:

最終的な設計判断
コードの実装
統合・結合

初心者向け解説: 「サブエージェント（Task）」とは何か

「サブエージェント」と聞くと難しそうだが、仕組みはシンプル。Claude Code が内部的に「別の Claude」を立ち上げて、作業を分担する機能のこと。Claude Code ではこれを Task と呼ぶ。

日常的な例えで理解する:

あなたがプロジェクトマネージャー（= メインの Claude Code）だとする。大きな仕事を抱えたとき、全部を自分でやるのではなく、一部をチームメンバーに頼む。

あなた（メインの Claude）:「この機能を実装したい」
  ├── 部下A（サブエージェント）:「既存コードの調査をしてきて」→ 結果だけ報告
  ├── 部下B（サブエージェント）:「テストファイルを分析してきて」→ 結果だけ報告
  └── あなた（メインの Claude）: 報告を受けて、実装を判断・実行

なぜ Task が必要なのか:

Claude Code には「コンテキストウィンドウ」という記憶の上限がある。一度に覚えられる情報量に限りがあるということ。

Task なし: メインの Claude が調査もコーディングも全部やる → 調査結果でコンテキストが埋まり、肝心の実装時に記憶容量が足りなくなる
Task あり: 調査は別の Claude（サブエージェント）がやり、結論だけメインに返す → メインのコンテキストがクリーンに保たれ、実装に集中できる

Claude Code に組み込みの Task タイプ（追加設定不要）:

タイプ	できること	使いどころ
Explore	ファイル検索、コード読み取り	「この関数がどこで使われてるか調べて」
Plan	設計・計画の策定	「実装方針を考えて」
general-purpose	何でも（ファイル編集、コマンド実行含む）	「この部分を修正して」

これらは Claude Code の組み込み機能なので、何もインストールする必要はない。Claude Code が自動的に判断して Task を使うこともあるし、CLAUDE.md に「調査はサブエージェントに委譲せよ」と書くことで積極的に使わせることもできる。

さらに発展: カスタムエージェント

組み込みの Task に加えて、.claude/agents/ フォルダに自分専用のエージェントを定義できる。

1
2
3
4
5
6
7
8
9
# .claude/agents/test-runner.md
---
name: test-runner
description: テストを実行して結果を報告する
tools: Bash, Read, Glob
---
あなたはテスト実行の専門家です。
- テストを実行し、失敗したテストの原因を分析
- 修正案を提示（修正自体は行わない）

これにより「テスト実行はこのエージェントに任せる」といった専門分業が可能になる。ただし、まずは組み込みの Task だけで十分。カスタムエージェントは必要になってから作ればよい。

3. 自己改善ループ

「tasks/lessons.md に修正パターンを記録せよ」

Claude Code はセッション間で記憶を持たない。昨日学んだ「やってはいけないこと」を、今日のセッションでは知らない。だからこそ、学習をファイルとして外部化する。

lessons.md のイメージ:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# 学んだこと

## パターン1: テストファイルの削除禁止
- 状況: リファクタリング時に「不要」と判断してテストファイルを削除した
- 問題: CI が壊れた
- ルール: 既存のテストファイルは絶対に削除しない。不要と思っても確認を求める

## パターン2: 環境変数のハードコード禁止
- 状況: 動作確認のためにAPIキーを直接コードに書いた
- 問題: セキュリティリスク
- ルール: 環境変数は必ず .env から読み込む

運用方法:

Claude が間違いを犯したら「lessons.md を更新して、同じ間違いを繰り返さないようにして」と指示
Claude 自身がルールを書き加える
次のセッションでは CLAUDE.md 経由で lessons.md が読み込まれ、同じ間違いを回避

4. 完了前の検証

「動作することを証明するまで完了とするな」

タスクの完了基準は「コードを書いた」ではなく「動作を証明した」。

検証基準:

テストが通ること
実際に動作すること（UI があればブラウザで確認）
「シニアエンジニアが承認するレベルか」 を判断基準にする

5. 優雅さの追求（バランス付き）

「非自明な変更には優雅なソリューションを求めよ。ただしオーバーエンジニアリングはするな」

「(Balanced)」と明記されている点が重要。

大きな変更: 設計を練り、エレガントなソリューションを追求する
小さな修正: シンプルに直す。3行で済むものを抽象化しない

6. 自律バグ修正

「CI の失敗を直して、と指示するだけ。具体的な手順は Claude に委ねよ」

問題を提示して、解決策の決定は Claude に任せる。マイクロマネジメントしないことで、ユーザーのコンテキストスイッチを最小化する。

# ❌ マイクロマネジメント
「test_user.py の 42行目で AssertionError が出ている。
expected_count が 3 なのに actual が 2 になっている。
fixture の setup で...」

# ✅ 自律的な修正
「CI のテストが落ちてるから直して」

タスク管理: 2つのファイルで PDCA を回す

複雑なツールは使わない。マークダウンファイル2つで十分。

ファイル	役割	内容
`tasks/todo.md`	計画・実行・記録	タスクリスト、進捗状態、結果の記録
`tasks/lessons.md`	学習・改善	修正パターン、予防ルール、ベストプラクティス

PDCA サイクルの回し方:

Plan:    todo.md にタスクを書き出す
Do:      Claude がタスクを実行
Check:   検証して結果を todo.md に記録
Act:     失敗パターンを lessons.md に追記

3つの根本原則

全体を貫く基本ルール:

1. シンプルさ優先

最小限の影響で済ませる。変更は必要な部分だけ。「ついでにリファクタリング」はしない。

2. 根本原因の解決

一時的な修正（ワークアラウンド）ではなく、根本原因を特定して修正する。// TODO: 後で直す を残さない。

3. シニア開発者基準

全体を通して、シニアエンジニアが承認するレベルの品質を維持する。「動けばいい」ではなく「正しく動く」を基準にする。

Boris Cherny の Tips との関係

この CLAUDE.md は、Claude Code 開発者 Boris Cherny が公開した Tips を実装可能な形にまとめたものと言える。

Boris Cherny の Tip	この CLAUDE.md での実装
Plan Mode の規律	原則1: Plan Mode デフォルト
サブエージェントでコンテキストを清潔に	原則2: サブエージェント戦略
Claude に自分のルールを書かせる	原則3: 自己改善ループ (lessons.md)
検証の仕組みを与える	原則4: 完了前の検証
挑発的プロンプト	原則5: 優雅さの追求
Claude に自分のバグを直させる	原則6: 自律バグ修正

本質: AI エージェントのマネジメント

この CLAUDE.md が示しているのは、人間のチーム管理と同じ原則が AI エージェントにも適用できるということ。

人間のチーム管理	AI エージェント管理
作業前にレビューで計画を確認	Plan Mode で計画を承認してから実装
タスクを専門メンバーに分担	サブエージェントに専門タスクを委譲
ふりかえりで改善点を記録	lessons.md に失敗パターンを蓄積
コードレビューで品質を担保	完了前に検証を要求
新人に「なぜそうするか」を教える	CLAUDE.md にルールと理由を明記

Claude Code を「コード生成ツール」としてではなく、**「明確な境界と検証ゲートを持つチームメンバー」**として扱う。それがこの CLAUDE.md の設計思想。

すぐに取り入れられるアクション

CLAUDE.md に「Plan Mode で始めよ」と書く — これだけで手戻りが大幅に減る
tasks/lessons.md を作る — 間違いを記録する仕組みを最初に用意する
完了基準を明記する — 「テストが通ること」「シニアエンジニア基準」を CLAUDE.md に書く
「直して」とだけ指示する — 具体的手順を与えずに Claude の自律性を活かす
todo.md でタスク管理する — 複雑なツールは不要。マークダウンで十分

初心者向け補足: Claude Code の拡張機能を整理する — Task / Skill / Hook / MCP

この記事で「サブエージェント」「自己改善ループ」など様々な機能が登場するが、Claude Code の拡張機能は大きく分けて 5つある。それぞれの役割と違いを整理する。

一覧表

機能	一言で言うと	どこに置く	動くタイミング
Task（サブエージェント）	別の Claude に仕事を任せる	`.claude/agents/`	Claude が判断 or ユーザー指示
Skill（スキル）	再利用できる手順書	`.claude/skills/`	自動 or `/スキル名` で呼び出し
Hook（フック）	イベント時に自動実行するスクリプト	`settings.json` の `hooks`	特定イベント発生時に必ず実行
MCP	外部サービスとの接続	`.mcp.json`	Claude がツールとして使用
Plugin（プラグイン）	上記をまとめて配布するパッケージ	`.claude-plugin/`	インストール時

Task（サブエージェント）— 「別の Claude に仕事を振る」

上の「原則2: サブエージェント戦略」で詳しく解説した機能。別の Claude を立ち上げて、独立した記憶空間で作業させる。

組み込みタイプ（Explore, Plan, general-purpose）は設定不要
カスタム定義は .claude/agents/エージェント名.md に配置
メインの記憶（コンテキスト）を汚さないのが最大のメリット

メインの Claude:「この機能を作りたい」
  └── Task（Explore）:「関連コードを調べてきて」→ 結果だけ返す

Skill（スキル）— 「手順書を渡す」

再利用可能な手順書・テンプレート。Task とは違い、別の Claude は立ち上がらない。メインの会話にそのまま読み込まれる。

イメージとしては「マニュアルを手渡す」こと。Claude が賢くなるわけではなく、やり方を教える。

1
2
3
4
5
6
7
8
# .claude/skills/deploy/SKILL.md
---
name: deploy
description: 本番環境へのデプロイ手順
---
1. テストを実行する
2. ビルドする
3. デプロイコマンドを実行する

/deploy と打つと手動で呼び出せる
description にマッチする場面で Claude が自動的に読み込むこともある
コーディング規約、API の使い方、定型作業の手順などに最適

Task との違い: Task は「別の人に仕事を頼む」、Skill は「自分用のマニュアルを読む」。

Hook（フック）— 「条件付きの自動スクリプト」

特定のイベントが起きたら、問答無用で実行されるスクリプト。Claude の判断とは無関係に動く。

日常の例え: 「ドアが開いたら自動で照明が点く」ような仕組み。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{
        "type": "command",
        "command": "npx prettier --write $(jq -r '.tool_input.file_path')"
      }]
    }]
  }
}

上の例は「ファイルを編集・作成したら、自動でコードフォーマッターを実行する」フック。

主なイベント:

イベント	タイミング
`SessionStart`	セッション開始時
`PreToolUse`	ツール実行前（exit code 2 でブロック可能）
`PostToolUse`	ツール実行後
`Stop`	Claude の応答完了時

Task / Skill との違い: Task と Skill は「Claude が何をするか」に関わる。Hook は「Claude の行動に対して、外部のスクリプトが反応する」。Claude はフックの存在を知らなくても動作する。

MCP（Model Context Protocol）— 「外の世界と繋ぐ」

外部のツールやサービスを Claude に接続する標準プロトコル。GitHub、データベース、Slack、Figma など、Claude Code 単体ではアクセスできないサービスとの橋渡し。

1
2
3
4
5
6
7
8
{
  "mcpServers": {
    "github": {
      "transport": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    }
  }
}

.mcp.json に設定
Claude にとっては「使えるツールが増える」感覚
外部サービスの読み書きが可能になる

他との違い: Task / Skill / Hook は Claude Code の「内部」の仕組み。MCP は「外部」との接続。

Plugin（プラグイン）— 「全部まとめて配る」

上記の Task、Skill、Hook、MCP を1つのパッケージにまとめて配布する仕組み。

my-plugin/
├── .claude-plugin/plugin.json   ← マニフェスト
├── skills/                      ← スキル群
├── agents/                      ← エージェント群
├── hooks/hooks.json             ← フック設定
└── .mcp.json                    ← MCP 設定

チームや組織で「うちのプロジェクトではこのツールセットを使う」と統一するのに便利。

使い分けの判断フロー

やりたいこと
  ├── 外部サービスに接続したい      → MCP
  ├── ファイル保存時に自動処理したい  → Hook
  ├── 手順書・テンプレートを再利用したい → Skill
  ├── 重い作業を別の Claude に任せたい  → Task
  └── 全部まとめてチームに配りたい    → Plugin

最も重要な違い: Task は「別の Claude が別の記憶空間で作業する」、Skill は「メインの Claude に知識を注入する」、Hook は「Claude の判断に関係なく必ず実行される」。

Claude Code の能力を10倍にする CLAUDE.md — AI エージェントのマネジメント哲学#

はじめに#

6つのワークフロー原則#

1. Plan Mode デフォルト#

2. サブエージェント戦略#

初心者向け解説: 「サブエージェント（Task）」とは何か#

3. 自己改善ループ#

4. 完了前の検証#

5. 優雅さの追求（バランス付き）#

6. 自律バグ修正#

タスク管理: 2つのファイルで PDCA を回す#

3つの根本原則#

1. シンプルさ優先#

2. 根本原因の解決#

3. シニア開発者基準#

Boris Cherny の Tips との関係#

本質: AI エージェントのマネジメント#

すぐに取り入れられるアクション#

初心者向け補足: Claude Code の拡張機能を整理する — Task / Skill / Hook / MCP#

一覧表#

Task（サブエージェント）— 「別の Claude に仕事を振る」#

Skill（スキル）— 「手順書を渡す」#

Hook（フック）— 「条件付きの自動スクリプト」#

MCP（Model Context Protocol）— 「外の世界と繋ぐ」#

Plugin（プラグイン）— 「全部まとめて配る」#

使い分けの判断フロー#

参考リンク#