Claude Codeのエージェントチーム設計 — 3プロジェクトをリリースして見えた設計指針

はじめに

Claude Code のサブエージェントは、1 ファイル書けば追加できます。組織設計よりはるかに低コストに「役割分担」の実験ができるのがこの仕組みの面白さです。

ただし、低コストで追加できるからこそ、「どういう基準で分けるべきか」 の判断は現場に委ねられていて、教科書的な答えがありません。

私は個人開発で 3 つの Web サービスを運営しており、それぞれに別々のエージェントチームを組んでいます。

• FolioInk（サブスク記事投稿PF）— 13 名体制

• エペナビ（APEXツール）— 10 名体制

• jir0.com（個人HP）— 5 名体制

3 プロジェクトを実際にデプロイして運用したことで、「プロジェクトごとに最適なエージェント構成は違う」 というのがはっきり見えてきました。同時に、プロジェクトをまたいで共通する設計原則 もいくつか抽出できました。

この記事は、その設計指針の整理です。「何人で組むべきか」「どう分けるべきか」「誰が誰を呼ぶか」を、失敗経験とセットで書きます。

想定読者:

• Claude Code のサブエージェントを使い始めたが、何人まで分けるべきか悩んでいる方

• 複数プロジェクトを並行運用していて、チーム構成を使い分けたい方

• Cursor・Cline 等の他 AI コーディングツールで似た構成を検討している方

3プロジェクトの実例

まず、3 プロジェクトの構成を並べます。数字だけ見てもピンと来ないので、扱っているリスクの種類 とセットで整理します。

エージェント数はプロジェクトの複雑さ、というより「扱うリスクの種類の数」に比例 します。

• jir0.com は静的な情報発信なので、決済・認証・ユーザー投稿リスクがない。5 名で足りる

• エペナビは外部 API（apexlegendsapi.com）と連動し、APEX のパッチ更新を追従する必要がある。Patch Monitor・Measurement Engineer という専用エージェントが必要になる

• FolioInk は決済・UGC・サブスクが絡むので、Stripe 専門の Payment と、利用規約を扱う Legal と、ドキュメント整備の Docs が必要

「とりあえず 13 名」とコピペしても、jir0.com では 8 名が暇になります。逆に jir0.com の 5 名を FolioInk に適用したら、Stripe 周りで事故る確率が跳ね上がります。

チーム構成はプロジェクトのリスク構造を映す鏡 であるべきです。

設計指針1：汎用Claudeにマネージャー役を明示する

これが 3 プロジェクトで最も効いた設計変更でした。

最初に依頼を受けるのはサブエージェントではない

Claude Code でユーザーが「〇〇を実装して」と依頼したとき、最初に依頼を受けるのは汎用 Claude 本体 です。サブエージェントはあくまで、本体が Task ツールで呼び出す先に過ぎません。

当初、私はここを曖昧にしていました。FolioInk のエージェントチームには「PM」がいるので、PM が窓口だろうと勝手に思い込んでいたのです。

でも実運用では、

1. ユーザーが汎用 Claude に依頼する

2. 汎用 Claude が「PM に振るべきか、Frontend に直接振るべきか、自分で対応すべきか」を判断する

3. 判断に応じて Task ツールでサブエージェントを呼ぶ

という流れになります。汎用 Claude が実質的なマネージャー役 を担っています。

ところが、この役割を CLAUDE.md に明示していなかったため、汎用 Claude が自分の裁量で Frontend のコードを直接書き始めてしまう、PM を呼ばずに仕様判断を勝手に下す、という事故が何度も起きました。

ルート CLAUDE.md で明示してから激変した

そこで、プロジェクトルート の CLAUDE.md に以下を書きました。

## あなたの役割: マネージャー

あなた（Claude）はマネージャーとして、ユーザーの依頼を受けて以下を行う：

1. 依頼内容を分析し、どのエージェントが適任かを判断する
2. 複数の視点が有効な場合は並行で依頼する
3. 各エージェントの回答を統合し、矛盾があれば整理してユーザーに提示する
4. 単純な質問や作業指示の場合は、エージェントを介さず直接対応する

この 4 行を書いた途端、汎用 Claude は 「自分はマネージャーであり、実装者ではない」 と理解するようになりました。勝手にコードを書くことは激減し、適切なサブエージェントに委任するようになりました。

プロジェクト CLAUDE.md にも明示すべきだった（反省）

FolioInk と エペナビ の CLAUDE.md には、この「マネージャー役」の宣言を書き忘れていました。

結果として、ユーザーから依頼が来ると汎用 Claude が「PM を通すべきか、直接 Frontend を呼ぶべきか」と迷い、時として PM を飛ばして直接 Frontend に実装を依頼してしまう、ということが起きていました。PM が設計しているはずの仕様判断を、汎用 Claude が勝手に下していたわけです。

反省: エージェントチームを持つプロジェクトの CLAUDE.md には、必ず冒頭で「汎用 Claude の役割」を宣言する べきです。これは 3 プロジェクト横断で最も効く指針でした。

