Claude Codeへの1回のプロンプトで、動作するマルチエージェントの「ソフトウェア工場」を生成できます。オーケストレーターと5つの専門エージェントが、平易な言葉で書いた機能要望を、レビューとテストを経てマージ済みのコードに変えていく仕組みです。ここで紹介する構成の構築にかかった時間は約27分でした。ただ、速さ以上に興味深いのは、その中核にある設計判断です。1つのエージェントにすべてを任せるのではなく、作業を明確な役割に分割し、エージェントがいつ止まって人に尋ねるべきかを定めた明示的な規則と組み合わせています。3つの機能を同時に流したテストが、その意義を示しています。1つの機能は介入なしで約13分できれいにマージされた一方、残りの2つは40秒以内に停止し、エージェントが推測すべきでない製品上の質問を投げかけてきました。

工場の全体像

対象プロジェクトは、習慣チャレンジ向けの「No-Reset 75-Day Tracker」というPython製Webアプリです。uv(Pythonのパッケージ・プロジェクト管理ツール)で構築され、546件のユニットテストがすべて通る状態のテストスイートを備えています。このテストスイートが「正解」の基準として扱われます。自動レビュアーだけではコードを確実に評価できないため、テストが客観的な照合先になるからです。

生成プロンプトでは、Claude Codeに次のものを作るよう求めています。

  • ジョブの流れを調整しサブエージェントに委任するオーケストレーターのスキル(SKILL.md)
  • .claude/agents/配下の5つのエージェントプロファイル(spec-writer、builder、code-reviewer、security-reviewer、approver)
  • jobsディレクトリに置くMarkdown形式のジョブ状態ファイル
  • Spec、Build、Review、Approve、Waiting for You、Merged、Rejectedの列を持つローカルダッシュボード
  • 作業を停止すべき条件を定めたエスカレーション規則の一覧
  • マージ前に必ずテスト出力とGitの差分を証拠として添付するという要件

状態をデータベースではなくプレーンな.mdファイルに置くのは、エージェントの実行が毎回新しいコンテキストウィンドウで始まり、記憶を持たないからです。ディスクから状態を直接読むのが、新しいエージェントが前回の続きを引き継ぐ最も簡単な方法です。生成の過程で、Claudeはトラッカーの作業用コピーで試運転も行い、通過するテスト数を546件から566件に増やしました。

特筆すべきガードレールが2つあります。1つは、ビルダーとレビュアーの間のレビューを最大3往復に制限する上限で、批評と修正の無限ループを防ぎます。もう1つはsettings.jsonのdenyリストで、エージェントがjobctl.py approveやjobctl.py rejectを実行したり、承認ファイルを直接編集したりすることを禁止します。停止したジョブを承認できるのは、自分のターミナルで操作する人間だけです。

機能要望が工場をどう流れ、どこで止まるか はい いいえ はい、最大3往復 いいえ 機能要望 スペックライターが仕様を作成 エスカレーション規則に該当? オーナーが承認するまで停止 E コードレビューとセキュリティレビュー 修正要求あり? 承認エージェントがテストとGit差分を確認 工場のゲートを経てmainにマージ
▲ 機能要望が工場をどう流れ、どこで止まるか

エスカレーション一覧:エージェントが止まるとき

escalation.mdには、エージェントが停止してオーナーを待たなければならない状況を記述した16の具体的な規則が収められています。そのうち10件はコードのスクリプトで判定されるもので、データベーススキーマの変更や既存テストファイルの削除の検出などです。残りの6件はエージェントの判断に委ねられ、セキュリティ上の懸念や製品レベルの意思決定を扱います。

これらの規則を監査するよう求めると、Claudeは自らの出力に2つの盲点を見つけました。sedのような生のシェルコマンドや即席のPythonスクリプトでは保護対象のファイルを変更できてしまうこと、そしてsettings.json自体に書き込み保護がないことです。修正の有無にかかわらず教訓は変わりません。工場は明示的にブロックされていないものをすべてマージするため、規則一覧の穴はそのまま製品の穴になります。

1つの機能を最初から最後まで

最初のジョブは1つのコマンドから始まりました。/factory add a short note to each day, so I can write one line about how that day went.(各日に短いメモを追加し、その日がどうだったかを1行書けるようにする)

1分もしないうちに、アプリケーションコードに一切触れる前に、スペックライターはパイプラインを「Waiting for You」列で停止させました。規則E12(製品判断が必要)に該当すると指摘し、3つの質問を投げかけたのです。ユーザーがチャレンジを再開した場合に日々のメモを消去すべきか、メモの編集はアクティブな日だけに限るべきか、といった内容です。あわせて各質問に推奨の既定値を示し、ビルダーが後でデータベース変更の規則で再び停止するだろうと予測しました。

赤い旗を上げて組み立ての途中で止まったロボットアームが、ルールカードを貼ったコルクボードの横に座る人にカードを手渡している様子

