AI-DLC Workflow V2のConstruction Phase: "設計を動くコードにする"構造化された実行
「設計はできた。さあコードを書こう」と思ったとき、何から手をつけますか？ どの順番で？ 並列にできるものは？ V2のConstruction phaseは「ただコードを生成する」のではなく、Unit（作業単位）とその依存グラフで実行順序と並列性を制御し、Bolt（計画上のデリバリスライス）で「どこまでを1つのまとまりとして届けるか」を計画します。シリーズ第11回。
Series: AI-DLC Workflow V2の解説 (31 articles)
- …
- 11AI-DLC Workflow V2のConstruction Phase: "設計を動くコードにする"構造化された実行 This article
1. なぜ構造化されたConstructionが必要なのか
まずは、そもそもの問いから始めましょう。「設計ができたら、あとはコードを生成すればいいのでは？」と思いますよね。
課題: 「一気に全部生成」が破綻するとき
AI-DLC Workflow V2（以降V2）のInception phase では、要件・ストーリー・アーキテクチャ設計・作業分解が済んでいます。しかし、それを「1つのプロンプトで一気にコード生成する」アプローチには、プロジェクトが一定の規模を超えると3つの問題が顕在化します。
- コンテキスト容量の壁: 10個のサービスとその設計文書を一度にAIに渡すと、コンテキストウィンドウを圧迫し、後半の生成品質が劣化します
- 検証不能性: 一度に大量のコードが出力されると、「どこが正しくてどこが間違いか」を特定する手段がありません
- 依存の無視: 認証サービスが存在しない状態で認証を前提としたAPIを生成しても、動きません
解決: 作業を分解し、依存順で段階的に実行する
V2のConstruction phaseは、この問題に対して「Staged Decomposition」という設計原則で応えています。単発生成ではなく、検証可能な小さな単位（Unit）に分解し、Unit間の依存関係を尊重した順序で進めるという方針です。
仕組み: 7ステージ＋概念レイヤーの整理
Construction phaseは7つのステージで構成されています。
| # | ステージ | リードエージェント | 実行単位 | 概要 |
|---|---|---|---|---|
| 3.1 | Functional Design | Architect | Unit単位 | エンティティ、ビジネスルール、機能仕様を設計する |
| 3.2 | NFR Requirements | Architect | Unit単位 | 性能・セキュリティ・拡張性・信頼性・可観測性の要件と技術スタックを決める |
| 3.3 | NFR Design | Architect | Unit単位 | 非機能要件をどう実現するかを設計する |
| 3.4 | Infrastructure Design | AWS Platform | Unit単位 | インフラ構成、監視設計、デプロイ構成を定義する |
| 3.5 | Code Generation | Developer | Unit単位 | 実装計画に沿ってコードとユニットテストを生成する |
| 3.6 | Build and Test | Quality | 全体で1回 | 全Unitを統合してビルドし、統合・性能・セキュリティテストを実行する |
| 3.7 | CI Pipeline | Pipeline Deploy | 全体で1回 | CI設定と品質ゲートを作成する |
そして、この7ステージを「何を・どの順序で・どう並列に」制御するために、いくつかの概念が登場します。ここで重要なのは、実行を駆動する概念と、計画を表す概念を区別することです。
- Unit（作業の最小単位）— 実行の起点。Unit間の依存グラフが実行順序と並列性を決める
- Runtime batch（並列バッチ）— 依存が解けて同時に走れるUnitの集まり。Unit依存DAGから算出される
- Bolt（ボルト）— 計画上のデリバリスライス。「どのUnitをひとまとまりにして、どこまで達成したら"届けた"と見なすか」を計画する単位。Delivery Planning（2.9）が、まとめる対象のUnit・完了の基準（Definition of Done）・「これを先に届ければ何の不安が解消できるか」という見立て・担当を記録する。ただしBoltは計画上の区切りであって、実行の順序や並列性を決めるものではない（それはUnitの依存グラフが決める）
- worktree — Boltが自律的な並列実行（後述のSwarm）で走るときのgit分離機構。Boltそのものでもバッチでもない
ここから先は、この概念を順に見ていきます。まず実行の起点であるUnitからです。
2. Unitとは何か
では最初の構成要素、Unitから見ていきましょう。
課題: 「全体を一塊」では粒度が粗すぎる
「タスク管理APIを実装する」と言ったとき、その中には認証、データモデル、ビジネスロジック、通知、UIコンポーネントなど、性質の異なる作業が混在しています。これを1つの塊として扱うと、進捗の可視化もできず、部分的なやり直しもできません。
解決: 独立して設計・実装・検証できる最小単位に分ける
Unitは「1つのサービス」「1つのライブラリ」「1つのUIコンポーネント」といった、独立して設計・実装・テストできる粒度の作業単位です。Unitは「WHAT（何を作るか）」を表し、Construction phaseの実行はこのUnitを起点に回ります。
仕組み: Inception phaseでの定義と依存DAG
UnitはInception phaseのUnits Generation（ステージ2.7）で定義されます。このステージでは2つのことが行われます。
- ドメイン設計を分解し、Unit（作業単位）を列挙する
- Unit間の依存関係をDAG（有向非巡回グラフ）として
unit-of-work-dependency.mdに記述する
たとえば、以下のような依存構造が定義されます。
この「何が何に依存しているか」というトポロジー情報が、Construction phaseの実行順序と並列性を決定する起点になります。コンパイラはこの依存ブロックを
runtime-graph.jsonのbolt_dagノードに読み込み、依存が満たされたUnitを「同時に走れるバッチ（runtime batch）」として算出します。3. BoltとRuntime batch — 計画と実行を分けて考える
続いて、Unitをどうまとめて、どう実行するかの仕組みです。ここが、計画と実行を混同しやすい最も重要なポイントです。
課題: 「計画上のまとまり」と「実行時の並列グループ」を混同しやすい
Unitが10個あるプロジェクトを進めるとき、私たちは2つの異なる問いを持っています。ひとつは「どのUnitを1つのデリバリスライスとしてまとめ、何をDefinition of Doneとするか」という計画の問い。もうひとつは「実行時にどのUnitが同時に走れるか」という実行の問いです。この2つを同じ概念で語ると、話が噛み合わなくなります。
解決: Boltは計画、Runtime batchは実行、と役割を分ける
- Bolt（ボルト）: 計画上のデリバリスライス。ホワイトペーパーではスプリントに相当する高速イテレーションとして導入された概念で、V2ではInception phaseの最終ステージ Delivery Planning（ステージ2.9）が、1つ以上の依存Unitをまとめて「grouping・Definition of Done・確信仮説・オーナーシップ」を
bolt-plan.mdに記録します。Boltは「どこまでを1つのまとまりとして届けるか」を表す計画概念であり、実行の境界ではありません。 - Runtime batch（並列バッチ）: 実行時の並列グループ。
unit-of-work-dependency.md（2.7）のUnit依存DAGから算出される、互いに依存せず同時に走れるUnitの集まりです。実行時のバッチ化と順序付けは、この依存グラフが駆動します。
仕組み: 実行を駆動するのはUnit依存DAG、bolt-plan.mdは計画の記録
Delivery Planning（ステージ2.9）が生成する
bolt-plan.mdは、計画コンテンツ（planning content）です。デフォルトの実行方式であるstage-major walkは、このbolt-plan.mdをUnitのグルーピングや実行順序の境界として消費しません。実行時にどのUnitが同時に走れるかは、あくまでunit-of-work-dependency.md（2.7）の依存DAGから決まります。先ほどの依存DAGの例で、runtime batchを見てみましょう。
- Batch 1: Unit A（データモデル。依存なし）
- Batch 2: Unit B（認証サービス）+ Unit C（通知サービス）。ともにUnit Aのみに依存し、互いに独立 → 並列実行
- Batch 3: Unit D（APIゲートウェイ）。Unit BとUnit Cの両方に依存
一方で
bolt-plan.mdは、「Unit AとBを1つのBoltとして先に届け、その確信が得られてからC・DのBoltへ」といったデリバリ計画を記録します。これは経済的な観点（リスク優先、価値優先など）でDelivery Agentが判断し、人間が承認時に調整できます。計画は計画として価値がありますが、デフォルトのstage-major実行では、実行の駆動役はUnit依存DAGです。
4. Functional DesignからCode Generationまで: Unit単位で繰り返すステージ
ここからは、5つの設計〜生成ステージがどう回るかを見ていきます。
課題: いきなりコードを書くと設計判断が暗黙になる
「とりあえず動くコードを出して」とAIに依頼すると、非機能要件やインフラ構成に関する判断がコード内に暗黙的に埋め込まれます。後から「なぜこのキャッシュ戦略を選んだのか」「なぜこのIAMロール構成なのか」を問うても、根拠が残っていません。
解決: 設計判断を段階的に明示化してからコード生成に入る
ステージ3.1（Functional Design）から3.5（Code Generation）までの5ステージは、いきなりコードを書くのではなく、設計判断を段階的に文書化してからコード生成に到達する流れになっています。これら5ステージはいずれも
for_each: unit-of-workを宣言するper-Unitステージで、Unitごとに実行されます。| # | ステージ | 何を明示化するか |
|---|---|---|
| 3.1 | Functional Design | API契約、データモデル、コンポーネント間のインタフェース |
| 3.2 | NFR Requirements | パフォーマンス、可用性、セキュリティの具体的な基準値 |
| 3.3 | NFR Design | 非機能要件を満たすための設計手段（キャッシュ、レプリカ、暗号化など） |
| 3.4 | Infrastructure Design | CDK/CloudFormation構成、ネットワーク設計、IAMポリシー |
| 3.5 | Code Generation | Functional DesignからInfrastructure Designまでの成果物を入力として、実装コードを生成 |
仕組み: 2つのwalk order（Stage-majorとUnit-major）
これら5ステージを複数Unitに対してどの順序で回すかについて、2つの戦略（walk order）があります。walk orderは
bolt-plan.mdとは別の軸である点に注意してください。
Unit-major（オプトイン）: 1つのUnitに対してFunctional DesignからCode Generationまでを通してから、次のUnitに移ります。状態ファイルに
Construction Iteration: unit-majorを宣言することで有効になります。
| 観点 | Stage-major | Unit-major |
|---|---|---|
| 並列化との相性 | 高い。Swarmが使える | 低い。Swarmは使えない |
| 最初の動くコードが得られるタイミング | 遅い。全Unitの設計が終わってから | 早い。最初のUnit完了時点で |
| 適したケース | Unitが多く並列効果を得たい場面 | Unit少数で段階的に確認したい場面 |
補足として、Stage-majorのデフォルトでは、承認はステージ単位のゲートで行われます（全Unitがそのステージを終えた後に1回）。Unit-majorはSwarmを抑制する代わりに、per-stageのゲートカスケードを保持します。
5. Swarm: 並列ワーカーによるコード生成
同時に走れるUnit（runtime batch）が複数ある場合、物理的に並列でコード生成を走らせる仕組みが必要です。それがSwarmです。
課題: 並列に生成すると同じファイルへの書き込みが衝突する
2つのワーカーが同時にコードを生成するとき、共有ファイル（設定ファイル、エントリポイントなど）への同時書き込みが発生し得ます。また、AIが「テスト通りました」と報告しても、実際には通っていないケースがあります。
解決: ワーカーごとに独立した作業空間を与え、収束を独立に検証する
Swarmは2つの仕組みでこれを解決しています。
- git worktreeによる分離: 各ワーカーに独立した作業ツリー（
bolt-<slug>ブランチ）を与え、ファイル衝突を構造的に排除する。このworktreeはgit分離の機構であって、Boltそのものでもruntime batchでもありません - Referee（審判）による再検証: ワーカーの自己申告を信用せず、独立したチェックで収束を判定する
仕組み: prepare → 並列実行 → finalize の3段構成
Swarmの審判（
aidlc-swarm.ts）は3つのサブコマンドで動作します。| サブコマンド | タイミング | 役割 |
|---|---|---|
prepare | バッチ開始時 | 各Unitにgit worktreeを作成し、独立した作業空間を提供する（自律Code Generationでは、各Unitの承認済み計画とTesting Contractを検証してからfork） |
check | ループ中 | プロジェクト固有のビルド/テストコマンドを実行し、収束を助言する |
finalize | 全Unit完了時 | 全Unitに対してチェックコマンドを再実行し、通過したものだけをmainにマージする |
finalizeの再検証が特に重要です。ワーカーが「収束した」と報告しても、finalizeは改めてチェックコマンドを実行します。テストを通過したUnitだけがmainブランチにマージされる。この仕組みにより、AIの自己申告に依存しない品質担保が実現しています。実行サイクルを図にします。
Swarmが動作するのはStage-majorモードの場合のみです。物理的な実行方式は環境変数
AIDLC_USE_SWARMで切り替わりますが、どの方式でも同じ収束チェックロジックが適用されます。6. ステージ 3.6 Build and Test 〜3.7 CI Pipeline : 全体で1回のステージ
すべてのUnit（および計画上の全Bolt）が完了した後に実行されるステージを見ていきましょう。
課題: Unit単位のテストだけでは統合時の問題を検出できない
各Unitが個別にテストを通過していても、それらを組み合わせたときに初めて顕在化する問題があります。インタフェースの型不整合、環境変数の競合、ポート番号の衝突などです。
解決: 全Unitの統合後に、プロジェクト全体で1回だけビルド・テスト・CI構成を実行する
ステージ3.6（Build and Test）と3.7（CI Pipeline）は、全Unitのコードがマージされた状態で1回だけ走ります（per-Bolt/per-Unitではありません）。
| # | ステージ | リードエージェント | 目的 |
|---|---|---|---|
| 3.6 | Build and Test | Quality | 全体ビルド、統合テスト、カバレッジ計測 |
| 3.7 | CI Pipeline | Pipeline Deploy | CI/CD構成の生成と検証 |
仕組み: once-at-endフラグによる実行制御
エンジンはステージ定義の
execution: once-at-endフラグを読み取り、すべての作業が完了した後にのみこれらのステージを開始します。3.6ではUnit単位のテストに加えて統合テストが走り、3.6のgateを通過して初めて3.7のCI Pipeline構成に進みます。3.7が完了するとConstruction phase全体が完了し、Operation phase へ移行します。
7. Walking Skeleton
Construction phaseの実行フロー全体を制御する特別なメカニズムを見ていきます。
課題: 残りの作業を自信を持って並列実行する根拠がない
多数のUnitを一斉に走らせたとして、そもそもアーキテクチャの基盤（データベース接続、認証フロー、デプロイパイプライン）が正しく動く保証がない状態では、全Unitが同じ理由で失敗するリスクがあります。
解決: 最初のスライスで全レイヤーを薄く縦断し、アーキテクチャの健全性を検証してから並列化する
Walking Skeletonとは、アーキテクチャの全レイヤーを薄く縦断する最小限のEnd-to-End実装です。計画上の最初のBolt（
bolt-plan.mdが示す最初のデリバリスライス）がこの役割を担い、これが通れば残りの作業は安心して骨格に肉付けしていく形で進められます。ただしデフォルトのstage-major walkでは、
bolt-plan.mdの最初のBoltは**advisory（助言的）**です。実際に人間の承認を求めるゲートは、最初のin-scope Construction EXECUTEステージに置かれます。仕組み: スコープ連動 + Ladder prompt + 自律モード
Walking Skeletonの動作は3つの仕組みで制御されます。
スコープ連動: Walking Skeletonが有効になるのは、スコープ定義で
skeleton: onが宣言されているグリーンフィールド系スコープの場合です（mvp、enterprise、feature、poc、classic、workshop、infra）。bugfix、refactor、security-patchのような増分スコープでは、既存のコードベースが骨格の役割を果たすため省略されます。スタンスはorg.md → team.md → project.mdの順で解決されます（最も具体的な非空の記述が勝ちます）。承認ゲート: 最初のConstruction EXECUTEステージのゲートは常に人間の承認を必要とします。自律モードの設定にかかわらず、ここは必ずゲートが開きます。
Ladder prompt（自律モードの選択）: 最初のConstructionゲートが承認された直後に1回だけ提示されるプロンプトです。
「残りをどう進めますか？」* Continue autonomously: 承認ゲートなしで自動進行* Gate every remaining stage: 残りのConstructionステージごとに承認ゲートを設ける
この選択は状態ファイルに
Construction Autonomy Modeとして永続化されます。重要な点として、自律モードであっても失敗時は必ず停止します。自律モードが省略するのは成功時の承認ゲートだけであり、エラーが発生した場合は即座に人間に制御が戻ります。実行フロー全体を図にします。
8. 監査イベント: BoltイベントとSwarmイベント
Construction phaseはaudit logに構造化イベントを記録します。ここでは、それらのイベントの位置づけを整理します。
| イベント | いつ発行されるか |
|---|---|
BOLT_STARTED / BOLT_COMPLETED | Swarm経路上のper-Unit/worktreeイベント。自律的な並列実行の中で、各Unit/worktreeの開始・完了を記録する |
BOLT_FAILED | 同じくSwarm経路で、Unit/worktreeの失敗を記録する |
SWARM_COMPLETED | runtime batchを閉じるイベント。バッチ内の全Unitが収束または失敗で決着したときに発行される |
重要な点として、デフォルトのgated run（通常の承認ゲート付き実行）は、これらの
BOLT_*行を記録しません。BOLT_STARTED/BOLT_COMPLETEDが現れるのは自律Swarm経路上であり、名前は「Bolt」ですが実体はper-Unit/worktreeのイベントです。runtime batchの区切りはSWARM_COMPLETEDが担います。9. 実行パターンまとめ
最後に、ここまでの概念を「どう判断するか」の観点でまとめましょう。
各概念が解決する課題
| 概念 | 役割 | 仕組み |
|---|---|---|
| Unit | 全体を一塊で扱うと検証できない | 独立して設計・実装・テストできる最小単位に分解する。実行の起点 |
| Runtime batch | 独立したUnitを直列に走らせると時間がかかる | Unit依存DAGから並列実行可能なUnitを自動算出しグルーピングする |
| Bolt | 「どこまでを1つのまとまりとして届けるか」の計画がない | Delivery Planning（2.9）がデリバリスライス（DoD・確信仮説・オーナーシップ）をbolt-plan.mdに記録する。計画概念であり実行境界ではない |
| Walking Skeleton | 基盤が動く保証なく並列化するとリスクが大きい | 計画上の最初のBoltで全レイヤーを縦断し健全性を検証する。デフォルトwalkのゲートは最初のConstruction EXECUTEステージ |
| worktree | 並列生成でファイル衝突が起きる | Swarm実行時に各Unitへbolt-<slug>ブランチのgit worktreeを与える。Boltでもbatchでもない |
| Swarm | AIの自己申告が信頼できない | 審判による再検証（finalize）で品質を担保する |
| Stage-major / Unit-major | プロジェクト特性ごとに最適なwalk orderが異なる | 依存の深さとUnit数に応じてwalk orderを選択する（bolt-planとは別軸） |
判断フローチャート
実際にConstructionを構成するとき、以下の順序で判断が進みます。
- スコープはWalking Skeletonを要求するか？ →
skeleton: onのスコープなら最初のConstruction EXECUTEステージがWalking Skeletonのゲートになる - walk orderはどちらか？ → Unitが多く並列効果を得たいならStage-major、少数で段階確認ならUnit-major
- 自律モードかゲートモードか？ → 収束チェック（テストスイート）が信頼できるならAutonomous、目視確認したいならGated
- 並列度はどの程度か？ → Unit依存DAGが浅いほどruntime batchが大きくなり並列効果が高い
これらの判断は、Inception phaseの成果物に基づいて行われます。実行の駆動はUnit依存DAG（
unit-of-work-dependency.md, 2.7）が担い、bolt-plan.md（Delivery Planning, 2.9）はデリバリ計画を記録する—この2つの役割を分けて捉えることが、V2のConstructionを正しく理解する鍵です。Series: AI-DLC Workflow V2の解説 (31 articles)
- …
- 11AI-DLC Workflow V2のConstruction Phase: "設計を動くコードにする"構造化された実行 This article
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article