設計指針2：責務分離の3つの判断軸

何人で組むかの前に、「どう分けるか」の基準が必要です。3 プロジェクトの試行錯誤から、以下の 3 軸で判断しています。

軸1：必要な知識ドメインが違うなら分ける

FolioInk で Payment を Backend から切り出した判断がこれです。

• Backend：一般的な API 設計、認証、Zod、Prisma

• Payment：Stripe Connect の 3-party flow、Webhook 冪等性、手数料計算、カード情報を扱わない設計

Stripe だけで要件が多すぎるので、汎用 Backend に混ぜると Backend の品質が下がります。「このエージェントに混ぜると他の責務が劣化する」と感じたら分けどき です。

エペナビの Patch Monitor も同じ発想で切り出しました。APEX のパッチ更新を追従するのは、Frontend にも Data Engineer にも混ぜたくない、独立した責務です。

軸2：判断基準が違うなら分ける

Tech Lead と Reviewer は、どちらも「コードを見る」役割ですが、判断基準が違います。

• Tech Lead：規約を 定める 側。「この設計パターンを採用するか」を議論する

• Reviewer：規約に 準拠しているか を確認する側。OWASP Top 10・N+1・any 禁止など、既定のチェックリストに照らす

ルールを作る人と、ルールで裁く人は別人 であるべきです。FolioInk で初期は統合していましたが、セルフレビューのバイアスで Critical が素通りしたため分割しました。

軸3：呼び出しタイミングが違うなら分ける

FolioInk の Legal・Docs・Growth は、どれもリリース後の世界に関わります。でも呼び出しタイミングが違います。

• Legal：MVP 着手時と、利用規約変更の節目

• Docs：機能が完成した直後に、ヘルプを書くタイミング

• Growth：機能がリリースされた後の、KPI 分析タイミング

呼び出しタイミングが違うエージェントを統合すると、「今は何をすべきか」が曖昧になります。分けておけば、トリガーと担当者が 1:1 で対応 します。

設計指針3：エスカレーション順序を固定する

エージェントを分けただけでは、ただのサイロです。誰が誰を呼ぶか のフローを CLAUDE.md で決めておく必要があります。

FolioInk のエスカレーションはこうなっています。

ユーザー
  ↓
汎用Claude（マネージャー役）
  ↓
  ├─ 仕様判断が要る → PM（必要なら Market Analyst / Tech Lead を並行招集）
  ├─ 設計から必要 → Architect
  └─ 実装着手 → Frontend / Backend / Payment
                  ↓
                  QA（テスト作成・実行）
                  ↓
                  Reviewer（セキュリティ・品質レビュー）
                  ↓
                  DevOps（Vercelデプロイ）

この順序のうち、実装 → QA → Reviewer → DevOps はスキップ不可 と CLAUDE.md に明記しています。

書いていなかった時期は、実装エージェントが「完了しました」と報告した瞬間、汎用 Claude が DevOps を呼んでデプロイし始めるという事故がありました。「QA と Reviewer を通さずデプロイしない」を明示するだけで、事実上の品質ゲートになります。

jir0.com では実装エージェントが 1 人（Frontend）しかおらず、決済もないので、エスカレーション順序はもっとシンプルです。プロジェクトのリスクに応じてゲートの厳しさを調整する のもこの指針の一部です。

設計指針4：横串の運用エージェントはフェーズゲートで呼ぶ

Legal・Docs・Growth のような 機能には紐づかないが常に必要な観点 を持つエージェントは、実装フローに組み込むとスピードが落ちます。

毎回の実装で「Legal レビューは？」「Docs は書いた？」のチェックが走ると、MVP 開発のリズムが壊れます。

代わりに、フェーズの区切り（Month 1 完了時・Month 2 完了時・リリース直前） でまとめて呼び出します。PM（または汎用Claude）が「このフェーズの成果物を Legal / Docs / Growth にまとめて見せて」と指示する形です。

並行起動のサンプルがこれです。

リリース後に：
Growth と Docs と Legal に並行で、
今回のリリースに関する担当タスクを依頼する

Growth は GA4 イベント追加、Docs はヘルプ追記、Legal は利用規約への影響確認。3 名は互いに何も見なくていい ので、並行しても衝突しません。15 分で 3 名の成果物を一気に回収できます。

常時稼働ではなく、フェーズゲートで呼び出す専門家 という位置付けにすることで、本線のスピードを維持しながら抜け漏れを防げます。

3プロジェクトで実際に踏んだ失敗

失敗1：Tech Lead と Reviewer を同一にしていた（FolioInk）

初期は「レビューできる人は 1 人で十分」と思っていました。結果、Tech Lead が自分で書いたコードを Tech Lead として自分でレビューし、セルフレビューのバイアスで Critical が素通りしました。

分けてから、Critical の検出率が体感 2 倍になりました。

失敗2：Backend と Payment を統合しようとした（FolioInk）

「どちらも API を書くから、Backend に統合すれば 12 名で済むのでは」と一度考えました。統合してみたら Backend の実装品質が落ちました。

