【Claude Code 完全マスター入門】Subagents・Plan Mode・claude agents まで網羅した『AI チーム編成』実装ガイド17章

本サイトは Google AdSense による広告が表示される場合があります。本記事は Anthropic 公式ドキュメント（code.claude.com/docs）、Anthropic 公式ブログ「How we built our multi-agent research system」「Building effective agents」「Effective context engineering for AI agents」を一次情報として精読し、運営者（現役 IT エンジニア・15 年以上の業界経験）が日本語で再構成したものです。仕様は 2026 年 5 月時点。最新情報は 公式ドキュメント をご確認ください。

Tech Notes · Claude Code · Master Guide · 2026.05

AI は 1 人で戦う時代を、もう終えている。Anthropic 公式が 2025 年 6 月のブログで明かしたとおり、Claude Opus 4 を司令官にし Claude Sonnet 4 を部下にする「マルチエージェント編成」は、社内リサーチ評価で 単独 Opus 4 を 90.2% 上回った^[1]。日本では「プロンプトの書き方」ばかりが議論されるが、海外のプロが磨いているのは AI チームの編成図 のほうだ。本記事ではこの「編成図」を Claude Code というツールに落とし込む完全マスター入門を、17 章のハンズオン形式で配る。CLAUDE.md・Plan Mode・Subagents・Skills・Hooks・MCP・Plugins・claude agents まで、公式情報のみを根拠に、コピペで真似していけば自然に強くなる順番で並べた。読了 25 分、習得まで 30 日。

user@sinyblog:~/article ❯ 01_tldr.md90 秒ダイジェスト：この記事のゴール

本記事のゴールは 1 つ。Claude Code を「賢いチャット」ではなく「AI チームの司令塔」として使えるようにすること。そのために以下 8 階層をコピペレベルの手順で身につけていく。

1. CLAUDE.md — プロジェクトの「常識」を恒久的に持たせる（4 層メモリ階層）
2. Plan Mode — 計画 → 承認 → 実行を強制する読み取り専用フェーズ
3. Output styles — システムプロンプトごと切り替える応答モード
4. Slash commands / Skills — 自作の作業テンプレを /command で呼ぶ
5. Subagents — 独立コンテキストの「専門家」を並列で召喚する
6. Hooks — Edit / Write のイベントで lint・通知を自動実行
7. MCP servers — Playwright / DB / GitHub などの外部ツール接続口
8. Plugins — 上記をパッケージ化してチームに配布

そして 13 章で バックグラウンドの主役 である claude --bg と claude agents、14 章で 暴走防止 の Permission modes、15 章で Anthropic 公式の 5 つのエージェントワークフローパターン を学び、16 章で巷で流通する誇張表現を 1 つずつ解毒する。

user@sinyblog:~/article ❯ 02_why-multi-agent.mdなぜ「1 人の AI」では限界か — 公式の 90.2% を正しく理解する

本論に入る前に「マルチエージェントは本当に効くのか？」を、Anthropic 公式の数字で確認しておきたい。あちこちで引用される「90.2%」の出典は、2025 年 6 月公開の社内エンジニアリングブログだ^[1]。

a multi-agent system with Claude Opus 4 as the lead agent and Claude Sonnet 4 subagents outperformed single-agent Claude Opus 4 by 90.2% on our internal research eval

Anthropic Engineering Blog “How we built our multi-agent research system”（2025-06-13）/ [1]

日本語に直すと「Claude Opus 4 を 司令官、Claude Sonnet 4 を 部下 としたマルチエージェント構成が、単独の Claude Opus 4 を、社内リサーチ評価で 90.2% 上回った」。よく誤解される 3 点を整理しておく。

同じブログには、タスクの複雑さに合わせた推奨規模も具体的に書かれている。

Simple fact-finding requires just 1 agent with 3-10 tool calls, direct comparisons might need 2-4 subagents with 10-15 calls each, and complex research might use more than 10 subagents with clearly divided responsibilities

Anthropic Engineering Blog 同上 / [1]

つまり 「事実を 1 つ調べるだけなら 1 体で十分、比較なら 2〜4 体、巨大リサーチなら 10 体以上」 という尺度。本記事もこの尺度に従って章を組んでいる。1 章ごとに、まず単独で動かし、必要なら徐々にチーム化していく順番だ。

user@sinyblog:~/article ❯ 03_install.mdDay 0：インストールと最初のセッション

