Claude Code Subagents 実践活用ガイド｜factcheck・self-eval・research エージェント自作完全マニュアル【2026年5月】

Claude Code でファクトチェック・自己評価・調査を毎日回している筆者が、Subagents（サブエージェント）の実装と運用ノウハウを全公開します。本記事では .claude/agents/ のYAMLフロントマター構造から、factcheck・self-eval・research の3つの実装、複数Subagentの並列実行、そして「path-scoped rulesがSubagentに届かない」という致命的な落とし穴の回避策まで、2026年5月時点の最新仕様で全部解説します。読了後すぐにあなたの .claude/agents/ に貼り付けて使える実コードを公開する、E-E-A-T全振りの実践マニュアルです。

目次

Claude Code Subagentsとは何か｜独立コンテキストの専門エージェント

Subagentsとは、Claude Codeの中で動く独立したコンテキストウィンドウを持つ専門AIアシスタントです。メイン会話とは別の作業空間でタスクを実行し、終わったら結果の要約だけをメインに返す、いわば料理に例えると「下処理係」「ソース係」「盛り付け係」を別々に立てて、最後にシェフ（メインClaude）が組み上げるような分業モデルのようなものです。

2026年5月時点のClaude Codeでは、Anthropic公式に明記の通り各Subagentは独立コンテキスト・カスタムプロンプト・限定ツール・独立権限を持ち、メインがコードレビューに集中している間に別Subagentが裏でファクトチェックを並列で回す運用が標準です。

重要な変更としてバージョン2.1.63で「Task tool」が「Agent tool」にリネームされました。既存Task(...)は互換エイリアスですが、新規はAgent(...)推奨です。

Subagentsが解決する5つの課題

Subagentsは以下のシーンで威力を発揮します。1つでも当てはまる業務があれば、導入検討に値します。

• コンテキスト保護：探索や調査ログを別Subagentに切り出してメインを節約
• 制約の強制：書き込みツールを取り上げて読み取り専用にする等、安全側に倒せる
• 設定の再利用：~/.claude/agents/に置けば全プロジェクトで同じSubagentが呼べる
• 専門化：役割を絞ったシステムプロンプトで精度向上
• コスト制御：軽い分類はhaiku、深いレビューはopusのようにモデル使い分け

なぜSubagentsが単発プロンプトより強いのか

「サブエージェント立てるくらいなら、メイン会話で続けて頼めば良いのでは」と思うかもしれません。実は、これが初心者がSubagentsの真価を理解できない最大の理由です。違いは3点あります。

違い1：コンテキスト汚染が起きない

メイン会話で「この記事をファクトチェックして」と頼むと、検証ログがメインを埋め尽くしメインClaudeの判断精度が落ちます。Subagentに切り出すと検証は別ウィンドウで完結し、メインには結果の要約だけが返ります。たとえるなら図書館で本を借りる時、図書館の中身ごと家に持ち帰らずに必要なページだけメモして帰るのと同じようなものです。

違い2：構造化された出力が保証される

単発プロンプトの結果は会話風になりがちですが、Subagentのシステムプロンプトで「### N. 項目名のheading形式・一次ソースURL必須」と明文化すれば、毎回同じフォーマットで出力されます。フォーマットが安定すると、bashのgrepとpython3で検証する品質ゲートを後段に挟め、形式違反は自動FAILにできます。

違い3：並列実行で時間が短縮される

記事完成後の「ファクトチェック→自己評価→ツイート生成」を直列で回すと10〜15分かかります。同じ作業を3つのSubagentで並列起動すると、最も遅いタスクの時間（約3分）で全部終わります。ちょうどレストランで前菜・メイン・デザートを別々のシェフが同時調理するように、所要時間はキッチンの規模に比例しません。Claude Codeも複数Subagentを同時起動でき、メイン会話は完了通知を受け取るだけです。

Subagentsの基本構造｜.claude/agents/とYAMLフロントマター

SubagentsはYAMLフロントマター付きのMarkdownファイルとして定義します。配置場所によってスコープが変わり、優先度の高い場所に置いた定義が同名の低優先度を上書きします。

