【ITニュース解説】From Epic to Merge: An End-to-End Workflow for Software Development with AI Agents

現在のソフトウェア開発において、AIエージェントは個別のコーディングタスクをこなす能力を著しく向上させている。適切な情報とコンテキストが与えられれば、エージェントは既存のコードを分析し、ファイルを変更し、必要なテストを作成して、実際に動作するコードを生成できるまでになった。しかし、これは「部分的な」能力に過ぎないのが現状である。

より大きな課題は、複数の関連タスクで構成される「機能全体（Epic）」を実装する際に発生する。これらのタスクの中には並行して実行できるものもあれば、他のタスクの完了に依存するものもある。また、アーキテクチャ上の重要な決定が必要なタスクや、AIによる自律的な変更が許されない機密性の高い領域に触れるタスクも存在する。このような状況では、「AIエージェントがコードを書けるか？」というシンプルな問いだけでは不十分であり、「ソフトウェア開発の目標を、AIエージェントが安全に実行し、検証し、レビューし、最終的に統合できる作業単位にどのように変換するか？」という問いがより重要になる。

この課題を解決するため、本稿ではAIエージェントを活用したエンドツーエンドのソフトウェア開発ワークフローを提案する。このワークフローは、人間の介入を最小限に抑えつつ、変更に伴うリスクに対して必要な制御を維持することを目指している。ワークフローの基本的な流れは、まず「Epic（開発の目的と制約）」を定義することから始まる。次に、このEpicを構成する「タスクの依存関係グラフ」が作成される。個々のタスクは、「Planner（計画立案者）」「Builder（構築者）」「Reviewer（評価者）」という役割を持つAIエージェントによって順に処理される。最終的に、これらのタスクの成果物は「Epic統合プルリクエスト」としてまとめられ、CI（継続的インテグレーション）による検証を経て、最終的に「人間の承認」を得て「main」ブランチにマージされる。ここで重要なのは個々のツールの選択ではなく、この一連のワークフローそのものである。

「Epic」は、AIエージェントがシステムとして何を達成すべきかについて、共通の認識を持つための最上位の情報源となる。これには、目的、問題の背景、開発の範囲と除外される事項、要件、具体的なタスクやユーザーストーリー、受け入れ基準、依存関係とリスク、そして成功を測る指標が含まれるべきだ。Epicはあくまで「意図、要件、制約の中央情報源」として理解されるべきであり、システムの「絶対的な真実」を全て含むものではない。実際の技術的な実装の詳細や現実は、既存のAPI仕様、データベーススキーマ、アーキテクチャ上の決定、インフラストラクチャの構成、テストコードといったリポジトリ内の情報に存在する。この区別は、AIエージェントが適切な意思決定を行う上で重要となる。例えば、「決済処理にリトライ機能を追加する」というタスクがあった場合、エージェントは「どのような失敗がリトライの対象か？」「何回までリトライを許可するか？」「決済の重複を防ぐ冪等性（べきとうせい）はどう確保するか？」といった具体的な質問を投げかけるだろう。Epicは、これらの質問に答えるためのプロダクトとアーキテクチャの境界線を提供し、個々の課題に全ての詳細なコンテキストを重複して記述する手間を省く役割を果たす。

AIエージェントを使った開発ワークフローでよくある間違いの一つは、非常に大きな目的を直接コーディングエージェントに与えてしまうことである。例えば、「課金機能のEpic全体を実装せよ」といった指示では、エージェントは同時にシステムのアーキテクチャを発見し、要件を解釈し、設計上の決定を下し、複数の関連領域のコードを変更し、異なる機能間の依存関係を矛盾なく保ち、実装の動作を検証し、タスクのスコープ内外を理解しなければならない。これでは、エージェントが首尾一貫した意思決定を多数こなす必要があり、その実行過程を人間が追跡し、理解するのが非常に困難になる。問題は単にAIモデルが扱える情報量（コンテキストウィンドウサイズ）の限界だけでなく、実行全体を通じて矛盾なく維持されるべき意思決定の複雑さにある。より効果的なワークフローは、個々の実行における複雑さを軽減することを目指す。

