生成AIをソフトウェア開発へ導入するとき、最初はコード補完や質問応答から始まる。
しかしAI Agentが実用的になるにつれて、問題は徐々に、
AIにコードを書かせられるか
ではなく、
AIに何を、どこまで、どの契約に従って実装させるか
へ移っていく。
さらに進むと、
AI Agentをどの状態で実行し、どの検証を通過したら次へ進めるか
という、開発基盤そのものの設計が必要になる。
この記事ではAI Driven Developmentの進化を4段階に分け、特にStage 2以降で必要になる、
- Agent Brief
- Handler
- Agent Runner
- CI
- State Machine
- Verification
- Policy Gate
を中心に、実装構造として整理する。
なお、各Stageで開発スタイルとエンジニアの雇用がどう変わるかは、前の記事「AI Driven Development はどこまで進むのか」で扱った。この記事はその実装側の話であり、雇用の議論は繰り返さない。
Stage 1: AI-Assisted Development
Stage 1では、人間が開発主体であり、AIは補助ツールである。
Developer
↓
Design
↓
Implementation
↓
AI Assistance
↓
Test
↓
Review
AIは例えば、
- コード補完
- エラー分析
- テストコード生成
- リファクタリング提案
- ドキュメント生成
を行う。
この段階では、既存のSDLC自体を大きく変更する必要はない。
AIはIDEやChatの中に存在するだけであり、開発状態を管理する主体ではない。
Stage 2: Spec-Driven Agentic Development
Stage 2では、AI Agentが実装主体になる。
ただし、
「この機能を作って」
という曖昧な指示だけで実行させるのではない。
まず、人間側で実装可能な作業単位まで仕様を具体化する。
典型的には、
Roadmap
↓
Ticket
↓
Agent Brief
↓
Handler
↓
Agent Runner
↓
CI
↓
Human Review
という構造になる。
ここで重要なのは、Roadmap・Ticket・Agent Briefを同じ文書として扱わないことである。
Roadmapの責務
Roadmapは、
何を、どの順序で、どの技術責務として成立させるか
を定義する。
例えば、
Phase 1
Agent Briefの契約を定義する
Phase 2
Briefを検証するHandlerを実装する
Phase 3
Ready for Agent状態のTicketをRunnerが取得できるようにする
Phase 4
Agent実行結果をCIと連携する
といった粒度になる。
Roadmapには、個別ファイルやprivate classの詳細までは書かない。
Ticketの責務
Ticketは、
今回何を実装・変更・検証するか
を定義する。
例えばHandlerの実装Ticketなら、
目的:
Agent Briefを実行可能状態へ遷移させる前に、
必須契約を検証できるようにする
対象:
- Brief Validation
- status transition
- validation failure handling
対象外:
- Agent execution
- CI execution
- merge automation
といった形になる。
つまりTicketは、実装者が単体で見ても、
- なぜ必要か
- 何を変更するか
- 何を変更しないか
- どうなれば完了か
を判断できる単位にする。
Agent Briefの責務
Agent BriefはTicketの要約ではない。
Agent Briefは、
AI Agentが追加の要件設計なしに実装開始できる実行契約
である。
例えば次のような内容になる。
Goal
Ticketで定義されたBrief Validationを実装する。
In Scope
- Agent Briefの必須項目検証
- validation resultの生成
- validation成功時の状態遷移
- validation失敗時の理由保持
Out of Scope
- Agent Runnerの起動
- CI実行
- Pull Request作成
- public API変更
Contract Constraints
- 既存のstatus transition contractを変更しない
- validation失敗時にReady for Agentへ遷移させない
- public schemaを変更する場合は別Ticketとする
Acceptance Criteria
- 必須項目欠落を検出できる
- invalidなBriefはReady for Agentにならない
- validなBriefだけが次状態へ遷移できる
Verification
- 既存テストが成功する
- validation failureの回帰テストを追加する
- state transitionの回帰を確認する
この段階になると、Agentには、
何を作るべきか
を考えさせない。
考えさせるのは、
この契約をどう実装するか
だけにする。
ここからは、このStage 2の構造を実運用するために必要になる部品を、Briefの状態管理・Handler・Agent Runner・CIの順に見ていく。
Briefの状態管理
Agent Briefを導入する場合、単なるMarkdownファイルとして管理するだけでは不十分になる。
最低限、次のような状態を持たせる必要がある。
Brief Draft
↓
In Review
↓
Brief Ready
↓
Validating
↓
Ready for Agent
In Reviewは人間がBriefをレビューしている状態、ValidatingはHandlerが機械検証を行っている状態である。
ここでは特に、
Brief Ready
と、
Ready for Agent
を分離することが重要になる。
Brief Readyは、
人間によるレビューが完了し、Handler Validationを要求した状態
である。
Ready for Agentは、
Handler Validationが成功し、Agentが安全に取得可能になった状態
である。
つまり、
Human approval
≠
Machine validation
として扱う。
Handlerとは何か
Handlerは、Agentへ作業を渡す前の契約検証層である。
例えば次の責務を持つ。
Input
↓
Agent Brief
↓
Handler
├─ required field validation
├─ state validation
├─ contract validation
├─ permission validation
└─ execution eligibility check
↓
Ready for Agent
Handlerは実装Agentではない。
Handler自身がコードを書く必要もない。
役割は、
この作業をAgentへ渡してよいか
を判定することである。
Handlerで何を検証するか
例えば以下を検証対象とする。
Brief completeness
Execution state
Required approval
Scope definition
Forbidden changes
Verification contract
Repository eligibility
Execution ownership
機械判定可能な項目は、できるだけLLMへ渡さない。
例えば、
required field存在確認
status一致
ticket id形式
repository id存在確認
などは決定論的ロジックで処理する。
一方、
Acceptance Criteriaが曖昧すぎないか
ScopeとOut of Scopeが矛盾していないか
Contract Constraintsが不足していないか
のような項目は、必要に応じてAIによるsemantic validationを利用する。
つまりHandlerは、
Deterministic Validation
+
Semantic Validation
の組み合わせになる。
このsemantic validationを担うAIが、後述するValidation Agentである。Briefを書いた側(人間またはBrief Generator)とは別のcontextで検証させる。
Agent Runner
Ready for Agentになった作業を実際に取得して実行するのがAgent Runnerである。
概念的には、
Ready for Agent
↓
Agent Runner
↓
claim
↓
workspace preparation
↓
repository checkout
↓
Agent execution
↓
verification
↓
result reporting
となる。
Runnerで重要なのは、単にAgent CLIを起動することではない。
むしろ重要なのは、
実行ライフサイクルを管理すること
である。
Runnerの責務
例えばRunnerは以下を管理する。
- Ticket claim
- 同時実行制御
- Repository取得
- execution workspace分離
- AgentへのBrief供給
- timeout
- retry
- cancellation
- execution log
- result artifact
- failure classification
- state transition
ここで、
Agent
と、
Agent Runner
は分けて考える。
Agentは、
コードを書く知能
である。
Runnerは、
その知能を安全に動かす実行基盤
である。
Claimが必要になる理由
複数Agent Runnerが存在すると、同じTicketを同時取得する可能性がある。
そのため、
Ready for Agent
↓
claim
↓
Claimed
という排他制御が必要になる。
例えば、
Runner A
Runner B
Runner C
が同じTicketを取得しないように、
atomic claim
を成立させる必要がある。
この処理はLLMに判断させるべきではない。
通常のstate transitionとlockingの問題として扱う。
Runnerの状態遷移
一例として、次のようになる。
Ready for Agent
↓
Claimed
↓
Preparing
↓
Running
↓
Verifying
↓
Completed
失敗時は、
Running
↓
Failed
だけでは不十分である。
少なくとも、
Retryable Failure
Non-Retryable Failure
Human Review Required
Environment Failure
Contract Violation
などの分類が必要になる。
この分類によって、次の処理が変わる。
RetryをAgent任せにしない
例えばCIが失敗した場合、
失敗したので直してください
と無制限にAgentへ再実行させる設計は危険である。
Runner側で、
retry limit
timeout
failure type
state transition
を管理する必要がある。
例えば、
Attempt 1
↓
verification failure
↓
retry allowed
Attempt 2
↓
same failure
↓
retry allowed
Attempt 3
↓
same failure
↓
Human Review Required
とする。
つまり、
Agentの自律性
と、
実行回数の制御
は別問題である。
CIはAgentの補助ではなくVerification Layer
Stage 2以降では、CIの意味も少し変わる。
従来は、
Developer
↓
Push
↓
CI
だった。
Agentic Developmentでは、
Agent
↓
Implementation
↓
CI
↓
Machine Verification
↓
Agent / Human
になる。
ここでCIは、
Agentが正しく実装したと主張しているか
を見るのではなく、
実際に契約を満たしているか
を判定する。
CIでAIに任せないもの
例えば、
- unit test
- integration test
- lint
- typecheck
- build
- schema validation
- dependency policy
- static security scan
などは、可能な限り決定論的に処理する。
AI Reviewだけで、
問題なさそうです
と判定させてはいけない。
AIは、
CI結果の解釈
には使えるが、
CI結果そのもの
の代わりにはしない。
Verification Contract
Agent Briefには、Acceptance Criteriaだけでなく、
Verification
を持たせる。
例えば、
Acceptance Criteria
- invalid Briefを拒否できる
- valid BriefをReady for Agentへ遷移できる
に対して、
Verification
AC1:
invalid input testcaseでfailureを確認
AC2:
valid input testcaseでstate transitionを確認
という対応を持たせる。
理想的には、
Acceptance Criterion
↓
Verification
↓
Evidence
まで追跡できる。
Evidenceを残す
Agentが、
テストしました
と報告するだけでは不十分である。
例えば結果として、
Execution Result
Changed:
- implementation
- tests
Verification:
- unit test: pass
- integration test: pass
- lint: pass
Commit:
abc123
CI:
pipeline-456
のようなEvidenceを残す。
もちろん、実際のschemaはプロジェクトごとに異なる。
重要なのは、
完了判定に使った事実
を後から追跡できることである。
Gitとの境界
ここからは、これらの部品と既存ツールの境界をどこに置くかを整理する。
Agent Runnerは、Production branchへ直接変更するより、
Agent
↓
working branch
↓
commit
↓
push
↓
CI
↓
review
↓
merge
の方が扱いやすい。
Gitは、
Agentの作業結果を固定する境界
として使える。
これにより、
- diff
- rollback
- provenance
- review
- reproducibility
を持てる。
CIとの境界
CIはAgent Runner内部へ埋め込みすぎない方がよい。
Runnerの責務は、
CIを開始する
CI結果を取得する
結果を状態へ反映する
までとする。
CI内部の、
build
test
lint
scan
はCI側の責務として維持する。
これにより、
Agent Runner
と、
CI Platform
を独立して交換できる。
Agent RunnerとCI Runnerは別物
ここは混同しやすい。
Agent Runner
は、
AI Agentの実行環境
である。
CI Runner
は、
検証処理を実行する環境
である。
例えば、
Agent Runner
↓
Git Push
↓
CI Runner
という関係になる。
AI Agentが直接すべてのbuild環境を持つ必要はない。
RedmineをControl Planeにする場合
筆者はTicket管理にRedmineを使っているので、Redmineを上位のTask Control Planeとして使う場合を例に挙げる。GitHub IssuesやJiraでも構造は同じである。
Redmine
↓
Ticket status
↓
Agent Brief status
↓
Handler
↓
Runner
↓
Git
↓
CI
↓
Result
↓
Redmine
というループにできる。
ただし、Redmineのstatusだけですべての実行状態を表現する必要はない。
例えば、
Ticket State
Agent Execution State
CI State
Release State
は別々の責務として保持し、必要な状態だけRedmineへ反映する方が安全である。
Stage 2.5: Human Gateを残した自動化
Stage 2から3へ一気に移行する必要はない。
実運用では、Stage 2.5がかなり現実的である。
Ticket
↓
Brief Draft
↓
Human Review
↓
Handler Validation
↓
Agent Runner
↓
CI
↓
AI Review
↓
Human Merge
Stage 2との違いは、BriefをAIに下書きさせ、AI Reviewを挟む点にある。ただしBriefの承認とmergeは人間が行う。
この構成なら、
- Briefの下書き
- 実装
- 一次検証
- 修正
- レビュー補助
は自動化できる。
一方で、
- Brief承認
- architecture decision
- contract変更
- merge
- release
は人間に残せる。
Stage 3: Policy-Driven Agentic Development
Stage 3では、Briefの下書きをAIに任せるだけでなく、Roadmap・ADR・Policyといった上位ルールからBriefを生成し、人間の承認を段階的に外していく。
例えば、
Ticket
+
Roadmap
+
ADR
+
Repository Policy
+
Release Contract
↓
Brief Generator
↓
Agent Brief
という構造になる。
人間が毎回、
このAPIは変更禁止
この状態遷移は維持
このsecurity boundaryは変更禁止
と書かなくても済むようにする。
それらを上位Policyから継承する。
Policy Layer
例えば概念上、次のようなPolicyを持つ。
Repository Policy
public API:
explicit approval required
schema change:
explicit approval required
security boundary:
agent modification prohibited
private implementation:
agent discretion allowed
test modification:
allowed
release configuration:
restricted
ここで重要なのは、Policyを自然言語だけに依存させないことである。
機械的に判定可能な部分は、structured dataとして持つ。
Agent Brief生成
Stage 3では、
Ticket
から直接Agentを起動するのではなく、
Ticket
↓
Brief Generation
↓
Validation
↓
Agent Execution
とする。
この中間層が重要である。
Ticketには人間向けの背景説明が含まれる。
一方、Agent実行には、
- bounded scope
- required behavior
- immutable contract
- acceptance criteria
- verification requirements
が必要になる。
Brief Generatorは、これらを変換する役割を持つ。
Brief Generatorを信用しすぎない
Brief GeneratorもAIである以上、誤る。
したがって、
Generator
↓
Handler Validation
という分離を維持する。
Generator自身に、
自分が正しいか確認してください
とさせるだけでは弱い。
最低限、
Generation
Validation
Execution
を分離する。
Handlerの節で触れたsemantic validationは、ここではValidation Agentとして、Generatorとは別モデル・別contextで動かす。
Contextも制限する
AgentへRepository全体を毎回読み込ませるのも非効率である。
例えば、
Ticket
↓
Brief
↓
Relevant Files
↓
Relevant ADR
↓
Related Tests
だけを渡す。
そのためには、
- repository index
- dependency graph
- symbol search
- related-ticket lookup
- ADR mapping
などが重要になる。
Agent Briefは、
AIへの指示書
であると同時に、
context boundary
としても機能する。
Stage 3の全体構造
実装構造としては、例えば次のようになる。
Roadmap
↓
ADR
↓
Policy
↓
Ticket ───────→ Brief Generator
↓
Brief Draft
↓
Human Review
↓
Brief Ready
↓
Handler
↓
Ready for Agent
↓
Agent Runner
↓
Agent
↓
Verification
↓
CI
↓
Review Agent
↓
Release Gate
↓
Human / Auto Merge
Stage 4: Autonomous Software Factory
Stage 4では、この仕組みをTicket起点だけでなく、イベント起点へ拡張する。
例えば、
Production Alert
↓
Incident Analysis Agent
↓
Issue Draft
↓
Impact Analysis
↓
Ticket
↓
Brief
↓
Agent
↓
CI
↓
Canary
↓
Monitoring
↓
Release / Rollback
まで閉じる。
ここで初めて、
人間が一つずつTicketを起動する
必要がなくなる。
Stage 4ではControl Planeが中心になる
Stage 4の中心はIDEではなく、Control Planeになる。
例えば、
Development Control Plane
Release: v2.0.0
Active Agents: 18
Waiting Validation: 4
CI Failed: 2
Human Decision Required: 3
Ticket #1001
State: Running
Ticket #1002
State: Contract Violation
Ticket #1003
State: Release Approval Required
人間は、
全てのコードを書く
のではなく、
例外を判断する
ようになる。
Stage 4で重要になるAuto Mergeの境界
Stage 4だからといって、すべてを自動mergeする必要はない。
むしろRisk Levelによって分ける。
Low Risk
↓
Automatic
Medium Risk
↓
Additional Validation
High Risk
↓
Human Approval
Critical Contract Change
↓
Human Only
例えば、
private refactor
は自動化できても、
public API change
security boundary
schema migration
production permission
は人間承認を要求する。
Stage 4は、
人間を完全に排除する
ことではない。
人間が判断すべき箇所だけ残す
ことである。
最終的な状態機械
Agentic Developmentを本格運用するなら、開発フローを状態機械として考えた方がよい。
例えば、
New
↓
Brief Draft
↓
In Review
↓
Brief Ready
↓
Validating
↓
Ready for Agent
↓
Claimed
↓
Running
↓
Verifying
↓
In Review
↓
Release Candidate
↓
Done
例外系として、
Validation Failed
Execution Failed
Verification Failed
Contract Violation
Human Decision Required
Cancelled
を持つ。
この状態機械が、Agent Runner・CI・Redmine・Gitなどを結び付ける中心になる。
実装をどこから始めるか
いきなりStage 3全体を実装する必要はない。
現実的には、次の順序がよい。
Phase 1: Brief Contract
まず、
Agent Briefとは何か
を定義する。
必要項目と状態遷移を固定する。
Phase 2: Handler
次に、
Briefを実行可能状態にできるか
を検証する。
この時点ではAgentを自動実行しなくてもよい。
Phase 3: Runner
Ready for Agentになった作業を、
claim
execute
report
できるようにする。
Phase 4: CI Integration
Agent成果物に対して、
deterministic verification
を実施する。
Phase 5: Result Feedback
CI結果を、
Runner
↓
Ticket
へ戻す。
Phase 6: Policy Layer
Stage 3へ進む場合、
ADR
Contract
Policy
をBriefへ自動反映する。
Phase 7: Multi-Agent Validation
必要に応じて、
Implementation Agent
Review Agent
Security Agent
などへ分離する。
最初からMulti-Agentにする必要はない。
Agentを増やす前にControlを作る
AI Agent導入でありがちな失敗は、
Agentを増やせば生産性が上がる
と考えることである。
実際には、
Agent数
↑
↓
変更量
↑
↓
検証負荷
↑
↓
統合負荷
↑
になる。
Control PlaneなしでAgentを増やすと、人間側が処理できなくなる。
Stage 3で最も重要になるのは、実はAgentモデルそのものではない。
重要なのは、
Contract
State
Execution Boundary
Verification
Evidence
Permission
Retry
Audit
である。
これらが弱い状態で高性能Agentを導入しても、
高速に不確実な変更を大量生成する
だけになりかねない。
したがって優先すべきなのは、
More Agents
ではなく、
Better Control
である。
逆に、この基盤が整っていれば、実装Agent自体は交換できる。
AI Modelを交換可能にする
Agent Runnerが特定のモデルへ密結合していると、将来の変更が難しくなる。
例えば、
AgentRunner
↓
AgentAdapter
↓
Model / CLI / Remote Agent
のような境界を持たせる。
すると、
Local Agent
Remote Agent
Cloud Agent
Different Model
を変更しやすい。
重要なのは、
AI Providerをarchitecture boundaryの外側に置く
ことである。
まとめ
AI Driven Developmentの進化は、
AIがコードを書く
という一直線の話ではない。
実際には、
Stage 1
AI assists human
Stage 2
Human specifies, Agent implements
Stage 3
Human defines policy, Agent system executes
Stage 4
Human controls autonomous software factory
という変化になる。
そして、Stage 2から先で重要になるのが、
Agent Brief
Handler
Agent Runner
CI
State Machine
Policy
Verification
である。
特にAgent Briefは、
AIへのプロンプト
ではない。
それは、
Goal・Scope・Contract・Acceptance Criteria・Verificationをまとめた実行契約
である。
Handlerは、
その契約をAgentへ渡してよいか判断するGate
である。
Agent Runnerは、
Agentの実行・排他・失敗・retry・成果物を管理するExecution Layer
である。
CIは、
Agentの自己申告に依存せず、変更の正しさを検証するVerification Layer
である。
最終的にはこれらが接続され、
Ticket
↓
Brief
↓
Validation
↓
Execution
↓
Verification
↓
Review
↓
Release
というSoftware Development Control Planeになる。
AI Agentが高度化するほど、Software Engineerの中心業務はコードを書くことから離れていく。
その代わりに重要になるのは、
AIが安全にコードを書き、検証され、統合され、失敗したときに止まれる開発システムそのものを設計する能力である。