5つの配置場所と優先度

個人なら~/.claude/agents/、チーム共有なら.claude/agents/でgit管理が標準です。自社では.claude/agents/とscripts/agent-prompt-prefix.shをリポジトリに含めて、複数マシン間で共有しています。

YAMLフロントマターの必須・任意フィールド

Subagentファイルの構造は以下のとおりです。必須はnameとdescriptionの2つだけで、残りは任意です。

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

主要フィールドを表で整理しておきます。2026年5月時点の公式仕様に準拠した内容です。

このうち実運用で最もよく使うのはtoolsとmodelとmaxTurnsです。料理に例えると、toolsは「使ってよい調理器具のようなもの」、modelは「シェフの腕（haiku=見習い、sonnet=中堅、opus=ベテラン）に相当する」、maxTurnsは「営業時間の上限のようなもの」。役割と難易度に応じて使い分けます。

ステップ1：最初のresearch Subagentを作る

最初に作るべきは「調査専門」のresearch Subagentです。書き込み権限が要らず安全、WebSearchを大量使ってもメインを汚さない、効果が即日体感できる、の3つが理由です。

research Subagentの最小実装

以下を.claude/agents/research.mdとして保存してください。これだけで動きます。

---
name: research
description: 一次ソースを優先して調査する専門エージェント。製品仕様・料金・最新ニュース等の事実確認に使う
tools: Read, Grep, Glob, WebSearch, WebFetch
model: sonnet
maxTurns: 15
color: blue
---

あなたは oishi-ai プロジェクトのリサーチサブエージェントです。以下を遵守してください:

- 一次ソース優先（公式ドキュメント・公式ブログ・主要メディア）
- 各事実に必ずURLを添える
- 推測と事実を明示的に分ける
- 鮮度確認（情報が公開日時点で最新か）
- 出力は箇条書きで、各項目に【結論】【根拠URL】【未確認の論点】を明記
- 完了時は PASS/FAIL と項目数を1行で報告

呼び出し方

メインClaudeに「Researchエージェントで〇〇を調べて」と頼むと、自動でresearch Subagentが起動します。明示的に呼ぶには Agent tool（旧Task tool）でsubagent_type: researchを指定します。バージョン2.1.63以前で書かれたTask(...)も互換エイリアスとして動きますが、新規実装はAgent(...)で書いてください。

研究室の「文献係」のようなものです。本棚と検索だけ使え、勝手にコードを書き換えません。結果は要約だけ返り、メインのコンテキストを節約しつつ調査の質を上げる分業ができあがります。

ステップ2：factcheck Subagent（自社実装公開）

research Subagentに慣れたら、次はfactcheck Subagentです。記事公開前に「全データを一次ソースで再確認」する専門係を立てます。自社の本番運用版を全文公開します。

factcheck Subagentの実装

以下を.claude/agents/factcheck.mdとして保存します。実コードはXServer MCP記事やAI半自動化記事の検証で365日動いている版です。

---
name: factcheck
description: 記事内の全データ（料金・日付・統計）を一次ソースで検証する。記事公開前に必ず実行
tools: Read, Grep, Glob, WebSearch, WebFetch, Bash
model: sonnet
maxTurns: 20
color: orange
---

あなたは oishi-ai プロジェクトのファクトチェック専任エージェントです。
以下のフォーマットで `tasks/factchecks/factcheck-<slug>.md` に記録してください。

## 検証ルール
1. 検証項目は最低5件
2. 各項目に一次ソースURL必須
3. 鮮度検証（公開日時点で最新か）
4. 廃止製品検出（shutdown/EOL/サービス終了の対象でないか）
5. tier 開示違反検出
6. 検証フォーマット：

```
### N. 項目名
- 記事内記述: ...
- 検証結果: 一致 / 一致しない
- 一次ソース: https://...
- 備考: ...
```

## 出力ファイル先頭に必須
`コンテンツハッシュ: <SHA-256>`

## 完了報告
PASS: N件 / 要修正: N件 を1行で返す。

呼び出しと並列実行