では、タスクはどの程度細分化されれば適切なのか。一つの有用な基準は、「一貫性のある成果を生み出し、他のタスクに依存せず独立して実装および検証が可能で、かつその変更が人間にとって理解しやすく、テスト可能で、必要に応じて簡単に元に戻せるプルリクエストを作成できる」程度の粒度である。したがって、タスクの規模は主にコードの行数や変更されるファイル数で測られるべきではない。より重要な特性は「凝集度」である。例えば、APIに新しいフィールドを追加するタスクは、データベースのスキーマ、ドメインモデル、サービス層、APIエンドポイント、そしてテストといった複数のコード層に影響を与える可能性がある。しかし、これらの変更が全て「新しいAPIフィールドの追加」という一つの垂直方向の機能を実現するためのものであれば、それは一つのまとまりのある、凝集性の高いタスクと見なせる。対照的に、認証機能の変更、課金ルールの変更、イベント処理の変更、インフラストラクチャの変更といった、複数の異なる機能を単一のタスクにまとめることは、たとえ変更されるファイル数が少なくても広すぎるタスクとなる可能性がある。したがって、「そのタスクは一つの明確な結果を持つか？」「一つのまとまった機能を実現するか？」「独立して検証可能か？」「主要なアーキテクチャ上の決定はすでに解決済みか？」「変更差分（diff）は一つの論理的な単位としてレビューできるか？」「その変更は他の無関係な作業を巻き添えにせずに元に戻せるか？」といった問いが重要になる。特に最後の問い、つまり「レビュアーがこの差分を単一の論理的な変更として理解し、承認できるか？」という問いに対する答えが「いいえ」であれば、そのタスクはさらに細かく分割する必要があるだろう。

さらに、不確実性のある「調査」作業と、確実な「実装」作業を混同することは特に危険だ。例えば、「非同期処理アーキテクチャを選択し、それを実装する」というタスクには、「どのようなアーキテクチャを採用すべきか決定する」という根本的に異なる種類の作業と、「その決定されたアーキテクチャを実際にコードとして実装する」という作業が含まれている。これを、「非同期処理の代替案を調査するタスク」「採用するアーキテクチャの決定を記録するタスク」「イベントプロデューサーを実装するタスク」「イベントコンシューマーを実装するタスク」のように分解することで、不確実性を早期に解消し、AIエージェントの行動をより厳密に制御できるようになる。

タスクがAIエージェント（Builder）による実装フェーズに到達する前に、そのタスクが実際に実装可能な状態であるかを確認するための「準備チェック」が重要となる。これは、例えば「明確に定義された成果が一つ存在するか？」「スコープと除外事項が明確か？」「受け入れ基準は客観的に検証可能か？」「全ての依存関係が宣言されているか？」「主要なアーキテクチャ上の決定はすでに解決済みか？」「変更は一貫性のある機能を表しているか？」「客観的な検証戦略が存在するか？」「独立したプルリクエストを作成できるか？」「関連しない作業を削除せずに変更を元に戻せるか？」といったチェックリストとして用いられる。これらの項目は厳密な数値ルールである必要はなく、コードのサイズよりも、タスクの凝集度、独立性、検証可能性といった特性がより重要である。

複数のタスクが並行して実行される場合、それぞれのタスクが独立したファイルシステム環境を持つことが不可欠となる。一つの簡単な戦略として、Epicの下に各タスク専用のディレクトリを作成し、それぞれに独立したGitブランチ、Gitワークツリー、またはコンテナ環境を与える方法がある。これにより、複数のAIエージェントが同じ作業ディレクトリを直接変更することによるファイルシステムの競合を防げる。しかし、これは異なるエージェントが同じAPIやデータモデルといった共有リソースを独立して変更することで生じる「意味的な競合」を排除するものではない。したがって、AIエージェントを統括するオーケストレーターは、タスク間の依存関係と、変更を統合する適切な順序を理解する必要がある。Epicは、単なるフラットなタスクリストとして扱うのではなく、「依存関係グラフ」として表現するのがより適切である。例えば、「データベーススキーマの追加」タスクが「イベントプロデューサーの作成」タスクと「APIの作成」タスクの前提となり、それらがさらに「イベントコンシューマーの作成」タスクの前提となり、最終的に全てが「統合検証」につながる、といった形である。タスクには「このタスクは○○タスクの完了にブロックされている」といったメタデータを明示的に持たせることで、オーケストレーターは独立したタスクノードを並行して実行し、依存関係のあるノードはそれが完了するまで待機できる。これは、複数のエージェントにEpic全体を任せて、彼らが自力で正しい作業順序を見つけることを期待するよりもはるかに安全で効率的なアプローチである。

