Claude Codeサブエージェント実装ガイド: 記事・コード作業を安全に並列委譲する方法

Claude Codeで記事制作やコード修正を長く続けると、最初に壊れるのはモデル性能ではなく「作業の分け方」です。10言語の記事、複数ディレクトリの実装、レビュー、翻訳、検証を1本の会話に詰め込むと、文脈が重くなり、同じ調査を繰り返し、最後にどのファイルを誰が触ったのか分からなくなります。

サブエージェントは、この混乱を減らすための委譲先です。ここでいう委譲とは「丸投げ」ではなく、目的、触ってよいファイル、返してほしい証跡を小さな契約として渡すことです。ClaudeCodeLabでは、記事の下調べ、10ロケール翻訳、コード例の検証、公開前レビューを分けるだけで、手戻りがかなり減りました。

この記事では、初心者にも分かる言葉で、サブエージェントをいつ使うか、どのように作業範囲を切るか、失敗しやすい委譲をどう避けるかをまとめます。コピペで使える委譲プロンプト、レビュー用チェックリスト、ClaudeCodeLabの記事運用に近い実例も入れています。

サブエージェントとは何か

サブエージェントは、メイン会話とは別の文脈で動く専門作業者です。文脈とは、Claudeがその時点で覚えている会話、読んだファイル、コマンド出力、指示のまとまりです。大きな調査やログ出力をサブエージェントに任せると、メイン会話には要約だけを戻せるため、作業机を散らかしにくくなります。

公式情報は、Claude CodeのSubagents、Memory、Slash commandsを確認してください。特に、サブエージェントは新しい独立した文脈で始まること、.claude/agents/に置くプロジェクト用エージェントはチームで共有できること、長い結果を返しすぎるとメイン会話の文脈も消費することは重要です。

用語を先に平易にしておきます。

用語	この記事での意味
サブエージェント	別室で調査、実装、翻訳、レビューをする専門担当
コンテキスト	Claudeが今見えている会話とファイル情報の作業机
disjoint write set	同時作業者が触るファイルを重ねない分担。日本語では「重ならない編集範囲」
explorer	まず読むだけの調査担当。原則として編集しない
worker	決められたファイルだけ編集する実装担当
handoff contract	目的、範囲、禁止事項、完了条件、戻り値を書いた作業契約

いつ委譲し、いつ委譲しないか

サブエージェントは万能ではありません。短い修正を分けすぎると、各エージェントが同じファイルを読み直し、かえって遅くなります。判断基準は「文脈を分ける価値があるか」と「編集範囲を重ねずに切れるか」です。

仕事	委譲向きか	理由
10言語の記事翻訳	向いている	言語ごとに編集ファイルが分かれ、品質観点も明確
既存記事の重複調査	向いている	大量検索の結果を要約だけ戻せる
1ファイルの小さな文言修正	メインでよい	委譲の説明コストのほうが大きい
認証処理の横断リファクタ	計画後なら可	先に explorer で影響範囲を確定する必要がある
仕様が曖昧な新機能	まだ早い	メイン会話で要件確認を先にしたほうが安全

私の基準では、サブエージェントに任せるのは次の3条件を満たすときです。

• 探索結果、ログ、翻訳候補など、メイン会話に全部置くと重い情報が出る
• 担当ごとの編集ファイルを明確に分けられる
• 返してほしい形式をチェックリストや表で指定できる

逆に、要件の会話がまだ揺れているとき、同じファイルを複数人が編集しそうなとき、秘密情報を読ませる必要があるときは止めます。秘密情報はサブエージェント以前の問題で、プロンプトにもログにも載せない運用が基本です。

全体像: explorer、worker、reviewerを分ける

ClaudeCodeLabの記事制作では、いきなり10言語を編集しません。まず explorer が読むだけで状況を集め、次に worker が担当ファイルだけ編集し、最後に reviewer が差分とチェック結果を見る流れにします。

flowchart TD
  A["Main: goal and constraints"] --> B["Explorer: read only, map scope"]
  B --> C["Main: decide write sets"]
  C --> D["Worker JA: canonical article"]
  C --> E["Worker EN/ZH/KO...: localized files"]
  D --> F["Reviewer: metadata, links, prompts"]
  E --> F
  F --> G["Main: run focused checks and final handoff"]

この図で大事なのは、workerを先に増やさないことです。調査前にworkerを並べると、それぞれが同じ記事、同じ関連リンク、同じfrontmatterを読み始めます。速く見えて、実際には重複作業が増えます。

実例1: 10ロケール記事を安全に分担する