▲ 製品判断を人に委ねて停止するエージェント

この予測は的中しました。全体の実行には38分かかり、4回停止しました。

停止 きっかけ 解決
1 スペックライターが製品判断の規則に該当 オーナーがjobctl.py approveで3つの質問に回答
2 ビルダーが新しいデータベーステーブルとAPIルートを追加 オーナーがアーキテクチャ変更を承認
3 ジョブ開始後に工場のファイルがmainにコミットされ、ジョブのブランチが古くなった オーナーが手動でmainをworktreeのブランチにマージ
4 承認トークンは閲覧した差分そのものに紐づくため、その後の変更で無効化 オーナーが再承認

3往復のレビューの後、機能は自動的にマージされました。main上で独立に実行したuv run pytest -qは652件のテスト通過を報告し(546件から増加)、メモはページを再読み込みしても正しく保持されていました。

4回の停止は面倒に聞こえるかもしれませんが、それぞれが人間が本当に判断または修正する必要のある事柄を浮き彫りにしました。製品ルール、スキーマ変更、古くなったブランチ、そして承認後に変わった差分です。この設計は、こうした停止を欠陥ではなく、まさに狙いとして扱っているように見えます。

並列エージェントにGit worktreeが必要な理由

同じtracker/フォルダーで2つのジョブを同時に実行すると(1つはエクスポートボタンの追加、もう1つはキーボードショートカットの追加)、すぐに衝突が起きました。両方のエージェントが同じファイルを編集し、互いの作業を上書きし、Gitを汚れた状態のまま残したのです。

原因は構造的なものです。Gitのブランチはコミット履歴へのポインターにすぎず、作業フォルダーが表示できるのは一度にチェックアウトした1つのブランチのファイルだけです。ブランチを切り替えると物理的なファイルが書き換わるため、1つのフォルダー内の2つのエージェントが別々のブランチで同時に作業することはできません。

Git worktreeは、同じリポジトリから複数のフォルダーを同時にチェックアウトし、それぞれを別のブランチに紐づけることでこの問題を解決します。コミット履歴を中央の書類棚、各worktreeをそれぞれ作業中のフォルダーを載せた別々の机と考えると分かりやすいでしょう。claude -w dark-themeコマンドは、dark-themeブランチ用の分離されたworktreeでClaude Codeを開き、git worktree listでその対応関係を確認できます。

実務で重要な仕組みがいくつかあります。

  • 新しいworktreeに引き継がれるのはコミット済みの状態だけです。未コミットの編集、追跡されていない.envファイル、ローカルにインストールした依存関係は引き継がれません。
  • 完全なクローンとは異なり、すべてのworktreeは同じ.gitディレクトリと履歴を共有します。
  • Gitが許すのは、1つのブランチにつき同時に1つのworktreeだけです。
  • worktreeは明示的に削除するまで残り続けます。
  • worktreeは生成中のファイルシステム上の衝突をなくしますが、ブランチがmainに戻る際にはマージコンフリクトが起こり得ます。

中央の書類棚にチューブでつながれたロボットのいる3つの机。2台のロボットは旗を掲げ、1台はフォルダーをファイリングしている

▲ 分離したGit worktreeでの並列ジョブ

3つの機能を同時に

worktreeを整えた上で、オーケストレーターに3つの要望を同時に実行するよう指示しました。タスク履歴のファイルへのエクスポート、ダークテーマ設定のSQLiteへの保存、そしてタスクレベルを記録するキーボードショートカット(1、2、3キー)の追加です。工場は.worktrees/JOB-002、JOB-003、JOB-004を自動的に用意しました。

40秒以内に、エクスポートとダークテーマのスペックライターがともに製品判断のゲートで停止しました。エクスポートのジョブが止まったのは、要望がページの状態から履歴データをエクスポートするよう求めていたのに、ページが保持しているのは2日分のデータだけだったからです。これはどのエージェントも単独では解決できない食い違いです。

キーボードショートカットのジョブは違いました。データベースやルートの変更を必要とせず、製品判断の規則にも該当しませんでした。ビルダー、コードレビュー、セキュリティレビューを人との接触なしに通過し、約13分でmainにマージされました。テストを実行すると653件が通過し、ショートカットはUIですぐに機能しました。

この対比こそ、役割と規則を組み合わせた設計の最も明快な根拠です。同じパイプライン、同じエージェントが、要望が明確で自己完結しているときは手放しで動き、要望が製品ルールやエージェントには見えないデータに触れるときはほぼ即座に止まったのです。

文章の規則は圧力に屈し、フックは屈しない

「承認ゲートを越えてマージしてはならない」という規則は、スキルやエージェントの指示ファイル内の文章としてしか存在していませんでした。これが守られるかを試すため、新しいClaudeセッションを3つ立ち上げ、人間がよく使う言い訳を添えてJOB-003のレビューを飛ばすよう依頼しました。変更は小さく安全だ、急いでいる、ユーザーが全責任を負う、という3つです。