まず手元に Claude Code を入れる。公式の CLI は npm パッケージで配布されている^[2]。Node.js さえあれば 1 コマンドだ。

# 1) インストール（要 Node.js）
npm install -g @anthropic-ai/claude-code

# 2) 初回認証（ブラウザが開く）
claude

# 3) いったん抜けてプロジェクトディレクトリへ
cd ~/work/my-project

# 4) そのリポを文脈にしてセッション開始
claude

「黄金の 5 コマンド」を最初に覚える

セッションが起動したら、まず次の 5 つを試す。これだけで Claude Code の基本操作はほぼカバーできる。

user@sinyblog:~/article ❯ 04_feature-map.md機能マップ — Claude Code の 8 つの拡張機構と編成図

Claude Code を司令塔にしてチームを動かすために理解しておくべき拡張機構は、大きく 8 つ だ。これらを「誰が何を担うか」の編成図として俯瞰しておく。以後の各章はこの順番で 1 つずつ深掘る。

user@sinyblog:~/article ❯ 05_claudemd.md階層①：CLAUDE.md — プロジェクトの「常識」を AI に教え込む

CLAUDE.md は セッション開始時に自動的に読み込まれる Markdown ファイル で、プロジェクトに関する持続的な指示を Claude に与える役割を持つ^[3]。Anthropic 公式は次のように説明している。

CLAUDE.md files are markdown files you write to give Claude persistent instructions for your project. They load at the start of every session and act as context, not enforced configuration. Shorter, more specific files produce better adherence than long documents.

code.claude.com/docs/en/claude-md / [3]

キモは「強制設定ではなくコンテキストとして機能する」「短く具体的なファイルの方が遵守率が高い」の 2 点。ダラダラ書くと逆に守られなくなる。

4 層のメモリ階層

最小実装テンプレ

# プロジェクト規約

## ビルドとテスト
- Build: `npm run build`
- Test: `npm test`
- コミット前: `npm run lint` を必ず通す

## コードスタイル
- インデント 2 スペース
- React は関数コンポーネントのみ
- API エラーは `{ error: string, code: number }` で返す

## アーキテクチャ
- `/src/components` — UI コンポーネント
- `/src/api` — Express ルーティング
- `/src/utils` — 共通ユーティリティ

## 守ってほしいこと
- 既存ファイルの編集を優先（不要なファイル新規作成は禁止）
- テストが落ちている状態で commit しない
- 機密ファイル（.env / *.key / credentials*.json）は読まない・書き換えない

@import 構文で分割する

規約が増えてきたら、@import で別ファイルに分割できる。再帰は最大 5 階層^[3]。

# Main Instructions

See @README.md for project overview.

# Build Commands
@./.claude/rules/build-rules.md

# API Standards
@docs/api-guidelines.md

user@sinyblog:~/article ❯ 06_plan-mode.md階層②：Plan Mode — 計画 → 承認 → 実行を強制する

Plan Mode は「変更を加えずに、調査して計画を出す」専用フェーズ。公式の説明は次のとおり^[4]。

Plan mode tells Claude to research and propose changes without making them. Claude reads files, runs shell commands to explore, and writes a plan, but does not edit your source.

code.claude.com/docs/en/permission-modes / [4]

起動の 3 方法

# 方法 1: CLI フラグで最初から
claude --permission-mode plan

# 方法 2: セッション中に Shift+Tab を 2 回
# default → acceptEdits → plan の順に切り替わる

# 方法 3: 単発のプロンプトに /plan を付ける
/plan ログイン周りのバグを調査して修正方針を出して

「Approve and …」の 3 択を意識する

計画が提示されたあとの承認画面では、次の実行モードを 3 つから選ぶ^[4]。

1. Approve and start in auto mode — 一気通貫で実行（多忙・信頼できる依頼向け）
2. Approve and accept edits — ファイル編集は自動承認、Bash は都度確認
3. Approve and review each edit manually — 1 つずつ目視承認（本番リポはこれ）

user@sinyblog:~/article ❯ 07_output-styles.md階層③：Output styles — 出力スタイルを職種で切り替える

Output styles は「システムプロンプト自体を切り替える」機構で、応答の根っこにある思考様式そのものを変える^[6]。CLAUDE.md が「足し算」なのに対し、Output styles は「土台を差し替える」イメージだ。

組み込み 4 スタイル