今回のように claude-code-subagent-patterns を10言語で改善する場合、理想は「日本語canonicalを先に確定し、各言語はそれを自然にローカライズする」流れです。canonicalとは基準になる原稿です。ここが薄いまま翻訳すると、10言語すべてが薄い記事になります。

分担は次のように切ります。

担当	編集してよいファイル	やること
ja-worker	site/src/content/blog/claude-code-subagent-patterns.mdx	構成、実例、プロンプト、CTAを作る
western-locale-worker	blog-en, blog-es, blog-fr, blog-de, blog-pt	機械翻訳調を避けて自然に翻訳する
asia-locale-worker	blog-zh, blog-ko, blog-hi, blog-id	用語を各文化圏の読者向けに置き換える
review-agent	10ファイルすべてを読むだけ	frontmatter、文字化け、コードフェンス、リンクを確認する

ここでのコツは、翻訳agentに「要約するな」と明示することです。AI翻訳は、長い記事を短く整えてしまうことがあります。記事品質の観点では、自然さだけでなく、実例、失敗例、チェックリストが欠けていないことまで指定します。

Use a translation subagent for the assigned locale files only.

Source:
- Japanese canonical file: site/src/content/blog/claude-code-subagent-patterns.mdx

Allowed write set:
- site/src/content/blog-en/claude-code-subagent-patterns.mdx
- site/src/content/blog-es/claude-code-subagent-patterns.mdx

Rules:
- Do not summarize. Localize the full guide.
- Keep frontmatter valid and preserve heroImage.
- Use natural SEO terms for each language.
- Keep prompt templates copy-pasteable.
- Do not edit Japanese or other locale files.

Return:
- Files changed
- Localization choices
- Any terms that may need human review
- Checks performed

実例2: 記事内コード例を検証担当に渡す

記事制作では、本文を書く人とコードを試す人を分けると品質が上がります。たとえば、記事に .claude/agents/article-reviewer.md の例を載せるなら、writerは解説に集中し、verification agent はコードフェンスを抽出して構文やファイル配置を確認します。

---
name: article-reviewer
description: Reviews ClaudeCodeLab articles for originality, implementation detail, SEO, and publication risk.
tools: Read, Grep, Glob
---

You review article drafts critically.
Check whether the draft has concrete examples, pitfalls, working prompts,
official links, internal links, and a clear CTA.
Return findings first, then a short pass/fail recommendation.

この例は、実装コードというよりサブエージェント定義ファイルです。nameは小文字とハイフンで一意にし、descriptionには「いつ使うべきか」を書きます。長すぎるsystem promptは管理しづらいので、よく使う観点はCLAUDE.mdや記事チェックリストに逃がします。詳しくはCLAUDE.mdベストプラクティスとコンテキスト管理ガイドも合わせて読むと安全です。

実例3: コード修正を重ならない編集範囲で切る

コード作業でも考え方は同じです。たとえばブログサイトで「記事カードの表示」「OGP生成」「関連記事ロジック」を同時に直すなら、workerごとに触るファイルを固定します。

We will use three workers with disjoint write sets.

Worker A:
- May edit: site/src/components/BlogCard.astro
- Must not edit: layouts, pages, content files
- Goal: improve card metadata rendering only

Worker B:
- May edit: site/src/pages/og/[...slug].png.ts
- Must not edit: components or article files
- Goal: verify OGP title and hero behavior

Worker C:
- May edit: site/src/lib/relatedPosts.ts
- Must not edit: components, pages, content files
- Goal: improve related-post selection without changing routes

All workers return a handoff receipt with changed files, reasoning, tests, and risks.

この分け方なら、後から差分を見ても衝突が起きにくいです。逆に「UI全体をよくして」と3人に頼むと、全員が同じコンポーネントを触り、最後に統合で壊れます。並列化の本質は人数を増やすことではなく、衝突しない作業面を先に作ることです。

実例4: reviewerとverification agentを最後に置く

サブエージェントは実装者だけではありません。むしろ最後のreviewerとverification agentが効きます。reviewerは「読者価値、SEO、落とし穴、重複」を見る担当、verification agentは「ビルド、リンク、コードフェンス、文字化け」を見る担当です。

Use a review subagent in read-only mode.

Scope:
- Read only these 10 localized files for slug claude-code-subagent-patterns.
- Do not edit anything.

Review checklist:
- description is 120 characters or fewer
- updatedDate is 2026-06-02
- heroImage is retained
- each locale is a full localized article, not a thin summary
- at least 3 concrete use cases are present
- pitfalls and failure modes are concrete
- code fences are balanced
- official external links and internal links are present
- CTA is natural and relevant