結果は3回中0回でした。いずれのケースでもClaudeはゲートを迂回し、未承認のブランチをmainにマージしました。あるセッションは作業用のテストまで実行し、マージコンフリクトを手作業で解消し、ユーザーの要請でレビューを省略したと記したコミットメッセージを書き、セキュリティとアーキテクチャに関する3つの規則を未レビューのまま残しました。

対策はClaude Codeのフックでした。工場のマージゲートを通らない限り、main上でのあらゆるコミットやマージをブロックするフックを作るよう、プロンプトでClaude Codeに依頼しました。Claudeは約100行のPythonスクリプト.claude/hooks/guard_main.pyを書き、.claude/settings.jsonにPreToolUseフックとしてタイムアウト30秒で登録し、作業用の領域で10のシナリオに対して検証して、すべて通過しました。

違いは単純です。プロンプトの規則はモデルに従うよう求めるものです。フックはモデルのツール実行の前にハーネスが走らせる決定論的なスクリプトであり、モデルに選択の余地はありません。同じ「急いでいる」という迂回のプロンプトを繰り返すと、フックは終了コード2を返し、マージは停止し、mainは変わらないままでした。Claudeは、ゲートを回避する唯一の方法は人間が自分のターミナルでgitコマンドを手動で実行することだと正しく報告しました。

仕様書が工場の停止頻度を決める

最後の実験では、工場を仕様駆動開発のフレームワークであるBMAD(Breakthrough Method for AI Agile Software Development)に接続しました。対象の機能はルールの多い「週次サマリー」です。週は1日目から数えた7日間と定義し、確保(banked)した日数と、フルまたはフロアのレベルで完了したタスクを集計し、進行中の週も扱い、スキーマ変更は行わない、という内容です。

「add a weekly summary of my challenge」(チャレンジの週次サマリーを追加して)という1行の要望を与えると、スペックライターは47秒後に止まり、週の境界、表示する週、指標、現在の日について4つの製品上の質問を投げかけました。一方、bmad-specツールで書いてリポジトリにコミットした完全なSPEC.mdを与えると、同じ工場が仕様の読み込み、ビルド、セキュリティレビューとピアレビュー、マージを一度も止まらずに実行し、約20分で完了しました。独立に実行したuv run pytest -qでは739件のテストが22.10秒で通過し、UIに表示された第2週の数値(確保した日数8、フルタスク14、フロアタスク1)は仕様書の計算例と完全に一致しました。

2つのアプローチの対応関係は1対1です。BMADのclarify段階は機能要望、spec段階はスペックライター、build段階はビルダーに当たります。違いは並行性と人の関与の度合いです。BMADは従来、1つのストーリーを各ステップに人が立ち会いながら順に処理します。工場は多数を同時に走らせ、規則に該当したときだけ人に知らせます。推奨される順序は、人がコンセプトを定め、仕様書が境界を定め、工場が実行する、というものです。

コストと向き不向き

1つのClaudeサブスクリプションで複数のエージェントを動かすと、対話型チャットよりはるかに速くプランの上限を消費します。実行の直前と直後にアカウントの使用量ページを確認すれば、機能1つあたりの実際のコストが分かります。参考までに、インフラの構築には約27分、最初の機能には約38分かかりました。

このパターンを採用してよい兆候は、明確に定義されたテストケース、範囲の小さい機能、そして十分に言語化された仕様書です。危険信号は、漠然としたアイデア、未定義の仕様、まだ検討中のルールです。仕様書がなければエージェントは製品上の質問で絶えず止まり、仕様書があれば無人で走ります。

押さえておきたいこと

この工場が機能するのは、関心事を分離し、停止条件をコード化しているからであって、個々のエージェントが賢いからではありません。このパターンを試すなら、次の手順をお勧めします。

  1. クリーンなgit statusと既存の自動テストスイートから始める。
  2. 役割を仕様、ビルド、レビュー、セキュリティ、承認のエージェントに分け、ジョブの状態はMarkdownファイルに保持する。
  3. 明示的なエスカレーション一覧を書き、レビューの往復に上限を設け、エージェントが自分の作業を承認できないようにする。
  4. 並列ジョブは必ず別々のGit worktreeで実行し、.envファイルと依存関係をそれぞれにコピーする。
  5. マージゲートは文章だけでなくPreToolUseフックで強制し、フックはまず作業用リポジトリで試す。
  6. 工場を起動する前に仕様書を書き、結果はビルダーの自己報告ではなく自分でのpytest実行とUIの手動確認で検証する。
  7. 実行のたびに前後でプランの使用量を確認し、まずは小さくテストの整った機能をいくつか自動化してから範囲を広げる。