このワークフローでは、「Planner」「Builder」「Reviewer」という三つの主要なAIエージェントの役割が明確に分担される。

Plannerは、実装に入る前に調査活動を行う責任を持つ。これには、関連するコードベースを検査し、影響を受ける可能性のあるコンポーネント、存在する依存関係、潜在的なリスクを特定することが含まれる。さらに、実装のアプローチを提案し、必要な検証ステップを定義し、現在のタスクがさらに分割されるべきかどうかを判断する。Plannerはこの段階で実際のプロダクションファイルを変更せず、その出力はコードの実装ではなく、詳細な実行計画である。

Builderは、Plannerによって承認されたタスクを実際に実行する役割を担う。その責任範囲は意図的に狭く、計画された変更の実装、既存のテストの更新または新しいテストの作成、必要な検証コマンドの実行、変更のコミット、そしてプルリクエストの作成または更新を行う。もしBuilderが実装中に、計画にはなかった重大なアーキテクチャ上の問題を発見した場合、勝手にスコープを拡大したり、受け入れ基準を再定義したりするのではなく、その発見をオーケストレーターにエスカレートすることが正しい行動となる。

Reviewerは、Builderによって行われた変更の結果を独立した立場で評価する。これは、実際のコードの差分、タスクの受け入れ基準、実行されたテストとその結果、アーキテクチャ上の制約、そしてシステム全体に対する潜在的な回帰（リグレッション）を検査することを含む。レビューは、Builderが実装した内容の説明だけに基づいて行われるべきではなく、タスクに設定された本来の要件と期待される動作に基づいて行われるべきである。この区別は重要で、そうでなければBuilderとReviewerが同じ誤った仮定を共有してしまう可能性がある。Reviewerは、「PaymentDeclinedErrorもリトライされている」といった具体的な調査結果と、それがどの受け入れ基準に違反しているかを明示的に伝える。このような客観的な調査結果は、問題が発見された際に自動的に修正ループを開始することを可能にする。

AIエージェント間の協調方法には、大きく分けて二つのパターンがある。「内部オーケストレーション」では、一つの主要なエージェントが、自身の内部にあるマルチエージェントの実行環境を介して、子エージェント（例えばPlanner、Builder、Reviewer）に作業を委譲する。これは、委譲プロセスが主要エージェントの推論プロセスと密接に結びついている場合に有効だ。一方、「外部オーケストレーション」では、独立したプロセスが個々のエージェントの実行を制御する。例えば、オーケストレーターが個別のエージェントプロセスを立ち上げ、それぞれが異なるタスクを並行して実行する。エージェント間の通信は、構造化された出力、ファイル、Git、APIといった永続的なメカニズムを通じて行われる。本稿で説明するアーキテクチャは、確実なワークフロー、独立した作業環境、明示的な並行処理、リトライ処理、タイムアウト設定、タスクキュー、永続的な実行状態、そして特定のプロバイダーに依存しないエージェント運用が必要な場合に特に有用な外部オーケストレーションを推奨している。

Epicにはシステム全体の広範な情報が含まれているが、全てのAIエージェントにEpic全体、過去の全ての会話履歴、全ての実装ログを与える必要はない。その代わりに、オーケストレーターは「タスクコンテキストパッケージ」を作成し、そのタスクの実行に必要な最小限かつ十分な情報のみを含めるべきである。これには、Epicの概要、タスクの具体的な説明、受け入れ基準、関連するアーキテクチャ上の決定、すでに完了した依存タスクの情報、関連するコードファイル、リポジトリに対する特別な指示、検証コマンド、リスク制約などが含まれる。AIモデルが扱えるコンテキストウィンドウが長くなったとしても、それを全て埋めることが必ずしも最善ではない。過剰なコンテキストは、古い情報、互いに矛盾する指示、無関係な実装の詳細、時代遅れのアーキテクチャ上の仮定、あるいは競合する目標などを持ち込んでしまい、エージェントの意思決定を混乱させる可能性があるからだ。したがって、コンテキストの選定と整理（コンテキストエンジニアリング）もオーケストレーションの重要な一部となる。重要な問いは「モデルがどれだけの情報を受け取れるか？」ではなく、「この特定の意思決定を正しく行うために必要な最小限かつ十分なコンテキストは何か？」である。