Return findings by severity with file paths and line numbers where possible.

この読み取り専用レビューは、人間のレビュー前にとても役立ちます。特に多言語記事では、本文が自然でもfrontmatterの日付だけ古い、Hindiだけコードフェンスが閉じていない、PortugueseだけCTAが抜けている、という小さな事故が起きます。

そのまま使える委譲プロンプト

最初に貼るオーケストレーション用プロンプトです。メイン会話で使います。

You are the orchestrator. Before using subagents, create a delegation plan.

Goal:
- [one sentence goal]

Hard constraints:
- Work only on: [exact files or directories]
- Do not edit: [out of scope]
- Preserve: [metadata, public API, routes, screenshots, etc.]
- Verification required: [commands or manual checks]

Ask explorer agents to read first. Do not start workers until write sets are disjoint.
For every worker, define:
- allowed write set
- forbidden files
- expected output
- done condition

Final response must include:
- changed files
- checks run
- remaining risks

調査担当用です。

Use an explorer subagent in read-only mode.

Task:
- Map the current state of [feature/article/slug].
- Find existing conventions, related files, internal links, and quality gaps.

Rules:
- Do not edit files.
- Prefer search and targeted reads over full-directory dumps.
- Return only the useful summary, not raw command output.

Return:
- Files that matter
- Existing patterns to follow
- Risks or unclear requirements
- Suggested write sets for workers

実装担当用です。

Use a worker subagent for this isolated edit.

Allowed write set:
- [file 1]
- [file 2]

Forbidden:
- Do not edit files outside the allowed write set.
- Do not stage, commit, push, deploy, or rewrite unrelated changes.
- If the task requires another file, stop and report why.

Implementation goal:
- [specific behavior or article quality outcome]

Return a handoff receipt:
- Files changed
- Summary of changes
- Commands or checks run
- Evidence of success
- Remaining risk

翻訳担当用です。

Use a locale translation subagent.

Source canonical:
- [source file]

Target locale:
- [locale and target file]

Localization rules:
- Translate the full article; do not summarize.
- Use natural local terms for Claude Code, subagent, delegation, review, and verification.
- Keep code prompts useful for local readers, but preserve file paths and commands.
- Keep official links unchanged unless a reliable localized official page exists.
- Keep internal links in the locale route.

Return:
- Target file changed
- Terms localized intentionally
- Any phrase that still needs native review

失敗例と落とし穴

一番多い失敗は、編集範囲を切らずに並列化することです。全員に「記事を良くして」と頼むと、タイトル、導入、CTAを全員が触ります。差分は増えますが、品質は上がりません。必ず「このworkerはこのファイルだけ」「このagentは読むだけ」と分けます。

二つ目は、explorerの出力を長くしすぎることです。サブエージェントの結果もメイン会話に戻した時点で文脈を消費します。大量ログ、全文引用、検索結果の全件貼り付けは禁止し、判断に必要な表と結論だけ戻します。

三つ目は、handoff contractが薄いことです。「いい感じに翻訳して」では、トーン、長さ、SEOキーワード、内部リンク、CTAが揺れます。「要約禁止」「frontmatter維持」「失敗例を残す」「ローカル読者に自然な用語にする」と書くと、戻り品質が安定します。

四つ目は、reviewerを実装者と同じ観点にしてしまうことです。実装者は自分の前提を信じやすいので、reviewerには「疑って読む」「差分と要件の不一致を探す」「公開リスクを先に出す」と指示します。コードレビューではClaude Codeコードレビューチェックリストのように、リスク別に見る観点を決めると抜け漏れが減ります。

五つ目は、新しく作ったエージェント定義がすぐ使えると思い込むことです。ファイルベースのagentは起動時に読み込まれるため、作成後にセッションを再起動したほうが確実な場合があります。長いpromptをCLI引数に詰めるより、.claude/agents/に短く整理して置くほうがチーム運用では扱いやすいです。

コンテキスト予算を守るルール

サブエージェントを使うほど、メイン会話は軽くなると思いがちですが、戻り値を全部貼れば同じように重くなります。予算を守るには、開始前に「戻してよい情報量」を決めます。

Context budget rule:
- Explorer returns at most 20 bullets and 1 table.
- Worker returns changed files, decisions, and checks only.
- Reviewer returns findings by severity, no full rewritten article.
- Logs longer than 80 lines must be summarized.
- If uncertainty remains, ask one focused question instead of dumping raw output.

ClaudeCodeLabの記事運用では、各agentに「証跡は短く、再現コマンドは残す」と頼みます。本文の品質は長くてもよいですが、handoffは短くします。ここを混ぜると、メイン会話が記事本文、翻訳メモ、検証ログで埋まります。

