はじめに

こんにちは。主にXでAI駆動開発を発信している熊井悠です！
AIスタートアップでCEO兼CTOをしています。

僕の会社では、約10人月の受託開発が2週間で、自社プロダクトは「開発〜リリース」が5日で終わるようになりました。支えているのは、Claude Codeで組んだ「並列ループエージェント」 です。概要は下記のスライドに書いてありますので合わせてご覧ください。

さて、この記事は紹介ではなく、空のディレクトリから並列ループエージェントを自分の手で組み上げるハンズオン です。STEP 0から進めれば、最後には「自走してコストも軽い開発エージェント」が手元に残ります。

この記事について

Claude Codeのスキル × サブエージェントで、開発を並列 × ループ × TDDで自走させる仕組みをゼロから作ります
技術スタックは非依存です。筆者はReact/Next.jsが多いですが他の言語でも使えるように考えております
情報を正確性に注意して記載しましたが、何か想定と異なる点があればコメントをぜひお願いします

元ネタは、AnthropicのNicholas Carlini氏による「並列ClaudeチームでCコンパイラを構築した実験」。16体のエージェントを並列で走らせ、約2,000セッション・2週間で、ほぼ自律的に10万行規模のCコンパイラ（Linux 6.9をx86/ARMで動かす）を書き上げました。

ただしこの実験は、各エージェントをDockerで隔離する大がかりな構成で、オーケストレーションも使わないプロトタイプです。

この記事ではそれをコピーするのではなく、そこで得られた4つの教訓を、Docker不要・1セッション内のサブエージェントで再現します。

無限ループで止めない
テスト駆動で「完了」を定義する
並列化する
出力を最小化してコンテキストを守る

まずClaude Codeの4つの役割を頭に入れる

2026年のClaude Codeには拡張ポイントが複数あります。混同すると設計が崩れるので、最初に4つを分けます。

拡張ポイント	役割	いつコンテキストに載るか	使いどころ
CLAUDE.md	規約・ルールの定義	毎回（起動時に必ず）	フローの骨格と停止ポイント
スキル（Skill）	やり方・手順（知識）	必要なときだけ（動的ロード）	テンプレ・スクリプトを同梱
サブエージェント	実行（並列・隔離）	親エージェントには載らない（独自コンテキスト）	重い作業の肩代わり
スラッシュコマンド	明示トリガー	呼んだときだけ	必ず通したい関所

効いてくるのは右2列です。毎回コンテキストに載るのはCLAUDE.mdだけで、あとは必要なときだけ載る。

ここがコスト設計の肝です。毎回まるごと載るCLAUDE.mdやプロンプトは、増えるほど"コンテキスト課金"が膨らむ。中程度のCLAUDE.mdでも数百〜千トークン、テンプレを足せばコードを読む前に数千トークンが消えます。1日に何十タスクも自走させれば、無視できません。

なので方針はシンプルです。手順とテンプレはスキルに置き、CLAUDE.mdは案内役に徹させる。 これが「出力を最小化する」という柱になります。

完成イメージ

作り終わるとこうなります。

my-project/
├── CLAUDE.md                       # 案内役（骨格＋停止ポイント＋スキル呼び出し）
├── SPEC.md                         # 走らせると feature-spec が生成
├── .claude/
│   ├── agents/                     # サブエージェント（実行レイヤー：モデル割り当て）
│   │   ├── implementer.md
│   │   └── reviewer.md
│   └── skills/                     # スキル（知識レイヤー：必要時ロード）
│       ├── feature-spec/SKILL.md   # 仕様書生成（テンプレ同梱）
│       ├── structured-review/SKILL.md  # 構造化レビュー（ユーザー起動）
│       └── e2e-runner/             # E2E（スクリプト同梱）
│           ├── SKILL.md
│           └── screenshot.sh
└── tests/                          # テスト規約・ハーネス置き場（実テストは実装に同居）

動かすときは claude を起動するだけ。親エージェントがCLAUDE.mdを読み、タスクを分解し、サブエージェントを並列で走らせ、必要なフェーズでスキルをロードし、結果を統合します。並列が効くのは調査・実装・検証の3面です。

  Parent Agent (Claude Code)
  └ CLAUDE.md（案内役）＋ 必要なときだけ Skill をロード

  Phase 1 調査       〈並列・読む〉   Explore
       │
       ▼
  Phase 2 仕様書                    並列グループを宣言
       │
       ▼
  ◆ 停止①  仕様を人間が承認
       │
       ▼
  Phase 3 実装       〈並列・書く〉   implementer
       │
       ▼
  Phase 4 統合ゲート  〈逐次・1人〉    全テスト＋lint 緑
       │
       ▼
  Phase 5 検証       〈並列・読む〉   reviewer
       │
       ▼
  ◆ 停止②  /structured-review で人間が判断

なぜ「並列ループ」なのか

Claude Codeを使い始めると、必ずこの壁にぶつかります。

頼む → 半分やって止まる → 「続けて」 → また止まる → ……

3時間後、「続けて」を40回打っている自分に気づく。これを解決するのが4つの仕組みです。