AIエージェントの自律性を高め、人間の介入を減らすことは、エージェントに無制限の許可を与えることを意味しない。ワークフローは、どの操作を自動的に実行しても安全であり、どの操作が人間の明示的な承認を必要とするかを明確に定義する必要がある。これは「リスクポリシー」として定義されるべきだ。例えば、アプリケーションコードの編集、テストの追加や更新、テストの実行、リンターや静的解析の実行、変更のコミット、プルリクエストの作成、そしてReviewerが要求した承認済みの範囲内での修正適用などは、「自律的」な操作として分類できる。一方で、依存関係の更新、データベースの非破壊的なスキーマ変更、API契約の変更、共有設定の変更、複数のドメインやサービスに影響する変更などは、「追加検証付きの自律」として、特定の検証ルールが成功した場合にのみ自動実行を許可する。さらに、本番環境へのデプロイ、データベースの破壊的な移行、機密情報へのアクセスや変更、インフラストラクチャの変更、認証や認可に関する変更、課金処理、不可逆なデータ変換などは、常に「人間の承認が必要」とすべきだ。これらの分類はシステムや組織のリスク許容度によって異なるため、普遍的なルールではなく、プロジェクトごとのリスクポリシーとして定義することが肝要となる。

これらの要素を組み合わせることで、完全な実装サイクルが実現する。まず、人間またはプロダクト管理プロセスがEpicを定義し、目的、問題、スコープ、要件などを明確にする。次に、計画プロセスがEpicを構成するタスクに分解し、それぞれのタスクが凝集性、独立性、テスト可能性、可逆性、アーキテクチャ上の不確実性といった観点からチェックされる。もし大きな設計上の不確実性が存在する場合は、実装タスクの前に専用の調査タスクが作成される。タスク間の依存関係は明示的に宣言され、オーケストレーターはこれにより安全な並行処理の機会を特定できる。

Epic全体の作業を管理するための統合ブランチが、現在のターゲットブランチ（通常はmain）から作成される。個々のタスクブランチは、このEpic統合ブランチから派生するか、適切な統合状態から作成される。オーケストレーターは、次に実行すべきタスクを選定し、Epicの概要、タスクの説明、受け入れ基準、関連するアーキテクチャ上の決定、完了した依存関係、関連ファイル、リポジトリへの指示、検証コマンド、リスク制約など、そのタスクに必要な情報のみを含むコンテキストパッケージを作成し、Plannerに渡す。

Plannerは、このコンテキストパッケージとリポジトリを検査し、実行計画を生成する。この計画は、タスクが「READY（実装可能）」、「NEEDS_SPLIT（分割が必要）」、「BLOCKED_BY_ARCHITECTURE（アーキテクチャ上の決定待ち）」、「BLOCKED_BY_DEPENDENCY（依存タスク待ち）」といった状態のいずれであるかを示す。Plannerの判断が「READY」であるタスクのみが自動的に次のステップに進む。この段階は、プロジェクトの計画と実際のコード生成の間の重要な境界線として機能する。

タスクが「READY」と判断されたら、オーケストレーターは独立したBuilder環境を構築する。これには、専用のタスクブランチ、独立したGitワークツリーまたはコンテナ、そしてタスク固有のコンテキストパッケージが含まれる。これにより、複数のBuilderが並行して実行されても、ファイルシステムの競合を避けることができる。