独自スタイルを 1 ファイルで作る

---
name: Diagrams first
description: 説明には必ず最初に図を 1 枚置く
keep-coding-instructions: true
---

コード・アーキ・データフローを説明するときは、
まず Mermaid 図を 1 枚出してから言葉で補足すること。

## 図の規約
- 制御フローは `flowchart TD`
- リクエスト経路は `sequenceDiagram`
- ノードは 15 個以内

切り替えはセッション開始時

Output styles の 変更はセッション開始時に確定 する。途中で /config から変えても、現在のセッションでは反映されない（prompt caching の安定性のため）^[6]。

user@sinyblog:~/article ❯ 08_skills.md階層④：Slash commands と Skills — 自作テンプレを /command 化

毎回同じ依頼を打つのが面倒になってきたら、スラッシュコマンド化 する。Claude Code には旧来の .claude/commands/*.md と、現在推奨の .claude/skills/<name>/SKILL.md 形式の 2 系統がある^[7]。新規は Skill 形式で書くのが公式の方針だ。

最小サンプル：/deploy を作る

---
description: 本番にデプロイする手順
disable-model-invocation: true
allowed-tools:
  - Bash(git status)
  - Bash(npm test)
  - Bash(npm run build)
  - Bash(npm run deploy)
---

## デプロイ手順

1. `git status` でワーキングディレクトリがクリーンか確認
2. `npm test` を流して全件パスを確認
3. `npm run build` でビルド
4. 問題なければ `npm run deploy` を実行
5. 完了後に Slack #deploy へ通知

引数を取る Skill

---
description: コンポーネントをフレームワーク間で移植する
arguments: [component, from, to]
---

$0 コンポーネントを $1 から $2 に移植せよ。
既存の挙動とテストを壊さず、命名規則は移行先に合わせること。

呼び出しは /migrate-component Button React Vue のように渡す。Skill 内では $0 = Button / $1 = React / $2 = Vue に展開される^[7]。

user@sinyblog:~/article ❯ 09_subagents.md階層⑤：Subagents — 独立コンテキストで「専門家チーム」を編成

ここまでは「1 人の Claude をどう躾けるか」の話だった。9 章からはいよいよ AI チーム編成 に入る。中核となるのが Subagents だ。

Subagents の正体

Subagent は 独立した system prompt・利用ツール・モデル・コンテキスト を持つ専門エージェント^[8]。親会話の履歴を持たず、結果だけ親に返ってくるのがポイント。だから親会話のコンテキストを汚さずに、重い調査や独立したレビューを並列で走らせられる。

最小定義：code-reviewer

---
name: code-reviewer
description: コードレビュー専門家。コード変更直後に必ず呼ぶ。品質・セキュリティを観点に。
tools: Read, Grep, Glob, Bash
model: sonnet
---

あなたはシニアコードレビュアー。次の手順でレビューせよ:

1. `git diff` で直近の差分を取得
2. 差分のあるファイルに集中
3. 以下のチェックリストで採点

## チェックリスト
- 命名と構造は読みやすいか
- 重複コードはないか
- エラーハンドリングは適切か
- API キー・シークレットが混入していないか
- テストが追加されているか

3 通りの呼び出し方

並列実行：「司令官 → 4 部下」の編成図

Anthropic の multi-agent ブログが推奨する「lead agent → subagents 並列」パターンは、Claude Code でもそのまま再現できる^[1]。子エージェントは親の tools に Agent(name) を含めることで起動権限を与える^[8]。

---
name: research-coordinator
description: 大物リサーチの司令官。fact-checker / competitive / outline / critic に並列で分解する。
tools: Agent(fact-checker, competitive, outline, critic), Read, Bash
model: opus
---

あなたはリード司令官。受け取ったリサーチ案件を次の 4 役に分解し、
それぞれに独立したコンテキストと指示書を渡し、最終出力を統合せよ。

1. fact-checker — 一次ソースで事実確認
2. competitive  — 競合・代替手段の比較
3. outline      — 読者向け構成設計
4. critic       — 出来上がった成果物への赤入れ

統合は司令官（あなた）の仕事。各役の生出力は捨て、整合済みの最終回答だけを返すこと。

ビルトインの 3 体（最初から使える）

user@sinyblog:~/article ❯ 10_hooks.md階層⑥：Hooks — Edit/Write をトリガに lint・通知を自動化

Hooks は Claude Code のライフサイクルイベントで任意のシェル／HTTP を起動 する仕組み^[9]。公式の説明は以下のとおり。

Hooks are commands or HTTP endpoints that Claude Code invokes at specific lifecycle events, allowing you to automate workflows, enforce policies, and extend permissions evaluation.

code.claude.com/docs/en/hooks / [9]

主なイベント（よく使う 6 つ）

最小実装：Edit/Write 後に ESLint を回す

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/lint-fix.sh",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

#!/usr/bin/env bash
# Claude Code の Hook から渡される JSON を stdin で受け取る
FILE=$(jq -r '.tool_input.file_path' < /dev/stdin)

if [[ "$FILE" =~ \.(ts|tsx|js|jsx)$ ]]; then
  npx eslint "$FILE" --fix
fi

exit 0

exit code の意味

user@sinyblog:~/article ❯ 11_mcp.md階層⑦：MCP servers — 外部ツール接続の標準口

MCP（Model Context Protocol）は Claude と外部ツール／データソースを繋ぐ共通プロトコル。Playwright・GitHub・各種 DB・Slack・Notion など、MCP サーバを 1 つ追加するごとに Claude Code から呼べるツールが一気に増える^[10]。

3 つのトランスポート

3 つのスコープ

最小実装：GitHub と Playwright を入れる

# GitHub（HTTP・認証ヘッダ付き）
claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_TOKEN"

# Playwright（stdio・ローカル起動）
claude mcp add --transport stdio playwright -- \
  npx -y @playwright/mcp

# 入っているか確認
claude mcp list

プロジェクト共有用の .mcp.json

{
  "mcpServers": {
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp"]
    },
    "db": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub", "--dsn", "${DB_URL}"],
      "env": { "DB_URL": "${DB_URL}" }
    }
  }
}

user@sinyblog:~/article ❯ 12_plugins.md階層⑧：Plugins — チームに配布する拡張パッケージ

ここまで作ってきた Skills / Subagents / Hooks / MCP を 1 つの単位にまとめてバージョン管理＆配布 したくなったら Plugin の出番だ^[11]。.claude/ 単発の standalone と Plugin の違いは次の通り。

公式マーケットプレイスから 1 行で入れる

# 公式マーケットプレイスから claude-code-setup を導入
/plugin install claude-code-setup@claude-plugins-official

# 入っているプラグイン一覧
/plugin list

# 公式マーケットの中をブラウズ
/plugin
# > Discover

公式マーケット claude-plugins-official（GitHub: anthropics/claude-plugins-official）には Anthropic 製のプラグインと、コミュニティ製のプラグインが両方並んでいる。詳細は前回記事 「claude-code-setup 完全ガイド」 を参照^[12]。

user@sinyblog:~/article ❯ 13_background.md主役の道具：claude --bg と claude agents を使いこなす

セッションを「裏で走らせて結果だけ受け取る」のがバックグラウンドセッション。長時間のリファクタ、マイグレーション、テスト追加などを任せて、自分は別の作業に戻れる^[13]。

3 つの起動パターン

# 1) 一気に裏に投げる
claude --bg "src/ 以下のテストを Pytest に書き直して。テスト命名は test_*.py で"

# 2) 対話中のセッションを途中で裏に回す
/bg

# 3) エージェントビュー（管制塔）を開く
claude agents

v2.1.142 で増えた 8 つのフラグ

2026 年 5 月のアップデートで claude agents 起動時に渡せるフラグが一気に増えた^[14]。「バックグラウンドで動かす Claude を起動の瞬間に躾ける」ことができるようになり、エンタープライズ用途で本気で使えるツールに化けた。

claude agents \
  --add-dir /repo/data-dumps \
  --permission-mode plan \
  --model opus \
  --effort high \
  --plugin-dir ./.claude/plugins \
  --mcp-config ./mcp.production.json \
  "S&P 500 IT 企業の取締役を全員特定し、出典 URL 込みで CSV にせよ"

user@sinyblog:~/article ❯ 14_permissions.mdPermission modes と Allowlist — 暴走を止める権限設計

AI チームを編成する以上、権限設計をサボると事故る。Claude Code は 6 つの権限モードと細かい allow/deny ルールでこれを制御する^[4]。

allow / deny ルールの最小例

{
  "permissions": {
    "defaultMode": "acceptEdits",
    "allow": [
      "Bash(npm run *)",
      "Bash(git status)",
      "Bash(git diff)",
      "Bash(git log *)",
      "Read(./src/**)",
      "Edit(./src/**)"
    ],
    "deny": [
      "Bash(rm -rf /)",
      "Bash(sudo *)",
      "Read(./.env*)",
      "Read(./**/*.key)",
      "Read(./**/credentials*)"
    ]
  }
}