仕様駆動：実装の前に「何を作るか」を仕様書で確定させる
並列：独立した作業を同時に走らせる（調査・実装・検証）
ループ：完了条件を満たすまで自走させる
TDD：「完了」を機械が判定できる状態を作る

土台となるのは1です。仕様なしで並列に走らせると、各エージェントが勝手な解釈で実装を始め、統合時に矛盾が噴出する。仕様書が全エージェント共通の「正」になるため、並列が成立します。

特に「どのセットが互いに独立か（＝同時に書いても衝突しないか）」を仕様の時点で宣言しておくこと。これが後段の並列実装の前提になります。この4つを、これから作るファイル群に仕込んでいきます。

STEP 0：プロジェクトの骨格を作る

まず骨格を用意します。最初から skills ディレクトリも掘っておきます。

mkdir my-project && cd my-project
mkdir -p .claude/agents .claude/skills tests
touch CLAUDE.md

STEP 1：CLAUDE.md を「案内役」として書く

CLAUDE.mdは起動時に毎回読まれます。なのでここには骨格と停止ポイントだけを書き、手順の詳細はスキルに委ねます。

CLAUDE.md

# Parallel Subagent Framework

## 実施時のカスタマイズ（置き換えること）
- テストコマンド: <テストコマンド>   # 例: bun run test / pytest
- Lintコマンド:   <Lintコマンド>     # 例: bun run lint / ruff check
- UIディレクトリ: src/components/   / データ取得: src/api/  / DB: prisma/schema.prisma

## フロー（骨格）
Phase 1 調査(並列) → Phase 2 仕様書(並列グループ宣言) → [停止① 人間レビュー] → Phase 3 実装(TDD・並列) → Phase 4 統合ゲート → Phase 5 検証(並列) → [停止② 構造化レビュー]

## どのフェーズでどのスキルを呼ぶか
- Phase 2（仕様書）→ skill「feature-spec」を使う
- E2E・スクショが必要なとき（随時・フロー外）→ skill「e2e-runner」を使う
- Phase 5（検証）のあと → ユーザーに /structured-review を促して停止する

## 絶対ルール
- 確認を求めるのは「仕様レビュー（停止①）」と「構造化レビュー（停止②）」の2箇所のみ。
- それ以外は止まらず自律的に進める。
- 停止①：仕様書を提示したら、人間が承認するまで Phase 3（実装）へ進まないこと。
- 停止②：構造化レビューは `/structured-review` で人間が起動するまで勝手に実行しないこと。

コツは2つ。コマンドは <テストコマンド> のようにプレースホルダにして技術スタック非依存にすること。そして停止ポイントは「①仕様レビュー」「②構造化レビュー」の2箇所に固定することです。

STEP 2：Phase 1（調査）をビルトインExploreで並列化する

調査フェーズでは、Claude Codeのビルトインサブエージェント Explore を使います。読み取り専用・デフォルトHaikuなので、高速かつ低コスト。explorer.md を自作する必要はなく、CLAUDE.mdに自然言語で指示を書けば、Claudeが自動でExploreへ委譲します。

CLAUDE.mdに追記します。

CLAUDE.md

## Phase 1: 調査（並列・ビルトインExplore活用）
以下の3つの調査を、それぞれ独立したサブエージェントで**並列に**実行する。

- UIディレクトリを調査。関連コンポーネントのファイルパス・props型・state・主要イベントハンドラを箇条書きで報告。コードは書くな。
- データ取得ディレクトリを調査。APIエンドポイント・型・hookを箇条書きで報告。コードは書くな。
- DB/スキーマを調査。テーブル構造・リレーション・データアクセス層を箇条書きで報告。コードは書くな。

各調査の報告は**箇条書きのみ**。長文の説明は不要。

効いているのは 「コードは書くな、調査だけ」（役割分離） と 「箇条書きで報告」（出力最小化） の2点。冗長な出力で親のコンテキストを埋めないための制約です。

CLAUDE.mdの指示は「お願い」であり「保証」ではない
CLAUDE.mdに書いた指示は自然言語として解釈されます。「並列に実行する」と書いても、Claudeが必ず並列で走らせるかはモデルの判断次第です。
確実に並列実行させたい場合は、シェルスクリプトで claude -p（ヘッドレス実行）を複数プロセス同時に起動するか、/batch コマンドで並列エージェントを展開してください。また、「途中で止まらず最後まで自律的に走り切ってほしい」場合は /goal コマンドで完了条件を設定すると、条件を満たすまでClaudeが自律的に作業を継続します。

claude -p（ヘッドレス／SDK実行）は従量課金になる可能性がある
通常の対話セッションは Pro / Max のサブスク枠で動きますが、claude -p のようなヘッドレス／SDK経由の実行は、環境やプランによってはサブスク枠ではなくAPI従量課金として扱われる場合があります。バッチ的に多数走らせると課金が膨らみ得るので、自動化に組み込む前に自分のプランでの課金区分と、どのキー／認証で動いているかを必ず確認してください。