本文完成直後にAgent(subagent_type: "factcheck", prompt: "<記事パス> を検証して")で起動します。所要時間は1記事あたり30秒〜2分。複数記事の同時検証も並列起動で相互干渉しません。

機械検証との連携

factcheck Subagentが書き出したtasks/factchecks/factcheck-<slug>.mdは、後段の機械検証スクリプト（scripts/quality-gate.sh）で自動チェックされます。検証項目5件以上・一次ソースURL必須・URL到達確認（HTTP 4xx/5xxでFAIL）・記事内主張のカバー率70%以上などを機械が判定し、人間の目視判断と二重で防御します。

ステップ3：self-eval Subagent（自社実装公開）

self-eval Subagentは「9項目×10点満点で記事の自己採点」をする専門係です。普通の「どう？」レビューだと「良いと思います」で終わりがちですが、self-evalは構造化された採点フォーマットで強制的に厳しめのレビューを引き出します。

self-eval Subagentの実装

以下を.claude/agents/self-eval.mdとして保存します。

---
name: self-eval
description: 記事を9項目×10点満点で構造化採点する。記事公開前に必ず実行
tools: Read, Grep, Glob, Bash
model: sonnet
maxTurns: 15
color: purple
---

あなたは oishi-ai プロジェクトの自己評価専任エージェントです。
記事を9項目×10点満点で採点し、`tasks/factchecks/self-eval-<slug>.md` に保存します。

## 評価項目（9項目）
- コンテンツ品質 / 文章品質 / SEO / 構造 / 画像
- 独自性 / 読者価値 / モバイル / 技術正確性

## フォーマット（厳守）

```
コンテンツハッシュ: <SHA-256>

| 項目 | スコア | 根拠 |
|------|--------|------|
| コンテンツ品質 | 10/10 | （15文字以上の固有根拠） |
...
```

## 改善提案セクション（必須）
完璧な記事は存在しない。最低50文字・最低3点の改善提案を必ず含める。
0件はFAIL。

## 完了報告
9項目すべて満点なら PASS、1項目でも欠ければ FAIL を1行で返す。

「完璧な記事は存在しない」前提の力

self-evalで最も重要なのは「改善提案セクション必須・最低50文字・0件はFAIL」のルールです。これがないと「全項目10/10、改善点なし」のようなコピペ採点が量産されます。たとえるなら健康診断で「全項目正常」しか言わない医師みたいなもので、改善余地を絞り出す設計にすることで形骸化を防ぎます。

ステップ4：rules注入の落とし穴とagent-prompt-prefix.shの解

ここからが本記事の最重要セクションです。Subagentsを実運用に乗せた時に必ずぶつかる「rulesがSubagentに届かない」問題と、その解決策を公開します。

致命的な落とし穴：path-scoped rulesはSubagentに継承されない