Builderは、タスクコンテキストとPlannerによって生成された実行計画、そしてリポジトリへの指示を受け取り、計画された変更を実装し、テストを更新または作成し、必要な検証を実行する。その結果は、成功ステータス、コミットハッシュ、単体テスト、統合テスト、リンター、型チェックなどの検証結果、変更されたファイルリスト、特記事項といった構造化された情報として出力される。オーケストレーターは、テストが合格したかどうかをエッセイのように長文を解析する必要なく、構造化されたデータから判断できる。

Builderが変更を完了したら、個々のタスク用のプルリクエストが作成され、それがEpic統合ブランチをターゲットとする。このタスクPRは、単独でレビュー可能であるべきだ。Builderのローカル環境での検証とは別に、CI（継続的インテグレーション）プロセスが再度実行され、二重の独立した検証層を提供する。

次に、Reviewerが介入する。Reviewerは、タスクの要件、受け入れ基準、コード差分、テスト結果、そして関連するアーキテクチャ上の制約を受け取り、それを基に独立して評価を行う。その結果は、ブロックする問題、ファイル名、行番号、問題の理由、違反した基準といった具体的な構造化された所見として返される。

もしReviewerが「ブロックする」と判断する問題を発見した場合、修正ループが開始される。Reviewerからの所見に基づいてBuilderが変更を加え、再度検証を行い、Reviewerが再評価する。このループは、あらかじめ定義された試行回数内で繰り返される。もし一定回数失敗した場合、そのタスクは人間へのエスカレーションが必要と判断される。繰り返しの失敗は、タスクの定義が不適切であるか、分解が不十分であるか、または未解決のアーキテクチャ上の問題が隠されていることを示す有用な情報となる。

Builderによる検証、CIによる検証、そしてReviewerによる承認が全て完了したら、プロジェクトの自律性ポリシーに従ってタスクはEpic統合ブランチにマージされる。これにより、依存関係グラフ内の下流タスクのブロックが解除され、オーケストレーターは新たに実行可能になった作業をスケジュールする。

全ての個々のタスクが独立して合格したとしても、Epic全体が意図通りに機能することは証明されない。全ての必要なタスクがEpic統合ブランチにマージされたら、ワークフローはより広範なEpicレベルの検証を実行する。これには、全体のテストスイート、統合テスト、エンドツーエンドテスト、契約テスト、データベース移行チェック、セキュリティチェック、パフォーマンスチェックなどが含まれる。これらのテストは、個々のタスクレベルの検証では検出できない、タスク間の相互作用による問題を捕捉する。例えば、二つの個別に正しいタスクが、互いに互換性のない仮定で実装されている場合などである。

最終的なReviewerは、個々のタスクではなく、統合された結果を元のEpic全体として定義された受け入れ基準に対して評価する。この段階での問いは、「タスク7を正しく実装したか？」ではなく、「システムはEpicで定義された最終的な成果と目的を満たしているか？」に変わる。全てのタスクが成功裏に完了したとしても、Epicの分解自体が不完全であった場合、意図した最終的な製品の動作が達成されない可能性があるため、この区別は極めて重要である。

最終的な統合結果がEpicの基準を全て満たしていると判断された場合、ワークフローはEpic全体のプルリクエストを生成し、これをmainブランチにマージするプロセスに入る。この段階が、人間による最終承認の最も適切なゲートとなる。人間はもはや、個々の小さなコード変更を手動で実装したりレビューしたりする必要はない。その代わりに、人間の注意と専門知識は、要件の策定、アーキテクチャ設計、リスク評価、例外処理、そして最終的な統合といった、最も高い価値を持つ意思決定に集中できるようになる。これは、「人間が開発プロセスに参加する（human-in-the-loop）」という概念の、より現実的な解釈と言える。

ワークフローの全てのステージで同じAIモデルを使用する必要はない。異なる役割には異なる計算要件がある。PlannerやReviewerは、アーキテクチャや依存関係を深く理解し、微妙な不整合を特定する必要があるため、より高度な推論能力を持つモデルの恩恵を受けるかもしれない。一方で、非常に制約された変更を実行するBuilderは、そこまで高度なモデルを必要としない場合もある。このような役割に応じたモデルの選択は、OpenCode、Codex、Claudeといった様々なコーディングエージェントランタイムを、根本的なワークフローアーキテクチャを変更せずに活用できる可能性も生み出す。AIモデルは、ワークフローそのものではなく、その「実行コンポーネント」の一つとなるのである。