Exploreのモデルに関する注意
ドキュメント上、ExploreはデフォルトでHaikuを使うとされています。ただし環境やバージョンによってはセッションのモデルを継承するケースが報告されています。また、MCPサーバーやプラグインを多数インストールしている環境ではHaikuのプロンプトサイズ制限を超えてExploreが失敗することがあります。その場合は CLAUDE_CODE_SUBAGENT_MODEL 環境変数でフォールバックモデルを設定してください。

STEP 3：仕様書を「スキル」にする（テンプレ同梱型）

ここが仕様駆動開発の実装です。調査結果を仕様書に固め、人間が承認し、以降の実装・テスト・レビューはすべてこの仕様を基準に動く。仕様書が全エージェント共通の「正」 になるわけです。

テンプレートをCLAUDE.mdに書くと毎回コンテキストに載ってしまうので、スキルにして仕様書を作るフェーズでだけロードさせます。

.claude/skills/feature-spec/SKILL.md

---
name: feature-spec
description: 調査結果から機能仕様書を生成する。新機能の実装フローで仕様を固める段階で使う。
---
仕様書は2部構成で出力する:

## Part 1 — 仕様（★人間がレビューする部分）
- 何ができるようになるか（利用者目線・技術用語なし）
- 画面イメージ / 操作の流れ / 受け入れ条件（チェックリスト）
- スクショ撮影ポイントには 📸 マークを付ける（STEP 7 の e2e-runner と対応させる）

## Part 2 — 実装計画（AI用・レビュー不要）
- 実装セット一覧（依存順）/ 各セットのテスト観点 / 型・データアクセス層の方針
- 並列グループ宣言：各セットが**触るファイル**を書き、互いに別ファイルだけのセットを同じ「波」（同時実装可）にまとめる。共有ファイルを触る結線は波にせず統合ゲートへ。

仕様書は SPEC.md に出力する。
提示時は Part 1 だけ見せ、Part 2 は「技術詳細なのでレビュー不要」と伝える。

2部構成にする理由は2つあります。

承認のハードルを下げる：レビュアーが非エンジニアでも、利用者目線のPart 1だけ読めば承認できる。なお、Part 2も必要な場合は適宜修正してください。
並列実装の前提を仕込む：Part 2の並列グループ宣言で「どのセットがファイル独立で、どれが依存するか」を確定させておく。だから実装フェーズで安全に並列化できる。仕様駆動と並列が地続きなのはここです。

仕様書生成はフロー上必ず通したいステップです。スキルは「モデルが発火を判断する」ため、自動発火に頼ると呼ばれないことがあります。そのためSTEP 1で書いたとおり、CLAUDE.mdのフローから「skill feature-spec を使う」と名前で明示的に呼ぶのが安全です。

このフェーズを CLAUDE.md にも1枚足しておきます。ポイントは停止①（仕様レビュー）をここで固定すること。スキルの発火に頼らず、フロー側で「承認まで実装に進まない」と明示します。

CLAUDE.md

## Phase 2: 仕様書（skill「feature-spec」を使う）
調査結果を skill「feature-spec」で SPEC.md にまとめる（2部構成＋並列グループ宣言）。
- 人間には Part 1 だけ提示し、Part 2 は「技術詳細なのでレビュー不要」と伝える。
- 【停止①】仕様書を提示したら、人間が承認するまで Phase 3 に進まないこと。

STEP 4：TDDの実装ルールと「サボり封じ」を書く

実装中ずっと効かせる品質規約は、reviewer サブエージェントにバンドルします。まずTDDの基本。

## 実装セットの進め方（RED → GREEN → REFACTOR）
1. テストを先に書く（RED）
2. 通す最小限の実装を書く（GREEN）
3. リファクタ（REFACTOR）
4. テスト通過を確認 → 次のセットへ
5. 失敗したら自分で直す。3回直して通らなければ報告。

そして自律エージェントで一番大事な「サボり方の封じ込め」。

## 絶対にやってはいけないこと
- テストを削除・無効化して「通った」ことにする
- テストの期待値（アサーション）をこっそり緩めて通す
- 失敗を無視して次に進む
- 毎回「どうしますか？」と人間に丸投げする

「期待値を緩めるな」は、削除禁止だけでは塞げない巧妙な抜け道です。

並列実装と統合ゲート（並列の本丸）

並列で読むのは衝突しません。難しいのは並列で書くこと。同じファイルを複数エージェントが触ると統合時に壊れます。そこで2つの条件を置きます。

ファイル独立：同時に走るセットが互いに別ファイルだけを触る（仕様書の並列グループが宣言済み）。これが満たせれば worktree すら不要。各自が新規ファイルを作るだけなので衝突しない。
隔離：独立を保証できない／既存ファイルを複数セットが触るなら、各実装者を別git worktree に分けて書き込み衝突を防ぐ。

並列実装の後には統合ゲートを必ず1枚置きます。共有ファイルを触る結線（合成・ルーティング）はここだけ1エージェントを逐次で行い、最後に全テスト＋lintを緑にする。

CLAUDE.md