Claude Codeでは.claude/rules/*.mdにプロジェクト固有のルールを置くと、特定パスのファイルを編集する時にメインClaudeがそのrulesを自動ロードします。これがpath-scoped rules機能で、便利な仕組みです。しかし、これらのrulesはSubagentに自動では渡りません。

Subagentは自分のシステムプロンプト（YAMLフロントマター下のMarkdown本文）と環境情報（CWD等）しか受け取りません。メインClaudeがロードしたrulesは別コンテキストなので、Subagent側には存在しないも同然です。この事実を知らずに「メインで設定したrulesが効くだろう」と思ってSubagentに記事執筆を任せると、tier開示違反・廃止製品の誤記・禁止ワード使用などの事故が起きます。

2026年4月の実際の事故

2026年4月のあるOSSプロジェクトでも同種の事故が記録されています。記事連動ツイートの生成をSubagentに任せたところ、tier開示禁止ルール（個人プランの開示禁止）が効かず、ツイート本文に契約プランや課金額がそのまま書き出されて投稿される寸前まで行きました。メインClaude側にtier開示禁止のrulesは確かに存在していましたが、Subagent側には届いていなかったのです。

解決策：agent-prompt-prefix.shでrulesを強制注入

解決策はシンプルで、Subagent起動時にrulesをcatして人間が手動でプロンプト先頭に貼り付ける運用にします。これを自動化するのが、自社で運用しているヘルパースクリプトscripts/agent-prompt-prefix.shです。以下が要約版です（フル版はGitHubで公開）。

#!/usr/bin/env bash
# agent-prompt-prefix.sh
# 使い方: bash scripts/agent-prompt-prefix.sh <factcheck|self-eval|article|tweet|research>

set -euo pipefail
REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
TYPE="${1:-help}"

emit_section() {
  echo ""
  echo "## $1"
  echo ""
  cat "$2"
}

case "$TYPE" in
  factcheck|self-eval)
    cat <<'EOF'
# ⚠️ サブエージェント向け強制ルール (oishi-ai)
あなたは oishi-ai のサブエージェントです。以下を必ず守ってください。
EOF
    emit_section "tier 開示禁止ルール" "$REPO_ROOT/.claude/rules/tier-disclosure.md"
    emit_section "品質ゲート・ファクトチェック・自己評価ルール" "$REPO_ROOT/.claude/rules/quality-gate.md"
    ;;
  article)
    emit_section "記事執筆ルール" "$REPO_ROOT/.claude/rules/quality-gate.md"
    emit_section "SVGデザインルール" "$REPO_ROOT/.claude/rules/svg-design.md"
    ;;
  # ... 他のtypeも同様
esac

使い方

Subagentを起動する直前にメインClaudeで以下を実行し、出力をAgent toolのpromptパラメータの先頭にコピペします。

$ bash scripts/agent-prompt-prefix.sh factcheck > /tmp/prefix.txt
$ cat /tmp/prefix.txt <ここで実際のタスク指示を続ける>

これでSubagentはメインで設定したtier-disclosure.mdとquality-gate.mdを必ず読んでから作業を始めます。「rulesが届かない」事故は構造的に消えます。記事公開パイプラインのワンライナーに組み込めば、忘れることもありません。

ステップ5：複数Subagentの並列実行と通知

Subagentsの真価は並列実行です。複数Subagentを同時起動でき、記事公開フローを例に整理します。

記事公開時の並列フロー

本記事執筆中も、以下のフローが実際に走っています。

1. メインClaude：記事HTML完成・コンテンツハッシュ計算
2. Agent(subagent_type: factcheck) を background:true で起動 → 30秒〜2分
3. Agent(subagent_type: self-eval) を background:true で同時起動 → 30秒〜1分
4. メインClaude：その間に画像配置・ツイート文作成を進める
5. 2つのSubagentが完了通知 → 結果ファイル（factcheck-<slug>.md / self-eval-<slug>.md）を読んで品質ゲート実行

料理に例えると、シェフが本盛り付け作業をしている間に、ホールスタッフが伝票チェック、ソムリエがワイン選定を別々に並列で進める感覚です。3つの作業を直列で回すと10〜15分かかるところを、並列なら最も遅い1本の時間（2分）で終わります。

completion通知の活用

Subagent完了時にメインへ「Agent <name> completed」通知が返るので、ポーリング不要で即座に結果ファイルを読めます。Claude Code×Cron自動化と組み合わせれば、夜間バッチでの記事ファクトチェックも完全自動化できます。

コスト最適化のコツ

並列実行はSubagent数を増やすほど合計トークンも増えます。自社運用ではモデルを以下のように使い分けています（AIベンチマーク記事の性能差を逆手にとって軽量モデル併用）。

• haiku：分類・抽出・短文要約（コスト軽量・速度最速）
• sonnet：factcheck・self-eval・research（バランス型）
• opus：複雑なコードレビュー・アーキテクチャ判断（深い推論が必要な時のみ）
• inherit：メイン会話と同じモデル（迷ったらこれ）

よくある失敗5パターンと回避策

Subagents運用で実際にぶつかった失敗を5パターンに整理しました。先回りで知っておくと、無駄な事故を減らせます。

失敗1：rulesがSubagentに届かないと誤認する

ステップ4で詳述の通り、.claude/rules/*.mdはSubagentに自動継承されません。agent-prompt-prefix.shのようなヘルパーで強制注入してください。

失敗2：tools を絞らずに書き込み権限を渡す

Write権限が残ったまま調査Subagentを動かすと事故ります。読み取り専用ならtools: Read, Grep, Glob, WebSearch, WebFetchと明示し、またはdisallowedTools: Write, EditでWrite/Editだけ抜きます。

失敗3：maxTurnsを設定せず無限ループに陥る

Subagentが解けないタスクで延々ループしトークンを焼くケースがあります。maxTurns: 15を必ず設定し、超過したら「FAIL: 15ターン超過」と返させる設計が安全です。航空機の燃料計のようなもので、上限を切らないと墜落します。

失敗4：複数Subagentで同一ファイルを書き換えて衝突

並列Subagentが同じファイルを書き換えると、最後に書いた方が勝つ競合が起きます。isolation: worktreeで隔離コピーを渡すか、書き込み先ファイルをSubagentごとに分けて回避します。

失敗5：description が曖昧で自動デリゲートが効かない

Claude Codeはdescriptionを見て自動でSubagentにタスクを振ります。「コードを助ける」のように曖昧だと判断できないので、「製品仕様・料金・最新ニュース等の事実確認に使う」と具体化すると自動デリゲートが正確に動きます。

よくある質問（FAQ）

Q1. Subagentから別のSubagentを呼べますか？

はい、toolsにAgentを含めれば呼べます。Agent(agent_type)構文でspawn可能なSubagentを限定することも可能です。ネストが深くなると追跡が困難になるので、最大2層を推奨します。

Q2. Subagentのmemoryフィールドって何ですか？

user/project/localの3スコープから選べる永続記憶機能で、セッションをまたいで学習を保持できます。ただし誤情報を覚えると次回以降の出力が劣化するので、factcheck/self-evalでは敢えて使っていません。

Q3. backgroundとisolationの違いは？

backgroundは「メイン会話と並列で動かす」、isolationは「作業空間を隔離する」フラグです。ファイル変更を伴うrefactor系エージェントにはisolation: worktreeを必ず付けます。

Q4. Subagentと/ultrareviewはどう違う？

/ultrareviewはクラウド側で複数Subagentが並列レビューする公式機能でブランチ全体の総合レビュー向き。自作Subagentはローカルで実行する個別品質ゲート向き。両者は/ultrareviewでPR全体→自作Subagentで個別検証、の二段構えで使えます。

まとめ｜Subagentsは「分業」で品質と速度を両立させる

本記事では、Claude Code Subagentsの作り方を自社運用のfactcheck・self-eval・research実装ベースで2026年5月時点の最新仕様で解説しました。要点を整理すると次のとおりです。

1. Subagentsは独立コンテキスト・カスタムプロンプト・限定ツールで動く専門エージェント
2. .claude/agents/<name>.md にYAMLフロントマター付きで配置（必須はname/descriptionのみ）
3. research → factcheck → self-eval の3段構成で記事品質を担保
4. path-scoped rulesはSubagentに届かない。agent-prompt-prefix.shで強制注入する
5. 複数Subagentを並列実行すれば、直列10〜15分の作業が2〜3分で完了
6. 失敗5パターン（rules未注入・tools過剰・maxTurns未設定・ファイル衝突・description曖昧）を先回りで潰す

Subagentsを分業の仕組みとして設計すると、Claude Codeの品質と速度が同時に上がります。まずは.claude/agents/research.mdを1ファイル置いて「Researchエージェントで〇〇を調べて」と頼んでみてください。1回でメインコンテキストの軽さに気づくはずです。factcheck → self-evalと段階的に増やすのが、挫折しない王道ルートです。

参照元

• Anthropic公式｜Create custom subagents（2026年5月時点の最新仕様）
• Anthropic公式｜Subagents in the Agent SDK
• Anthropic公式｜Discover and install Claude Code plugins
• GitHub｜anthropics/claude-plugins-official
• 関連記事｜Claude Code 5月update（/ultrareview解説）
• 関連記事｜XServer公式MCP×Claude Codeガイド
• 関連記事｜Claude Code×Cron×Vercel自動化システム
• 関連記事｜AI半自動化7ステップ
• 関連記事｜AIベンチマーク初心者ガイド