覚えておきたい優先順位

1. deny は絶対 — 他のルールでは上書き不可。Hook でも上書きできない^[9]。
2. 評価順は deny > ask > allow。マッチした時点で確定。
3. Bash パターンは スペース境界が重要 — Bash(ls *) は ls -la にマッチ、lsof にはマッチしない。

user@sinyblog:~/article ❯ 15_five-patterns.mdAnthropic 公式 5 パターンで「AI チーム」を編成する

機能の解説は終わった。本章はそれらを 編成図 に落とすパート。Anthropic の Erik Schluntz / Barry Zhang が 2024 年 12 月に公開した名作 Building effective agents^[5] から、5 つのエージェントワークフローパターンを Claude Code 実装に翻訳していく。

各パターンの原文（公式定義）

Prompt chaining decomposes a task into a sequence of steps, where each LLM call processes the output of the previous one.

Routing classifies an input and directs it to a specialized followup task.

Parallelization: LLMs can sometimes work simultaneously on a task and have their outputs aggregated programmatically.

Orchestrator-workers: A central LLM dynamically breaks down tasks, delegates them to worker LLMs, and synthesizes their results.

Evaluator-optimizer: One LLM call generates a response while another provides evaluation and feedback in a loop.

Anthropic Research “Building effective agents”（2024-12-19）/ [5]