## Phase 3: 実装（TDD・並列）
仕様書 Part 2 の「並列グループ」ごとに implementer を同時起動。各自 RED→GREEN→REFACTOR。
- 各セットは自分のファイルと自分のテストだけを書く（共有ファイルは触らない）。
- ファイル独立が明確なら worktree 不要。怪しければ別 worktree で隔離。
- 依存するセットは次の波へ（依存順は仕様書が宣言）。

## Phase 4: 統合ゲート（並列実装の後に必ず1枚・親が逐次で）
- 親（または1体の implementer）が各セットの成果を結線する（共有ファイルを触るのはここだけ）。
- 全テスト＋lintを回して緑を確認。競合・重複・宣言外のファイル変更がないか確認。

STEP 5：役割ごとにモデルを割り当てる（実行レイヤー）

サブエージェントは .claude/agents/ に定義し、フロントマターの model フィールドで役割ごとにモデルを固定します。タスクごとに動的に切り替えるのではなく、役割で割り当てるのがポイント。

.claude/agents/implementer.md

---
name: implementer
description: 機能実装・バグ修正用。複雑な実装に使う。
tools: Read, Edit, Write, Bash
model: opus
---
あなたは実装担当です。仕様書（feature-spec の Part 2）を「正」とし、以下の品質規約に従って TDD で実装してください。

## 実装セットの進め方（RED → GREEN → REFACTOR）
1. テストを先に書く（RED）
2. 通す最小限の実装を書く（GREEN）
3. リファクタ（REFACTOR）
4. テスト通過を確認 → 次のセットへ
5. 失敗したら自分で直す。3回直して通らなければ報告。

## 絶対にやってはいけないこと
- テストを削除・無効化して「通った」ことにする
- テストの期待値（アサーション）をこっそり緩めて通す
- 失敗を無視して次に進む
- 毎回「どうしますか？」と人間に丸投げする

## 並列実装のルール
- 各セットは自分のファイルと自分のテストだけを書く（共有ファイルは触らない）。
- ファイル独立が明確なら worktree 不要。怪しければ別 worktree で隔離。
- 共有ファイルを触る結線は行わない（統合ゲートの担当）。

.claude/agents/reviewer.md

---
name: reviewer
description: コード品質レビュー用。コード変更後に使う。
tools: Read, Grep, Glob, Bash
model: sonnet
---
あなたはシニアレビュアーです。読み取り専用で、指摘のみを箇条書きで返します（自動修正はしない）。

## 守られているべき品質規約（実装が違反していないか確認する）

### 実装セットの進め方（RED → GREEN → REFACTOR）
1. テストを先に書く（RED）
2. 通す最小限の実装を書く（GREEN）
3. リファクタ（REFACTOR）
4. テスト通過を確認 → 次のセットへ
5. 失敗したら自分で直す。3回直して通らなければ報告。

### 絶対にやってはいけないこと（違反を検出する）
- テストを削除・無効化して「通った」ことにする
- テストの期待値（アサーション）をこっそり緩めて通す
- 失敗を無視して次に進む
- 毎回「どうしますか？」と人間に丸投げする

## レビュー観点（Phase 5：呼び出し時に指定された次元を担当する）
- 正しさ（バグ・境界条件）
- 仕様カバレッジ（受け入れ条件 vs 実装・テスト）
- 重複・過剰実装・抜け漏れ
- 型安全・データ層の整合

担当次元の指摘だけを箇条書きで返すこと。修正可否の判断は親に委ねる。

model にはエイリアス（haiku / sonnet / opus）、フルID（例：claude-opus-4-6）、または親を継承する inherit（デフォルト） が指定できます。役割とモデルの対応はこんなイメージです（状況に合わせてチューニングを）。

役割	モデル	理由
メイン（実装）	`opus`	複雑な作業をこなす地力
レビュー	`sonnet`	速さと質のバランス
調べ物（Explore）	`haiku`	高速・低コスト

各サブエージェントは独自のコンテキストで動くので、メイン会話を圧迫しません。

model はエイリアスで書くこと。 フルIDだと新モデルが出るたびに全ファイル書き換えになります。エイリアス（opus / sonnet / haiku）なら、Claude Codeが最新の対応モデルに自動解決してくれます。

ツール名の確認方法
tools フィールドに指定できるツール名は、Claude Codeのバージョンによって変わる可能性があります。/tools コマンドで現在利用可能なツール一覧を確認し、正確な名前を使ってください。

STEP 6：構造化レビューを「ユーザー起動スキル」にする

ここが、この記事で一番伝えたい部分です。

並列エージェントはコンテキストを節約しながら動くため、構造的にマクロ視点が弱くなります。個々のセットは緑でも、全体で見ると重複や抜け漏れが残る。そのためテストとlintが緑になった「後」に、人間が必ず止まって目で見るレビューを入れます。

ただし、いきなり人間が全体を精査するのは重い。そこで二段構えにします。

