Claude Code のサブエージェントを3つに分けて開発を回す設定手順

TL;DR

• 個人開発で Claude Code 1エージェント運用が限界 → 3つに分割
• architect（設計） / implementer（実装・テスト） / reviewer（レビュワー） の役割分担
• 設定ファイル(~/.claude/agents/<name>.md)のサンプル付き
• ハマりポイント: ファイル直書きは session restart 必須

なぜ分けるか(短く)

1人で全部やらせると、特にレビューが甘くなる。
自分の書いたコードを自分でレビューする構造だと、思い込みが外せないんですよね。

後は実装中、要件の変更がちゃんと記録されてたりされてなかったり、どこまでプロジェクトが進行したかも別セッションでわからなくなったり。。。

ベスプラはもっと細分化(テスター・マーケ・UX等)だけど、個人開発で4プロダクト並行（渡しの場合）という前提で、最低限3つに絞りました。

詳しい判断ロジックは Zennの記事 に書きました。
この記事は 設定手順 に絞って書きます。

ファイル配置

3つのファイルを ~/.claude/agents/ に置く。

~/.claude/agents/
├── architect.md
├── implementer.md
└── reviewer.md

WSL の場合は /home/<user>/.claude/agents/。
Windows と WSL は別の ~/.claude/ を持つので、使う環境側に置く必要があります。

各エージェントのフロントマター例

architect.md(要件定義)

---
name: architect
description: 新規プロダクトの要件定義を進める。市場調査・機能洗い出し・受け入れシナリオ・技術選定・スケジュール作成まで担当。"要件定義" "新しいプロダクト" "技術選定" などで呼ぶ。実装はしない。
tools: WebSearch, WebFetch, Read, Write, Edit, Glob, Grep, Bash
model: opus
---

(システムプロンプト本文: 役割・進め方・成果物の定義)

implementer.md(実装兼テスター)

---
name: implementer
description: spec.md の受け入れシナリオを満たすコードとテストを書く。schedule.md を毎セッション更新。"実装" "次のタスク進めて" などで呼ぶ。
tools: Read, Edit, Write, Bash, Grep, Glob
model: sonnet
---

(システムプロンプト本文)

reviewer.md(独立レビュー)

---
name: reviewer
description: 直近のコミット差分を独立した目線でレビュー。バグ・セキュリティ・受け入れシナリオ網羅・スケジュール更新を確認。"レビューして" "コードチェック" などで呼ぶ。
tools: Read, Grep, Glob, Bash
model: sonnet
---

(システムプロンプト本文)

description の書き方のコツ

description がトリガーフレーズなので、自然な呼び出し方を複数列挙する。
これがないと auto-delegation が効かず、毎回明示的に呼ぶ羽目になる。

良い例:

description: 直近のコミットや差分を独立した目線でレビューする。バグ・セキュリティ・テスト不足・命名・無駄な抽象化を指摘。実装直後・PR前・"レビューして" "コードチェック" "見直して" と言われたとき呼ぶ。

悪い例:

description: コードレビュー

→ 短すぎて Claude が呼びどころを判断できない。

落とし穴: session restart

ここで30分くらい溶かしたポイント。

ファイル直書きで作ると、その場では /agents に表示されません。

公式ドキュメントによれば:

Subagents are loaded at session start. If you add or edit a subagent file directly on disk, restart your session to load it.

つまり:

• ✅ /agents UI で作成 → 即時反映
• ❌ ファイル直書き → セッション再起動が必要

動作確認

# CLI で確認(セッション外でもOK)
claude agents

出力にこう出ればOK:

8 active agents

Built-in agents:
  claude-code-guide · haiku
  Explore · haiku
  general-purpose · inherit
  Plan · inherit
  statusline-setup · sonnet

User agents:
  architect · opus
  implementer · sonnet
  reviewer · sonnet

5 active agents のままなら、フォルダの場所か restart 忘れを疑う。

呼び出し方

サブエージェントは スラッシュコマンドでは呼べません(Skill とは違う)。
自然言語で呼び出すか、/agents UI から手動指定。

"reviewer 見て"
"architect 呼んで、新機能の仕様を詰めたい"
"implementer に続き進めてもらって"

description のフレーズが含まれていれば、Claude が auto-delegation で渡してくれます。

まとめ

• ~/.claude/agents/ に <name>.md 直書きで3つ配置
• 各ファイルのフロントマター必須項目: name description
• description には呼び出しフレーズを複数入れる
• 直書きしたら 必ず session restart
• WSL 使う人は環境分離注意(Windows と WSL は別ホーム)
• 動作確認は claude agents (CLI) が早い

---