Evaluator-optimizer の実装例（一番効くやつ）

5 つの中で最も実装が簡単で、最も効果が大きいのが Evaluator-optimizer。「本体 Claude が生成したものを別の Claude が採点し、不合格なら差し戻す」だけ。Subagent 1 体追加で完成する。

---
name: critic
description: 成果物の評価者。100点満点で採点し、80点未満なら具体的な修正指示を返す。
tools: Read, Grep, Glob
model: sonnet
---

あなたは厳しい評価者。以下のルーブリックで採点せよ:

- 正確性 (40点): 事実誤認・出典欠落の有無
- 構造 (20点): 章立て・論理の流れ
- 実用性 (20点): 読者がそのまま使えるか
- 文体 (10点): 冗長・矛盾の有無
- セキュリティ (10点): 機密混入・危険コマンド誘発の有無

採点結果は次の JSON で返すこと:

{
  "score": <0-100>,
  "verdict": "pass" | "reject",
  "fixes": ["具体的な修正指示1", "..."]
}

80 点未満は reject。再提出を要求する。

使い方は簡単。本体 Claude に「出来上がったら必ず critic を通せ」と CLAUDE.md に書き、出力 → critic → 修正 → critic… を回す。これが「評価者 AI」の正体だ。

user@sinyblog:~/article ❯ 16_decoder.md煽り情報を解毒する — SNS でよく見る誇張表現の答え合わせ

本記事を書くきっかけになった X 上の煽り投稿には、確かに 骨格として正しい主張 が混ざっている。一方で 数字や用語の不正確さ も同居していて、そのまま暗記すると後で恥をかく。ここで 5 つの主張を 1 つずつ事実検証しておく。

user@sinyblog:~/article ❯ 99_30days.mdまとめ：明日から 30 日でマスターするロードマップ

17 章を駆け抜けた。最後に「実際の習得スケジュール」を示す。1 日 30 分でこなせる粒度に切ってある。

30 日後、あなたの手元には次のものが揃っている。

1. 200 行以下に整った CLAUDE.md — プロジェクトの「常識」が言語化された状態
2. 自作 Skill 3 個＋ Subagent 2 体＋ Hook 2 個 — 日常作業の半分が自動化された状態
3. 本番リポ向け settings.json — 暴走しない権限設計が完成した状態
4. Evaluator-optimizer ループ — 出した成果物が必ず critic を通る品質保証ライン

ここまでくれば、もう「1 人の AI に祈る」段階ではない。あなたは AI チームの司令官 になっている。

武器を 1 本だけ持って戦場に出る時代は終わった。明日から、編成図 を握って戦場に出よう。