機械側の事前ふるい：人間レビューの前に「検証を観点ごとに分けて並列で走らせる工程」を一枚かませる（1体に全部見せるのではなく、観点別の複数レビュアーに枝分かれさせる＝ファンアウト）。読み取り専用レビュアーを次元ごと（正しさ／仕様カバレッジ／重複・スコープ／型安全）に同時起動し、各自が箇条書きで指摘だけ返す。読むだけなので衝突せず、単一レビュアーが見落とすマクロ問題を次元分担で拾えます。これが並列の3つ目（＝検証の並列）で、一番低リスクで足せる並列です。
人間の判断：その指摘を携えて、最後に人間が /structured-review で止まって判断する。

1段目（機械側のふるい）は、STEP 5 で定義した reviewer を次元ごとに並列起動する工程です。フロー（Phase 5 検証）に対応する関所なので、CLAUDE.md にも1枚足しておきます。

CLAUDE.md

## Phase 5: 検証を観点ごとに並列実行（読み取り専用・停止②の前）
テスト・lintが緑になったら、reviewer を次元ごとに並列起動する（読むだけなので衝突しない）。
- 正しさ（バグ・境界条件）
- 仕様カバレッジ（受け入れ条件 vs 実装・テスト）
- 重複・過剰実装・抜け漏れ
- 型安全・データ層の整合
各レビュアーは箇条書きで指摘のみを返す。修正可否は親が判断（自動修正しない）。その指摘を持って /structured-review へ。

これは絶対に発火させたい停止ポイントです。スキルの自動発火は「呼ばれないことがある」ので、disable-model-invocation: true を付けてユーザー起動専用にし、/structured-review で明示的に叩きます。

.claude/skills/structured-review/SKILL.md

---
name: structured-review
description: 実装後の構造化レビュー（人間の最終チェック）。
disable-model-invocation: true
---
以下を確認し、人間に報告して停止する:
- 画面に必要なCRUD・ロジックが揃っているか
- 過剰実装・重複・抜け漏れがないか
- ドメインの整合性は取れているか

多くの自走フローは停止ポイントを「実装前の仕様レビュー」だけにして、実装後はテストが緑なら自動完了にしてしまう。マクロ視点が弱いと分かっているなら、実装後にも関所を置くべきです。停止は2箇所、仕様レビューと構造化レビュー。

disable-model-invocation の既知の問題
disable-model-invocation: true を設定したスキルでも、セッション再開（--resume）時にモデルから見えてしまうバグや、逆にユーザーがスラッシュコマンドで明示的に呼んでもClaudeが実行を拒否するケースが報告されています（2026年2月時点のGitHub Issues）。うまく動かない場合は、CLAUDE.mdの絶対ルールに「構造化レビューは /structured-review で人間が起動するまで勝手に実行しないこと」と併記しておくと安全です。

STEP 7：E2Eを「スキル」にする（スクリプト同梱）

スキルの真価が出るのがここです。E2Eはそのフェーズでだけ要るうえ、スクリプトを同梱できる。screenshot.sh をスキルフォルダに入れてしまいます。

.claude/skills/e2e-runner/SKILL.md

---
name: e2e-runner
description: E2Eテストとスクリーンショットを生成・実行する。
  「E2Eを書いて」「画面の動作確認をして」のときに使う。
allowed-tools: Read, Write, Bash
---
1. 仕様書の📸マークと撮影ポイントを対応させる
2. Playwright でテストを生成し e2e/ に置く
3. ./screenshot.sh で全画面を撮影し screenshots/ に保存する
（screenshot.sh はこのスキルフォルダに同梱）

.claude/skills/e2e-runner/
├── SKILL.md
└── screenshot.sh   ← 同梱

これでE2Eのときだけテンプレもスクリプトもロードされ、それ以外のフェーズでは1バイトも食いません。しかもE2Eは「E2E書いて」で発火が明確なので、ここは自動発火に任せてOKです。

STEP 8：`/goal` で完了条件を縛り、サーキットブレーカーを付ける

ループの安全装置です。「止まるな」を自然言語で書く代わりに、2026年5月にClaude Code v2.1.139で導入された /goal を使います。

/goal は完了条件をセットすると達成まで自走し、各ターン後に別のエバリュエータモデル（デフォルトはHaiku）が会話トランスクリプトを読んで条件達成を判定するもの。条件を満たさなければ制御を返さず次のターンに入ります。

/goal 全実装セットが緑 かつ lint通過 かつ 構造化レビュー承認まで完了させる

これで「止まるな」が言い回し頼みでなくなり、サブエージェントが気分で離脱する事故が減ります。

/goal のエバリュエータの限界
エバリュエータモデルは会話トランスクリプトだけを読んで判定します。ファイルを読んだりコマンドを実行したりはしません。つまり、Claudeが「テスト全部通りました」と報告すればエバリュエータはそれを信じます。完了条件はClaudeが会話中に出力として明示的に示せるもの（テスト実行結果の貼り付け、lintの出力など）にしてください。「コードの品質が高い」のような主観的条件は機能しません。

ただし自走＝暴走と紙一重なので、サーキットブレーカーを必ず付けます。

CLAUDE.md