Stripe API の叩き方を気にしすぎて、記事 CRUD のような 一般的な API の実装品質が劣化 したのです。責務を詰め込むと、責務の中心に引きずられて周辺が雑になります。

失敗3：マネージャー役を宣言していなかった（FolioInk / エペナビ）

前述の通り、各プロジェクトの CLAUDE.md では書いていませんでした。結果、汎用 Claude が PM を飛ばして Frontend に直接実装依頼したり、自分でコードを書いたりする事故が起きました。

この学びが、3 プロジェクトでの運用経験から得た最大のものです。

失敗4：Docs を後から足した（FolioInk）

Docs エージェントは、MVP が動き始めてから慌てて作りました。結果、ヘルプページのトーンが既存の他ドキュメント（README・API リファレンス）と揃わず、後からトーン統一の作業コストが発生しました。

リリース後に必要になる役割も、MVP 着手時点でエージェントを仮置きしておく 方が、長期的に楽です。空のエージェント定義でも、存在するだけでトーン設計の意識が違います。

失敗5：jir0.com に QA を置かなかった

jir0.com は静的 LP だから QA 不要と判断しましたが、リンク切れ・OGP 画像切れ・構造化データの誤り のような LP 特有の QA 観点を誰も持たないまま運用されました。

今振り返ると、Frontend のチェックリストに LP QA 観点を入れるか、軽量な QA エージェントを置くべきでした。エージェントを置かない判断をするときは、「その責務を誰が持つのか」を明示 する必要があります。

プロジェクト立ち上げ時のチェックリスト

3 プロジェクトの経験から、新規プロジェクト開始時に必ず決めるべき項目を整理しました。

Step 1. マネージャー役の宣言（必須）

CLAUDE.md の冒頭に、汎用 Claude の役割 を宣言する。何を判断し、何をサブエージェントに委任するかを書く。これを書かないと汎用 Claude が暴走します。

Step 2. 扱うリスクの列挙

決済・認証・UGC・外部API・個人情報・法務リスク のうち、プロジェクトが扱うものを列挙する。列挙されたリスクの数に応じて、専門エージェントの要否が決まる。

Step 3. 最小エージェントセットの決定

全プロジェクトに共通で最低限必要な構成がこれです。

• PM（仕様判断・スコープ管理）

• Frontend（UI実装）

• Reviewer（品質・セキュリティ確認）

これに、Step 2 で列挙したリスクに応じて専門エージェントを足していきます。

Step 4. エスカレーション順序の固定

「実装 → QA → Reviewer → デプロイ」の順序を CLAUDE.md に書く。スキップ不可であることも明記する。

Step 5. 横串運用エージェントのフェーズ配置

Legal・Docs・Growth のような横串エージェントは、どのフェーズゲートで呼ぶかをあらかじめ決める。

エージェント数の正解は、プロダクトが決める

「13 名が最適」でも「5 名で十分」でもなく、プロジェクトが抱えるリスク構造がエージェント数を決定する というのが 3 プロジェクトをリリースして得た最大の結論です。

• 静的LP（jir0.com）：PM / Designer / Frontend / Reviewer / Growth の 5 名で完結

• 外部API依存ツール（エペナビ）：Patch Monitor・Measurement Engineer のような 領域固有の専門エージェント が必要

• 決済・サブスク（FolioInk）：Payment・Architect・Tech Lead・Legal・Docs の リスク管理エージェント が必要

Claude Code のサブエージェントは、組織設計よりはるかに低コストで再編できます。最初から完璧を狙う必要はなく、痛みを感じた箇所から切り出していく のが現実的です。

まとめ — 5つの設計指針

3 プロジェクトのリリース経験から抽出した設計指針を、再掲します。

1. 汎用 Claude にマネージャー役を明示する — 最初に依頼を受けるのはサブエージェントではなく汎用 Claude 本体。CLAUDE.md 冒頭で役割を宣言する

2. 責務分離は 3 軸で判断する — 知識ドメイン／判断基準／呼び出しタイミングのどれかが違うなら分ける

3. エスカレーション順序を固定する — 特に「実装 → QA → Reviewer → デプロイ」はスキップ不可にする

4. 横串の運用エージェントはフェーズゲートで呼ぶ — 毎回呼ぶとスピードが落ちる。区切りでまとめて並行起動する

5. エージェント数はプロジェクトのリスク構造に比例する — テンプレをコピペせず、扱うリスクを数え上げてから決める

Claude Code を使う中で、モデル単体の性能よりも、役割分担の設計の方が生産性に効く と強く感じるようになりました。同じ Sonnet でも、「何でもやれ」と言われるより「Payment のことだけ考えろ」と言われた方が、明らかに鋭い判断をします。

役割設計は、ソロ開発で AI と組むなら最も回収率の高い投資のひとつだと思います。

関連リンク

• Claude Code 公式ドキュメント — Sub agents

• Claude Code 公式ドキュメント — CLAUDE.md

• 前回の記事：個人開発のCLAUDE.md設計パターン — AIに「指示書」を書く技術（FolioInk 内で公開）