このプロセスが明確に構造化されると、そのパフォーマンスを測定できるようになる。タスクごとのトークン消費量、エージェントの役割ごとのトークン消費量、タスクごとの実行時間、Epic全体の実行時間、リトライ回数、失敗したBuilder試行回数、Reviewerによる指摘、CIの失敗、人間介入なしで完了したタスク数、人間へのエスカレーション回数、プルリクエストごとやEpicごとのコストなどの指標が有用となる。これらの測定値は、単にトークン使用量を最小化するためだけでなく、「Plannerを追加することで実装の失敗が減るか？」「より強力なReviewerを導入することで統合時の欠陥が減るか？」「特定の種類のタスクが常に人間へのエスカレーションを必要とするか？」「タスクのサイズがどの程度になると自律的な完了が不安定になるか？」「並行実行は実際に開発期間を短縮しているか？」といった、より深い問いに答えるのに役立つ。この段階で、AIエージェントやモデルに関する意思決定は、直感ではなく、具体的なワークフローのパフォーマンスデータに基づいて行えるようになる。

上記全てが明示的になると、オーケストレーションの問題は驚くほど機械的になる。タスクは、PENDING（保留中）からREADY（準備完了）、PLANNING（計画中）、BUILDING（構築中）、VALIDATING（検証中）、REVIEWING（レビュー中）といった状態を遷移し、Reviewerによって「変更要求」が出されればBUILDINGに戻り、「ブロック」されればESCALATED（人間へエスカレーション）となり、「承認」されればMERGED（マージ済み）となる。同様に、Epic自体もPLANNINGからEXECUTING、INTEGRATING、VALIDATING、AWAITING_APPROVAL（承認待ち）、そしてCOMPLETED（完了）という独自のライフサイクルを持つ。この段階で、AIを活用したソフトウェア開発は、単なるチャットインターフェースというよりも、より複雑な「分散型ソフトウェアデリバリーシステム」のように見え始める。そして、これがより有用な抽象化の捉え方であると言えるだろう。

AIを活用したソフトウェア開発において最も興味深い問題は、もはやコード生成そのものではなく、いかにそのプロセス全体を「オーケストレーション」するかである。自律的な開発ワークフローは、「エージェントは何に取り組むべきか？」「どのようなコンテキスト（情報）を受け取るべきか？」「どの作業を並行して行えるか？」「どのような意思決定がすでに行われているか？」「実装はどのように検証されるべきか？」「誰がその結果をレビューするのか？」「Reviewerが指摘した場合どう対応するか？」「どの行動が自動的に行えるか？」「人間の承認はどこで必要か？」「独立した変更はどのようにして最終的な一つの機能として統合されるのか？」といった多くの問いに答えなければならない。より優れたAIモデルが登場すれば、個々のタスクの実行能力は向上するだろうが、これらのオーケストレーションに関する問いに答える必要性がなくなるわけではない。堅牢なAIエージェント開発ワークフローは、「非常に強力なモデルがプロジェクト全体を受け取り、単に全てを『解決してくれる』」という仮定に基づいて設計されるべきではない。むしろ、システムはAIによる実行が始まる前に、全ての曖昧さを可能な限り減らすように設計されるべきだ。

これは具体的に、「明確な意図（Epic）」、「一貫性のあるタスク分割」、「明示的なタスク依存関係」、「タスクに必要最小限の関連コンテキスト」、「隔離された実行環境」、「客観的な検証プロセス」、「独立したレビュー」、「リスクに基づいた自律性の定義」、「制御された統合プロセス」を意味する。このワークフローの究極的な目標は、人間をソフトウェアエンジニアリングの現場から完全に排除することではない。そうではなく、人間の貴重な時間と知恵を、ルーチンな実装の監督から解放し、判断、製品コンテキストの理解、アーキテクチャの設計、リスク評価といった、人間固有の能力が本当に重要となる意思決定へと集中させることにある。これらの境界が明確に定義されれば、AIエージェントは単なる孤立したコーディングアシスタントではなく、現代のソフトウェアデリバリーパイプラインにおける不可欠な構成要素となるだろう。