## サーキットブレーカー
- フロー開始時に `/goal` を1回セットしてから自走に入る（条件の書き方は下記）。
- 完了条件はタイトに（曖昧な条件は無限ループの燃料）
- `/goal` の条件に**ターンまたは時間の上限を条件文として**含める（例：「or stop after 20 turns」）
- Autoモードで全ツールを無条件承認しない
- テスト修正は1セット3回まで（局所上限）
- フロー全体の上限も必ず持つ（局所上限だけでは財布を守れない）

/goal の上限はフラグではなく「条件文」に書く
/goal の形態は次の3つです。

コマンド	動作
`/goal <条件>`	ゴールを設定（そのターンが即開始）
`/goal`	ステータス確認（経過時間・評価済みターン数・累計トークン・直近の判定理由）
`/goal clear`	ゴール解除（`stop` / `off` / `reset` / `none` / `cancel` も同義）

ターン上限などはフラグではなく完了条件の文章の中に書きます。公式の例は 「or stop after 20 turns」のようなターン／時間の節（clause） です。エバリュエータは会話に現れた内容しか見ない（コマンド実行やファイル読み取りはしない）ため、累計トークンは /goal のステータスで確認はできても、トークン数を停止条件にするのは不確実で、ターン／時間で縛るのが確実です。条件文は最大4,000文字まで。

なお /goal の実体はセッションスコープのプロンプトベースStopフックで、信頼ダイアログを承認したワークスペースでのみ動作します（disableAllHooks 等が有効だと使えません）。

局所上限（修正3回）に加えて、フロー全体の上限も必ず持つこと。

動かしてみる

組み上がりました。あとは起動するだけです。

claude
# または
claude -p "ユーザー一覧画面に検索機能を追加して"

親がCLAUDE.mdの骨格を読み、こう流れます。

Phase 1 並列調査：ビルトインExploreを使って同時調査
Phase 2 仕様書 → 停止①：feature-spec スキルが並列グループ宣言つきの仕様書を出し、承認を求めて止まる
Phase 3 並列実装：承認後、独立セットを同時実装
Phase 4 統合ゲート：結線を1箇所に束ね、テスト＋lintを緑に
Phase 5 並列検証 → 停止②：検証を観点ごとに分けて並列実行し、その指摘を持って /structured-review で再び止まる

調査・実装・検証の3面で並列が効きつつ、必要なフェーズでだけスキルがロードされるので、コンテキストは常に軽いままとなります。

完成したファイル一式

STEP 0〜8 を終えると、手元にはこのフレームワーク一式が残ります。

my-project/
├── CLAUDE.md                          # STEP 1,2,4,6,8: 案内役（骨格＋各Phase＋停止＋ブレーカー）
├── .claude/
│   ├── agents/
│   │   ├── implementer.md             # STEP 5: 実装担当（model: opus）
│   │   └── reviewer.md                # STEP 4,5: レビュー担当（model: sonnet・品質規約を同梱）
│   └── skills/
│       ├── feature-spec/SKILL.md      # STEP 3: 仕様書を生成（SPEC.md を出力）
│       ├── structured-review/SKILL.md # STEP 6: 構造化レビュー（/structured-review で起動）
│       └── e2e-runner/                # STEP 7: E2E（スクリプト同梱）
│           ├── SKILL.md
│           └── screenshot.sh
└── tests/                             # STEP 0: テスト規約・ハーネス置き場

これがハンズオン（STEP 0〜8）で組み上がる雛形そのものです。冒頭「完成イメージ」に出てくる SPEC.md や、src/ の実装ファイルは、この雛形を実際に走らせたとき（前項「動かしてみる」）に feature-spec や implementer が生み出す成果物であって、雛形には最初から含まれません。

付録：フレームワーク全ファイル（コピペ用）

STEP 1〜8 では各ファイルを断片で示しました。ここに完成形を1箇所にまとめます（特に CLAUDE.md は5つのSTEPに分散、reviewer.md は本文で省略した品質規約を展開済み）。コマンドは <テストコマンド> のようにプレースホルダのままです。自分のスタックに差し替えれば、そのまま動きます。

CLAUDE.md

# Parallel Subagent Framework

## 実施時のカスタマイズ（置き換えること）
- テストコマンド: <テストコマンド>   # 例: bun run test / pytest
- Lintコマンド:   <Lintコマンド>     # 例: bun run lint / ruff check
- UIディレクトリ: src/components/   / データ取得: src/api/  / DB: prisma/schema.prisma

## フロー（骨格）
Phase 1 調査(並列) → Phase 2 仕様書(並列グループ宣言) → [停止① 人間レビュー] → Phase 3 実装(TDD・並列) → Phase 4 統合ゲート → Phase 5 検証(並列) → [停止② 構造化レビュー]

## どのフェーズでどのスキルを呼ぶか
- Phase 2（仕様書）→ skill「feature-spec」を使う
- E2E・スクショが必要なとき（随時・フロー外）→ skill「e2e-runner」を使う
- Phase 5（検証）のあと → ユーザーに /structured-review を促して停止する

