TL;DR
- Claude Code上に役割の異なるサブエージェントを11体作り、個人開発の全業務（設計・実装・検証・リリース・非コードのレビュー）を役割分担している。
- 効果を出しているのは凝ったプロンプトではなく、「症状→誤った直感→正しい打ち手」の形式で失敗を記録し、次の委任プロンプトに機械的に混ぜ込む仕組み（
team-lessons）だった。 - この記事は設定ファイルとコードの実物を貼る。ただしプロジェクト固有名と内部チーム名の一部は伏せている（伏せた箇所はその都度書く）。
このAIチーム構築それ自体をプロダクトとして売っているわけではない（収益0円）。ここに書いた運用は、自分の個人開発（Webツール群・note・LINEスタンプなど）を毎日回すための実務フローとして使い続けているものを、そのまま公開している。
構成: ccteams というOSSの上に乗せている
土台は ccteams（MITライセンス）という、Claude Code用にあらかじめ役割分担されたサブエージェント一式をワンコマンドでプロジェクトに適用するツール。.claude/ 配下にチーム定義一式が展開され、プロジェクトのルート CLAUDE.md から読み込まれる。
ディレクトリ構成（実物・一部省略）:
.claude/
├── active-team.md # 起動のたびに読まれるチーム運用ルール
├── agents/ # サブエージェント定義（1体=1ファイル）
│ ├── scope-planner.md
│ ├── architect.md
│ ├── builder.md
│ ├── qa-reviewer.md
│ ├── shipper.md
│ ├── reviewer.md
│ └── ...(残り5体は第三者向け資料の批評専任チーム。スコープが違うので別記事で扱う)
├── skills/
│ ├── working-method/SKILL.md
│ ├── generalist-playbook/SKILL.md
│ └── team-lessons/SKILL.md
└── check-in.sh # SessionStartフックで毎回実行
サブエージェント6体を実物で
.claude/agents/*.md の frontmatter に name / description / tools / model を書くだけで1体になる。実際の6体の frontmatter（description と model のみ抜粋）:
| エージェント | 役割 | model |
|---|---|---|
scope-planner |
曖昧な依頼を「1文のゴール」「完成条件」「最小スコープ」「明示的な先送り」に変換する。コードは書かない | opus |
architect |
データモデル・API・技術選定などの設計判断だけを担当。実装はしない | opus |
builder |
実装担当。既存の書き方・命名・テストの流儀を検出してから合わせて書く | sonnet |
qa-reviewer |
実装完了後の検証。プロジェクト自身のtest/lintコマンドを実際に走らせ file:line — 問題 — 直し方 で報告。実装はしない |
opus |
shipper |
コミット整理とリリースノート。git push・タグ付け・ブランチ削除はせず、実行コマンドを報告して人間の確認を待つ |
sonnet |
reviewer |
批判専任。公開・削除・自動化・課金・個人情報が絡む変更の前に必ず通す | sonnet |
設計判断・実装・検証を別モデル・別コンテキストの役に分けているのがポイントで、architect/qa-reviewer のような「判断の質」が効くところにはopus、builder/shipper のような「量をこなす」ところにはsonnetを割り当てている。
ルーティングは全部ファイルに書く（口頭で毎回言わない）
.claude/active-team.md に、誰にいつ投げるかのルールとフローを書いている。以下は実物からの抜粋で、各項目の後半（判断基準の詳細）は長いので落としている。
## Orchestration rules
- **New or vague work** — start with **scope-planner**: one-sentence goal, done-means
criteria, minimal shippable scope, explicit deferrals. Skip if the task is already
well-defined.
- **Non-trivial design decisions** — delegate to **architect** after scoping.
- **Implementation** — delegate to **builder**. It detects the stack and matches existing
conventions; do not pre-select a language or framework for it.
- **Before anything is "done"** — **qa-reviewer** must verify: run the project's tests,
lint, and typecheck; report findings as `file:line — problem — concrete fix`.
- **Committing and releasing** — delegate to **shipper**: it never pushes, tags, or
deletes branches itself — it reports the exact command; get the user's confirmation.
## Flow (adapt as needed)
scope-planner → architect → builder → qa-reviewer → shipper
トリビアルな作業（1ファイル・パターン明確）はscope-planner/architectを飛ばしてよい、という例外条件もここに明記してある。
委任プロンプトには毎回同じdigestを埋め込む
全エージェントへの委任プロンプトの先頭に、次のdigestを機械的にコピーする運用にしている（active-team.md より実物）。
Working method (non-negotiable):
1. Restate the goal in one sentence + a "done means" criterion before acting.
2. Read the actual files before forming opinions; verify every path/function you reference exists in this project.
3. Name your riskiest assumption and check it first, while it is cheap.
4. The diff is a claim; execution is evidence. Run the project's build/lint/tests and report their real output.
5. Label claims VERIFIED (ran it) / REASONED (read it) / ASSUMED (unchecked) — never upgrade one silently.
6. Before finishing: re-read the original request; every requirement met, nothing promised-but-undone.
「診断や作業を丸投げしない」「合っているかを実行して確かめる」「確認済みと未確認を混ぜない」を、依頼文の型として毎回強制している。この記事自体もこの手順に沿って書いた。
一番効いているのは team-lessons（失敗のカタログ）
.claude/skills/team-lessons/SKILL.md に「症状→誤った直感→正しい打ち手」の形式で失敗事例を溜めていて、委任のたびに関連エントリを引用して渡す。実際に自分が書いたエントリを2つ引用する（プロジェクト固有名と一部の数値は伏せた）。
### 「もう解決済み」と裏取りせず並行タスクを丸ごと動かしかけた
- **Symptom** (2026-07-23): 継続メモが「対応中」と書いていたのを鵜呑みにして
builder/architectを割り当てそうになった。scope-plannerに実ファイル・git logを
読ませたところ、該当バグは既に修正済み・実装済みとVERIFIED(node --test全緑＋
実ブラウザ検証)。
- **Wrong instinct**: 継続メモ・ステータスボードの記述を、最新の実ファイル状態
より優先して信じ、着手前提でエージェントを割り当てる。
- **Correct move**: 一括割り振りの前に「本当にまだ未完了か」を実ファイル・
テスト・git logで裏取りさせてから配車する。もう終わっていたら候補から外す。
### 外部プラットフォーム向け成果物の仕様をプロジェクト内文書だけで判定した
- **Symptom** (2026-07-08): 画像18枚をプロジェクト内の仕様書どおりに規格化し
全PASS報告 → 実際の提出先の公式仕様（縦横とも偶数px必須）を満たしておらず、
QAで12枚が入稿リジェクト対象と判明。
- **Wrong instinct**: プロジェクト内の仕様書に書かれた条件を満たせば出荷可能と
みなす。
- **Correct move**: 提出先が外部プラットフォームの成果物は、プロジェクト内文書を
仕様の要約にすぎないと想定し、公式入稿仕様を検証項目に明示する。
同じ失敗を別のエージェント（別コンテキスト）が再現するのを防ぐのが目的。効果が出た具体例として、CLIツール(Codex)のサンドボックス設定を1つ付け忘れ、取得済みの調査結果がまるごと消えた失敗もここに書き足した。以後、書き込みが要るCodexの依頼には必ずサンドボックスを書き込み可能モードにするオプションを付けるルールにした。1回ファイルに書いたことで、同じ依頼文をコピーするだけで次回から再発しなくなる。
SessionStartフックで「資産の存在」を毎回思い出させる
サブエージェントやスキルを増やしていくと「作ったのに存在を忘れて使わない」問題が起きる。これへの対処として、セッション開始時に自動実行されるシェルスクリプト(.claude/check-in.sh)を書いた。実物から引用する（内部チーム名を含む1行だけ伏せた）。
#!/usr/bin/env bash
# セッション開始時に「使える資産」と「稼働状況」をClaudeのコンテキストへ流し込む。
# 目的: 構成した資産を毎回思い出させ、使い漏れをなくす。本人が毎回口頭で言わなくて済むようにする。
echo "【毎回守ること（守れているか自分で確認する）】"
echo " 1. 非コードの重要成果物は公開前に reviewer を通す"
echo " 2. コード変更は qa-reviewer の検証を経るまで「完了」と言わない"
echo " 3. 委任プロンプトには working-method の digest と generalist-playbook 読了指示を必ず入れる"
echo " 4. Google Workspace 操作は gws-*/recipe-* を先に探す（自作しない）"
echo " 5. 機械処理・一括処理は ollama / codex に回す（自分のトークンを使わない）"
echo " 6. 知見は必ず外部保管（memory / team-lessons / 正本md）"
echo " 7. 成果物は自分の目で開いて確認してから報告する"
echo " 8. 区切りで /clear を提案する"
このスクリプトは .claude/agents/*.md を実際に for ループで走査してサブエージェント一覧を組み立てるので、エージェントを増減させてもドキュメントの更新漏れが起きない。
自分の環境で再現する手順
-
ccteams（MIT）を導入するか、.claude/agents/*.mdを手書きする。最低限name/description/tools/modelの4項目があれば1体になる。 -
.claude/active-team.mdに「どの依頼をどのエージェントに渡すか」のルールとフロー図を書く。ここが空だと毎回口頭指示が必要になる。 -
.claude/skills/team-lessons/SKILL.mdを作り、失敗が起きるたびに「症状→誤った直感→正しい打ち手」の3行を足す。委任プロンプトの末尾に関連エントリを引用する運用をセットで作る。 - SessionStart hookに
check-in.sh相当のスクリプトを登録し、資産一覧を毎回コンテキストへ流し込む。 - 非コードの成果物は
qa-reviewerとは別の批判役（reviewer）を必ず通す。公開前レビューをコードと同じ扱いにする。
ここに書いた手順自体はコピペで再現できる。実際に時間がかかるのは設定ファイルを書くことではなく、team-lessons に何を書くかを見極めるまでの試行錯誤——つまり自分のプロジェクト固有の失敗を何十件も踏んで拾い上げる工程のほうだ。
まとめ
サブエージェントを増やすこと自体は簡単だが、効果が出るのは「プロンプトが賢いから」ではなく、「失敗を1回ごとに記録し、次の依頼文に機械的に混ぜ込んでいるから」だった。11体という数はおまけで、本体は team-lessons という失敗ログの運用にある。
なお、他人のプロジェクトに同じ仕組みを入れる代行もやっている。最初から動く状態で渡せる分だけ、上に書いた試行錯誤の工程を圧縮できる、というのが売っているものの中身です。相談は info@clartools.com まで。要件が固まっていなくても構いません。
この記事は Zenn にも投稿しています: https://zenn.dev/clar/articles/2fc619714ec7f1