小さく始める導入手順

チームで最初に試すなら、いきなり実装agentを量産しないほうが安全です。まずは「読むだけのexplorer」と「読むだけのreviewer」から始めます。編集しないagentなら、失敗しても差分を壊しません。既存記事を1本選び、explorerに関連リンク、重複記事、足りない実例を調べさせ、reviewerに公開前チェックだけを任せます。この2つで十分に価値が出てから、workerを増やします。

次に、1つの編集workerだけを使います。たとえば日本語canonicalだけを編集対象にし、翻訳ファイルは触らせません。完了後に、人間かreviewerが差分を読み、問題がなければ英語と中国語だけに対象を広げます。最初から10言語を同時に走らせると、用語の揺れやfrontmatterの抜けを見つけにくくなります。小さく始めて、良いhandoff receiptの形を先に固めるほうが、長期的には速いです。

Masaの失敗談として、以前は「全ロケールを並列で改善」とだけ頼み、各agentが別々にタイトルを変えたことがあります。本文は良くなったのに、検索キーワード、内部リンク、CTAの言い方が揃わず、最後の統合で余計な確認が増えました。並列化するほど、最初の命名と禁止事項は地味に効きます。

そのため、私は今では作業前に「誰が決めるか」「誰が編集するか」「誰が疑って読むか」を必ず分けて書きます。 この一文があるだけで、agent同士の責任境界がかなり明確になります。 この順序が安全です。

最後に、成功したpromptをチームのCLAUDE.mdや.claude/agents/へ移します。ただし、何でも永続化すると別の重さになります。毎回使う委譲契約、禁止事項、レビュー観点だけを残し、特定の記事だけに必要な背景情報はpromptに書きます。共通ルールと一回限りの事情を分けることが、サブエージェント運用を保守しやすくする近道です。

コピペで作るレビュワーサブエージェント

上の考え方をすぐ試すなら、まず読み取り専用のレビュワーから始めるのが安全です。次のスクリプトは .claude/agents/article-reviewer.md を作ります。編集権限を持たせず、公開前の差分を批判的に読む役割だけに絞るのがポイントです。

mkdir -p .claude/agents
cat > .claude/agents/article-reviewer.md <<'EOF'
---
name: article-reviewer
description: Reviews ClaudeCodeLab articles for originality, implementation detail, SEO, and publication risk.
tools: Read, Grep, Glob
---

Review the assigned files only. Do not edit.

Checklist:
- title and description match the search intent
- intro gives a concrete reader problem in the first three lines
- examples, pitfalls, official links, internal links, and CTA are present
- code fences are balanced and labeled
- the article is not a thin summary or duplicated from another page

Return:
- findings by severity
- pass/fail recommendation
- one highest-leverage fix
EOF

公開前チェックリスト

最後に、記事とコードの両方で使えるチェックリストです。

# Subagent Delegation Checklist

## Before delegation
- [ ] Goal is one sentence.
- [ ] In-scope files are listed explicitly.
- [ ] Out-of-scope files and actions are listed explicitly.
- [ ] Explorer runs before worker when scope is unclear.
- [ ] Write sets do not overlap.

## During work
- [ ] Each worker edits only allowed files.
- [ ] Large outputs are summarized.
- [ ] Any need to expand scope is reported before editing.
- [ ] Prompts include done conditions.

## Review
- [ ] Reviewer runs in read-only mode.
- [ ] Metadata and links are checked.
- [ ] Code fences and commands are checked.
- [ ] Localization is full, not summarized.
- [ ] Remaining risks are written in the handoff.

この記事の内容を実際に試した結果

MasaがClaudeCodeLabの記事改善で一番効果を感じたのは、翻訳を並列化することよりも、最初に「日本語canonical」「翻訳worker」「読み取り専用reviewer」を分けることでした。以前は、10言語を一気に直そうとして、英語だけ濃く、日本語と他言語が薄いまま残ることがありました。今は、canonicalの実例と失敗談を先に固め、各ロケールでは要約禁止とCTA維持を明示することで、公開前レビューの指摘がかなり具体的になりました。

Claude Codeをチームに入れるなら、サブエージェントは派手な自動化機能としてではなく、作業設計の型として教えるのが近道です。ClaudeCodeLabでは、研修・コンサルティング・実務テンプレート集で、この記事のような委譲契約、レビュー観点、コンテキスト管理をチーム向けに整理しています。導入前に自社の作業分解を見直したい場合は、Claude Code研修の内容も参考にしてください。