## 絶対ルール
- 確認を求めるのは「仕様レビュー（停止①）」と「構造化レビュー（停止②）」の2箇所のみ。
- それ以外は止まらず自律的に進める。
- 停止①：仕様書を提示したら、人間が承認するまで Phase 3（実装）へ進まないこと。
- 停止②：構造化レビューは `/structured-review` で人間が起動するまで勝手に実行しないこと。

## Phase 1: 調査（並列・ビルトインExplore活用）
以下の3つの調査を、それぞれ独立したサブエージェントで**並列に**実行する。

- UIディレクトリを調査。関連コンポーネントのファイルパス・props型・state・主要イベントハンドラを箇条書きで報告。コードは書くな。
- データ取得ディレクトリを調査。APIエンドポイント・型・hookを箇条書きで報告。コードは書くな。
- DB/スキーマを調査。テーブル構造・リレーション・データアクセス層を箇条書きで報告。コードは書くな。

各調査の報告は**箇条書きのみ**。長文の説明は不要。

## Phase 2: 仕様書（skill「feature-spec」を使う）
調査結果を skill「feature-spec」で SPEC.md にまとめる（2部構成＋並列グループ宣言）。
- 人間には Part 1 だけ提示し、Part 2 は「技術詳細なのでレビュー不要」と伝える。
- 【停止①】仕様書を提示したら、人間が承認するまで Phase 3 に進まないこと。

## Phase 3: 実装（TDD・並列）
仕様書 Part 2 の「並列グループ」ごとに implementer を同時起動。各自 RED→GREEN→REFACTOR。
- 各セットは自分のファイルと自分のテストだけを書く（共有ファイルは触らない）。
- ファイル独立が明確なら worktree 不要。怪しければ別 worktree で隔離。
- 依存するセットは次の波へ（依存順は仕様書が宣言）。

## Phase 4: 統合ゲート（並列実装の後に必ず1枚・親が逐次で）
- 親（または1体の implementer）が各セットの成果を結線する（共有ファイルを触るのはここだけ）。
- 全テスト＋lintを回して緑を確認。競合・重複・宣言外のファイル変更がないか確認。

## Phase 5: 検証を観点ごとに並列実行（読み取り専用・停止②の前）
テスト・lintが緑になったら、reviewer を次元ごとに並列起動する（読むだけなので衝突しない）。
- 正しさ（バグ・境界条件）
- 仕様カバレッジ（受け入れ条件 vs 実装・テスト）
- 重複・過剰実装・抜け漏れ
- 型安全・データ層の整合
各レビュアーは箇条書きで指摘のみを返す。修正可否は親が判断（自動修正しない）。その指摘を持って /structured-review へ。

## サーキットブレーカー
- フロー開始時に `/goal` を1回セットしてから自走に入る（条件の書き方は下記）。
- 完了条件はタイトに（曖昧な条件は無限ループの燃料）
- `/goal` の条件に**ターンまたは時間の上限を条件文として**含める（例：「or stop after 20 turns」）
- Autoモードで全ツールを無条件承認しない
- テスト修正は1セット3回まで（局所上限）
- フロー全体の上限も必ず持つ（局所上限だけでは財布を守れない）

.claude/agents/implementer.md

---
name: implementer
description: 機能実装・バグ修正用。複雑な実装に使う。
tools: Read, Edit, Write, Bash
model: opus
---
あなたは実装担当です。仕様書（feature-spec の Part 2）を「正」とし、以下の品質規約に従って TDD で実装してください。

## 実装セットの進め方（RED → GREEN → REFACTOR）
1. テストを先に書く（RED）
2. 通す最小限の実装を書く（GREEN）
3. リファクタ（REFACTOR）
4. テスト通過を確認 → 次のセットへ
5. 失敗したら自分で直す。3回直して通らなければ報告。

## 絶対にやってはいけないこと
- テストを削除・無効化して「通った」ことにする
- テストの期待値（アサーション）をこっそり緩めて通す
- 失敗を無視して次に進む
- 毎回「どうしますか？」と人間に丸投げする

## 並列実装のルール
- 各セットは自分のファイルと自分のテストだけを書く（共有ファイルは触らない）。
- ファイル独立が明確なら worktree 不要。怪しければ別 worktree で隔離。
- 共有ファイルを触る結線は行わない（統合ゲートの担当）。

.claude/agents/reviewer.md

---
name: reviewer
description: コード品質レビュー用。コード変更後に使う。
tools: Read, Grep, Glob, Bash
model: sonnet
---
あなたはシニアレビュアーです。読み取り専用で、指摘のみを箇条書きで返します（自動修正はしない）。

## 守られているべき品質規約（実装が違反していないか確認する）

### 実装セットの進め方（RED → GREEN → REFACTOR）
1. テストを先に書く（RED）
2. 通す最小限の実装を書く（GREEN）
3. リファクタ（REFACTOR）
4. テスト通過を確認 → 次のセットへ
5. 失敗したら自分で直す。3回直して通らなければ報告。

### 絶対にやってはいけないこと（違反を検出する）
- テストを削除・無効化して「通った」ことにする
- テストの期待値（アサーション）をこっそり緩めて通す
- 失敗を無視して次に進む
- 毎回「どうしますか？」と人間に丸投げする

