Claude Codeで25イテレーション170件超のバックログを1セッションで自律完了した話

はじめに

Claude Codeのマルチエージェント体制で、飲食店向けAI原価計算SaaS「Genka」のPhase 1〜4を開発した。結果として25イテレーション・170件超のプロダクトバックログ（PB）を100以上のコミットで1セッション内で自律完了できた。この記事では、大量のバックログをエージェントに自律消化させるために必要だった設計と運用パターンを共有する。

前提: プロジェクトの規模感

• 技術スタック: Next.js 15 + Supabase + Vercel
• エージェント体制: orchestrator / biz-mgr / dev-manager / programmer / qa / tester / incident-commander 等15+ロール
• バックログ: 170件超（MVP機能実装 + プロセス改善 + UX改善 + セキュリティ対策 + 本番環境構築 + 新機能 + 法令準拠 + common/廃止）
• イテレーション: P1(2) + P2(2) + P3(14) + P4(21) = 計25イテレーション、100+コミット、1セッションで消化
• 到達点: Phase 4 P4-21完了、common/廃止・プロジェクト自己完結化

パターン1: programmerへの一括委譲

最も効率に寄与したのが、programmerサブエージェントに「計画策定→実装→テスト→完了処理」を一括で委譲するパターンだ。

なぜ一括委譲が必要だったか

当初はdev-managerがPBごとに計画→programmer委譲→結果確認→次PBという逐次フローだった。問題は：

1. biz-mgrのhookブロック: biz-mgrがプロジェクト配下のファイルを編集しようとするとhookがブロックする。計画策定のたびにこの問題に遭遇
2. コンテキストスイッチコスト: エージェント間の委譲のたびにコンテキストの要約と伝達が発生
3. 承認待ちのボトルネック: 各PBの完了確認でorchestratorに戻る往復が無駄

解決策として、イテレーション単位でprogrammerに一括委譲し、イテレーション内の全PBの計画策定・実装・テスト・完了処理を自律的に実行させた。

パターン2: hookによるガードレール

自律実行の範囲を広げるほど、品質を担保する仕組みが重要になる。

• 工程ゲートhook: 前工程の完了チェックなしに次工程のファイル編集をブロック
• orchestrator編集ブロック: SubagentStart/Stopで検知し、orchestratorがプロジェクト配下を直接編集することを禁止
• passWithNoAssertions: false: vitestのサイレントPASS問題を構造的に防止
• セキュリティhook: hookバイパス経路（11件のVUL）を検出・対策

パターン3: PBの自己完結性

（TODO: PBの記述品質がセッション跨ぎの自律実行を可能にした話。課題+達成目標+受入基準の3点セットが鍵）

結果

Phase	イテレーション数	PB完了数	主な成果
P1	2	9	基盤構築（認証/DB/パーサー）
P2	2	20	栄養計算/アレルゲン/ラベルPDF
P3	14	57	MVP全機能 + プロセス改善
P4	21	84+	本番環境構築 + UC4/UC5 + UT443件 + 法令準拠 + トークンスタック + common/廃止
合計	25	170+	1セッション、100+コミット

パターン4: トークンスタックによるエージェント識別

SubagentStart/Stopイベントをスタック構造で管理することで、ネストしたサブエージェントの深度を正しく追跡できる。これにより、orchestratorがプロジェクトファイルを直接編集することをL1 hookで構造的にブロックできるようになった。

biz-mgrのトークン消失問題は、単純なStart/Stop対応ではなくスタック構造が必要だったことを示す好例だ。

パターン5: プロジェクト自己完結化

当初はcommon/ディレクトリに共通ナレッジを集約していたが、25イテレーションの実績で「2プロジェクト以上で再利用」の基準を満たすものがなかった。common/を廃止し、各プロジェクトが自己完結する方針に転換。メンテナンスコストが下がり、プロジェクト間の暗黙の依存が解消された。

教訓

1. hookは自律性とトレードオフ: 厳格なhookは品質を守るが、自律実行の障壁にもなる。hookの粒度設計が重要
2. 委譲の粒度: PB単位→イテレーション単位に引き上げることで効率が劇的に改善
3. PBの記述品質: 「読み手が計画判断できる」レベルの記述でなければ、自律実行は破綻する
4. 信頼モデルの限界: hookが増えるほどバイパス経路も増える。信頼モデル自体の設計が必要
5. 偽証跡の検出: vitestのpassWithNoAssertionsが127件全PASSの偽証跡を生んだ。テスト結果を信頼する前に「何を検証したか」を確認する仕組みが必要
6. 共通化は実績で判断: 「将来使うかも」ではなく「実際に2プロジェクト以上で使われたか」で共通化を判断する
7. 原因の思い込みは危険: PB増殖をサブエージェントの暴走と断定していたが、実際はユーザーの別セッション操作だった

まとめ

25イテレーション・170件超のPBを1セッションで自律完了できたのは、hookによるガードレール、PBの記述品質、一括委譲パターン、トークンスタックによるエージェント識別、そしてプロジェクト自己完結化の5要素が揃った結果だ。特にhookとPB記述品質が最も重要で、この2つが欠けると自律実行は早期に破綻する。