## レビュー観点（Phase 5：呼び出し時に指定された次元を担当する）
- 正しさ（バグ・境界条件）
- 仕様カバレッジ（受け入れ条件 vs 実装・テスト）
- 重複・過剰実装・抜け漏れ
- 型安全・データ層の整合

担当次元の指摘だけを箇条書きで返すこと。修正可否の判断は親に委ねる。

.claude/skills/feature-spec/SKILL.md

---
name: feature-spec
description: 調査結果から機能仕様書を生成する。新機能の実装フローで仕様を固める段階で使う。
---
仕様書は2部構成で出力する:

## Part 1 — 仕様（★人間がレビューする部分）
- 何ができるようになるか（利用者目線・技術用語なし）
- 画面イメージ / 操作の流れ / 受け入れ条件（チェックリスト）
- スクショ撮影ポイントには 📸 マークを付ける（STEP 7 の e2e-runner と対応させる）

## Part 2 — 実装計画（AI用・レビュー不要）
- 実装セット一覧（依存順）/ 各セットのテスト観点 / 型・データアクセス層の方針
- 並列グループ宣言：各セットが**触るファイル**を書き、互いに別ファイルだけのセットを同じ「波」（同時実装可）にまとめる。共有ファイルを触る結線は波にせず統合ゲートへ。

仕様書は SPEC.md に出力する。
提示時は Part 1 だけ見せ、Part 2 は「技術詳細なのでレビュー不要」と伝える。

.claude/skills/structured-review/SKILL.md

---
name: structured-review
description: 実装後の構造化レビュー（人間の最終チェック）。
disable-model-invocation: true
---
以下を確認し、人間に報告して停止する:
- 画面に必要なCRUD・ロジックが揃っているか
- 過剰実装・重複・抜け漏れがないか
- ドメインの整合性は取れているか

.claude/skills/e2e-runner/SKILL.md

---
name: e2e-runner
description: E2Eテストとスクリーンショットを生成・実行する。
  「E2Eを書いて」「画面の動作確認をして」のときに使う。
allowed-tools: Read, Write, Bash
---
1. 仕様書の📸マークと撮影ポイントを対応させる
2. Playwright でテストを生成し e2e/ に置く
3. ./screenshot.sh で全画面を撮影し screenshots/ に保存する
（screenshot.sh はこのスキルフォルダに同梱）

.claude/skills/e2e-runner/screenshot.sh

#!/usr/bin/env bash
# E2E スクリーンショット撮影スクリプト（e2e-runner スキル同梱）
# Usage: ./screenshot.sh <url> <name>
#   url  : 撮影対象URL（例: http://localhost:3000/users）
#   name : 出力ファイル名（拡張子不要。screenshots/<name>.png に保存）
set -euo pipefail

URL="${1:?usage: ./screenshot.sh <url> <name>}"
NAME="${2:?usage: ./screenshot.sh <url> <name>}"

OUT_DIR="screenshots"
mkdir -p "$OUT_DIR"
OUT_PATH="${OUT_DIR}/${NAME}.png"

# Playwright CLI を利用（npx playwright が無ければ案内して終了）
if ! command -v npx >/dev/null 2>&1; then
  echo "error: npx が見つかりません。Node.js / Playwright を導入してください。" >&2
  exit 1
fi

echo "📸 capturing ${URL} -> ${OUT_PATH}"
npx playwright screenshot --full-page "$URL" "$OUT_PATH"
echo "saved: ${OUT_PATH}"

tests/README.md

# tests/

テストハーネス置き場。実装セットごとのテストをここに置く。

## 規約
- TDD: 各実装セットはテスト先行（RED → GREEN → REFACTOR）。
- 完了判定は機械が下せる状態にする（テスト緑 + lint緑）。
- `--fast` 相当の高速モードを用意しておくと、ループ中の反復が軽い。

## コマンド（CLAUDE.md のプレースホルダと一致させること）
- テスト: `<テストコマンド>`        # 例: bun run test
- 高速:   `<テストコマンド> --fast`  # 例: bun run test --fast
- Lint:   `<Lintコマンド>`          # 例: bun run lint

screenshot.sh には実行権限を付けておきます（chmod +x .claude/skills/e2e-runner/screenshot.sh）。

おわりに

ゼロから組んできて、最後に残るのはシンプルです。「何を作るか」を仕様として確定させることと、「最後の構造化レビュー」だけは人間の仕事だということです。この順序と、手放さない2つの関所さえ守れば、並列エージェントはとても強力な武器になります。

手を動かしながら読んでいただけたなら嬉しいです。詰まった点や、もっと知りたいところがあればぜひ教えてください！ここまで読んでいただき、ありがとうございました。

普段は、GEAR.indigo Bizという要件定義・設計AIソリューションを無料提供しております！
本エージェントと組み合わせ利用もすることが多いので、ぜひご覧ください！

GEAR.indigo Biz は BYOK で無料で使えます
「会議メモを貼るだけ。要件と設計が、勝手に前に進む。」——本記事で書いた「ツールを忘れて、決断に集中する」状態を、ぜひ手元で体験してみてください。