はじめに
AIにコードを書かせることは、もはや珍しくない。しかし、多くの開発者のAI活用は 「1回の指示で1つのコードを生成する」 という単発利用に留まっている。
本記事では、その先にある 「AIを開発プロセスの一部として組み込む」 ための設計パターンを紹介する。
GitHub Copilot 向けに公開されているエージェント定義ファイル（カスタム指示でAIの振る舞いを定義するマークダウンファイル）100件以上を分析した結果、優れたエージェントには共通するワークフロー設計のパターンがあることがわかった。これらのパターンは GitHub Copilot に限らず、Claude、ChatGPT、Cursor など他のAIコーディングツールにも応用しやすい。
1. タスクの自動分類とワークフロー選択 — Strategy パターン
「全部同じやり方」では破綻する
簡単なバグ修正と大規模なリファクタリングを、同じプロセスで処理するのは非効率だ。人間の開発者は無意識にタスクの規模や性質に応じてやり方を変えているが、AIにも同じことをさせる必要がある。
Blueprint Mode の4ワークフロー
Blueprint Mode というエージェントは、ユーザーの要求を分析し、4つのワークフローのいずれかに自動的に振り分ける設計になっている。
| ワークフロー | 条件 | 特徴 |
|---|---|---|
| Debug | 明確な再現手順のあるバグ | 原因調査→修正→検証に特化 |
| Express | 小規模な変更（2ファイル以下） | 確認なしで即実行 |
| Main | 上記以外の一般的なタスク | 計画→実装→自己採点のフルサイクル |
| Loop | 複数ファイルへの繰り返し処理 | 各アイテムをさらにExpress/Mainに分類 |
これはデザインパターンの Strategy パターン に相当する。タスクの性質に応じて最適な実行戦略を自動選択することで、小さなタスクには軽量なプロセスを、大きなタスクにはフルプロセスを適用できる。
特に注目すべきは Loop ワークフロー の入れ子構造だ。繰り返し処理の各アイテムを Express か Main に分類し、さらに以下の例外処理を持つ。
- アイテム処理中にバグ発生 → Loop を一時停止し Debug ワークフローに切り替え
- 修正が他のアイテムに影響 → ループ計画を更新し影響アイテムを再処理
- 想定以上に複雑なアイテム → そのアイテムだけ Main に昇格
現実の開発では「やってみたら想定より複雑だった」「途中で別のバグが見つかった」が日常的に起きる。これらをあらかじめワークフローに組み込んでいる点が実用的だ。
マルチエージェントによるルーティング
より大規模な設計として、Gem Orchestrator は15以上の専門エージェント（リサーチャー、プランナー、実装者、テスター、デバッガー、批評家など）に作業を振り分けるオーケストレーターだ。
ユーザーの要求
↓ フェーズ検出
├── Discuss Phase（曖昧さの解消）
├── Research Phase（調査が必要）
├── Planning Phase（計画が必要）
└── Execution Phase（実装に着手可能）
↓ 複雑度判定
├── simple → 直接実行
├── medium → 計画→実行
└── complex → 調査→計画→実行
核心的なルールは 「Orchestrator 自身はコードを書かない」 ことだ。ルーティングと状態管理に徹し、実作業は専門エージェントに委ねる。
2. 「計画」と「実行」を分離する — Pipeline パターン
なぜ分離が必要か
LLMは「コードを書いて」と言われると、まずコード生成に進みやすい傾向がある。結果として、全体設計の検討が浅いまま局所最適に寄ったコードになり、後から大きな手戻りが発生しやすい。
Implementation Plan: 計画のみに特化したエージェント
Implementation Plan は、「計画を生成するだけで、コードは一切書かない」ことに特化したエージェントだ。
- 計画の要件: 決定論的・構造化済み・即座に実行可能・自己完結的
- コード編集: 明示的に禁止
- 出力: 別のAIエージェントまたは人間が実行できる形式の計画書
計画は「フェーズ」と「タスク」の階層構造で構成され、すべてにID体系が付与される。
| プレフィックス | 対象 |
|---|---|
REQ-001 |
要件 |
TASK-001 |
タスク |
SEC-001 |
セキュリティ考慮事項 |
CON-001 |
制約 |
DEP-001 |
依存関係 |
TEST-001 |
テスト基準 |
RISK-001 |
リスク |
このID体系により、「TASK-003 は REQ-001 に対応する」「TASK-005 は DEP-002 に依存する」といったトレーサビリティが実現し、AIエージェントが計画をプログラム的に解析・実行できる。
特に注目すべきは、テンプレートに含まれる 「代替案（Alternatives）」セクションだ。却下した選択肢とその理由を明記させることで、意思決定の透明性が確保される。これにより「なぜこのアプローチを選んだか」が後から参照でき、計画レビューの質が向上する。
DAGベースの実行計画
Gem Planner は、タスク間の依存関係をDAG（有向非巡回グラフ）として設計し、Wave スケジューリングで並列実行可能なタスクを特定する。
- 依存関係のないタスク → Wave 1（並列実行可能）
- Wave 1 に依存するタスク → Wave 2
- 以降同様
さらに、Wave 間の接続点にはインターフェース（コントラクト）を定義し、「Wave 1 のタスクAはこの形式で出力する」「Wave 2 のタスクBはその出力を入力として受け取る」という取り決めを明示する。これにより、タスク間の情報伝達が構造化される。
もう1つの特徴は プレモーテム分析（Pre-Mortem Analysis） だ。計画を実行する前に「このプランが失敗するとしたら、どこで失敗するか」を分析させる。事後の振り返りではなく、事前の失敗シナリオ特定を組み込んでいる。
3. 役割分離によるフェーズ境界の強制 — Observer パターン
TDD の規律をシステムで強制する
TDD（テスト駆動開発）の最大の課題は「Red（テスト作成）のつもりで書き始めたのに、いつの間にか実装も書いてしまう」というフェーズ混在だ。人間でも守りにくいこの規律を、エージェントを物理的に分離することで強制する設計がある。
TDD Red / Green / Refactor は、3つの独立したエージェントで TDD サイクルを実現する。
| エージェント | 役割 | ハードな制約 |
|---|---|---|
| Red | テスト作成 | プロダクションコードの記述を禁止 |
| Green | 最小実装 | テストの修正を禁止 |
| Refactor | 品質改善 | テストを全てグリーンに維持 |
フェーズ固有の制約
各エージェントが持つ制約は、TDDの本質を反映している。
Red Phase では、テストが「正しい理由で」失敗することを確認する指示がある。構文エラーによる失敗ではなく、実装が存在しないことによる失敗でなければならない。また、「1回に1つのテストのみ」という制約で、テスト設計の粒度を維持する。
Green Phase では、**「Fake it till you make it」**戦略を段階的に適用する。
- まずハードコードで返す（定数）
- テストが増えるにつれ条件分岐を追加
- さらにメソッドを抽出
- 最終的にコレクションを活用
LLMは「最初から完成形のコードを書きたがる」傾向があるため、あえて段階的実装を強制する指示が重要だ。
Refactor Phase では、通常の品質改善に加えてセキュリティチェックリストが組み込まれている。入力検証、SQLインジェクション防止、XSS対策、認可チェック、OWASP Top 10 という具体的な項目が列挙されており、「Refactor = リファクタリング + セキュリティレビュー」という再定義がなされている。
GitHub Issue を「単一の真実の源泉」とする
3エージェントすべてがGitHub Issueから要件を取得し、Issueに対して報告・更新を行う。ブランチ名から Issue 番号を自動抽出する仕組みにより、ユーザーが毎回 Issue を指定する手間を排除している。
Issue → Red（要件をテストケースに変換）
→ Green（アクセプタンスクライテリアに照らして実装）
→ Refactor（完了条件を最終検証、Issueクローズ判断）
Issue が3フェーズを貫通する共有コンテキストとして機能し、フェーズ間の情報断絶を防ぐ。
役割分離の一般原則
この設計思想はTDDに限らず応用できる。前述の Prompt Builder（Builder / Tester の2ペルソナ分離）や、Gem シリーズ（Orchestrator / Planner / Implementer / Critic の分離）にも同じ原理が見られる。
役割を分離する判断基準:
- 各役割の目的が相反する場合（テスト作成 vs 実装、構築 vs 検証）
- 1つのプロンプトに全役割を詰め込むと制約が曖昧になる場合
- フェーズの出力が次のフェーズの入力となる明確なパイプラインがある場合
4. 品質ゲートとしての自己採点 — Guard パターン
LLMに自身の出力を採点させる
Blueprint Mode は、タスク完了時に5つのカテゴリで自己採点する仕組みを持つ。
| カテゴリ | 評価対象 |
|---|---|
| 正確性 | コードが要件通りに動作するか |
| 堅牢性 | エッジケースやエラーハンドリング |
| 簡潔性 | 不要なコードがないか |
| 保守性 | 他の開発者が理解・変更しやすいか |
| 一貫性 | プロジェクトの既存コードスタイルに合っているか |
各カテゴリを1〜10で採点し、全カテゴリ8点以上が合格条件。1つでも8点未満なら、具体的な改善項目を作成して再実装する。最大3回の反復で、3回で解決しなければタスクを FAILED とする。
自己採点の限界と対策
同一モデルによる自己評価には「自分の誤りに気づけない」リスクがある。この限界を補うアプローチとして、以下のバリエーションがある。
別ペルソナによる検証（Prompt Builder 方式）:
- Builder と Tester の役割を分離し、Tester は Builder の出力を「そのまま実行してみる」ことで問題を検出
- 同一モデル内でも、ペルソナを分けることで視点の違いを生み出す
スコープ別の監査基準（Gem Critic 方式）:
- 計画レビュー、コードレビュー、アーキテクチャレビューでそれぞれ異なる監査基準を適用
- 計画: 分解の粒度、依存関係の妥当性、過剰設計の有無
- コード: ロジックの抜け、エッジケース、YAGNI違反
- アーキテクチャ: 結合度、将来対応の過剰さ、慣例への盲従
3層検証パイプライン（Doublecheck 方式）:
- 主張抽出 → ソース検証 → 敵対的レビュー
- 「正しいか判定する」のではなく「情報源を探して人間に渡す」アプローチ
5. 大規模タスクのコンテキスト管理 — External Memory パターン
LLMのコンテキストウィンドウとの戦い
大規模なコードベース（1000+ファイル）を分析するタスクでは、全ファイルを一度にLLMのコンテキストに収めるのは現実的ではない。LLMは「代表的なファイルだけを読んで全体像を補完する」方向に寄りやすいが、それでは重要な情報を見落とす可能性がある。
Modernization Agent の外部メモリ戦略
Modernization Agent は、既存プロジェクトの分析→ドキュメント生成→アーキテクチャ推薦→実装計画策定を9ステップで行うエージェントだ。最大の特徴は、ファイルシステムをコンテキストの拡張として利用する設計にある。
Step 1〜4: プロジェクトの全ファイルを読み込み、技術スタック・アーキテクチャパターン・ビジネスロジックを分析する。「100%ファイルカバレッジ」が完了条件であり、ファイルのスキップは明示的に禁止されている。
Step 5: 分析結果を機能ごとに独立したMarkdownファイルとして /docs/features/ に出力する（Per-Feature Documentation）。
/docs/features/
├── car-model.md # 車種管理機能の分析
├── driver-management.md # ドライバー管理の分析
├── insurance-policy.md # 保険ポリシーの分析
└── ...
Step 6: これらの中間成果物を再読み込みして master README を合成する（Re-read 戦略）。
この2段階アプローチの意図は以下の通りだ。
- コンテキストウィンドウ制約の回避: 全ファイルを一度に処理するのではなく、機能単位で中間出力を永続化する
- 分析結果の検証可能性: 個別ファイルを人間がレビューできる
- 後続ステップからの参照: 実装計画から機能ドキュメントへのリンクでタスクを紐づけ
チェックポイントの配置設計
9ステップのうち、ユーザーの確認を求めるのはステップ7（分析の正確性検証）とステップ8（技術選定の方向性）の2箇所のみだ。
Step 1〜6: 完全自律動作（ユーザー確認なし）
Step 7: チェックポイント（分析結果の正確性を人間が確認）
Step 8: チェックポイント（技術選定の方向性を人間が判断）
Step 9: 実装計画の生成と新プロジェクト構造の作成
分析フェーズ（ファイルを読むかどうか）は機械的な作業であり人間の介入余地が少ないが、分析の正確性と技術選定は人間の判断が不可欠だ。チェックポイントが「人間の判断が最も価値を持つ箇所」に限定されている点が合理的な設計である。
新旧コードの分離 — Strangler Fig パターン
ステップ9では、新プロジェクト構造を /modernizedone/ フォルダに作成し、既存コードには手を加えない。これはストラングラーフィグパターンの適用であり、既存システムの稼働を維持しながら段階的に移行できる。Cross-cutting concerns（共通基盤）を最初に構築し、その上に機能を順次移行する設計で、依存関係の正しい構築順序を反映している。
6. Human-in-the-Loop の設計 — どこで人間が介入すべきか
介入ポイントの連続体
分析した各エージェントのHuman-in-the-Loop設計を比較すると、以下の連続体が見える。
| エージェント | 介入ポイント | 設計意図 |
|---|---|---|
| 4.1-Beast | なし（完全自律） | 長時間の自律実行を優先。中断を最小化 |
| Blueprint Mode | 信頼度90未満の場合のみ | 数値閾値で判断。確信がある場合は続行 |
| Modernization | 分析完了後 + 技術選定時（2箇所） | 人間の判断が最も価値を持つ箇所に限定 |
| TDD | 全フェーズ（Red, Green, Refactor各1回） | 各フェーズの入力が次フェーズの成否を決定 |
介入ポイントの設計基準
どこに介入ポイントを置くべきかは、以下の基準で判断できる。
人間の判断が必要なケース（介入を入れるべき）:
- 技術選定やアーキテクチャ判断（複数の正解がありうる）
- ビジネス要件の解釈（AIには文脈が足りない）
- 不可逆な操作の前（本番デプロイ、データ移行など）
機械的に実行可能なケース（介入は不要）:
- ファイルの読み込み・分析
- テンプレートに従った出力生成
- 既知のパターンに基づくコード生成
中間的なケース（信頼度スコアで判断）:
- AIが「たぶん正しい」と判断する実装（閾値で制御）
- 小規模な変更と大規模な変更で基準を変える
Modernization Agent の設計がうまい点は、**「分析の網羅性は機械的に検証可能（ファイルカバレッジ100%）だが、分析の正確性は人間の判断が不可欠」**という区別を明確にしていることだ。
介入のオーバーヘッド
TDD エージェントのように全フェーズで確認を入れると、3フェーズ × 1回 = 最低3回の確認が必要になる。小さなバグ修正に毎回3回の確認はオーバーヘッドが大きい。
4.1-Beast の「完全自律」と TDD の「全フェーズ確認」の間のどこにバランスを取るかは、タスクの不可逆性と間違いのコストで決まる。
- 間違いのコストが低い（ローカルのテスト実行など）→ 自律寄り
- 間違いのコストが高い（本番DB操作、セキュリティ設定など）→ 確認寄り
まとめ: タスクサイズ別の推奨パターン
本記事で紹介した設計パターンを、タスクサイズ別に整理する。
小規模タスク（1〜2ファイル、バグ修正や小さな機能追加）
- ワークフロー: Express / Debug（Blueprint Mode 方式）
- 計画分離: 不要
- 品質ゲート: 自己採点（正確性+一貫性の2軸）
- Human-in-the-Loop: なし or 信頼度スコアで判断
中規模タスク（3〜10ファイル、機能開発やリファクタリング）
- ワークフロー: Main（Blueprint Mode 方式）
- 計画分離: 先に計画を生成させ、レビュー後に実行
- 品質ゲート: 自己採点（5カテゴリ、最大3回反復）
- Human-in-the-Loop: 計画レビュー時 + 信頼度90未満の判断時
大規模タスク（10+ファイル、モダナイゼーションやアーキテクチャ変更）
- ワークフロー: Pipeline（計画→実行→検証の直列処理）
- 計画分離: 必須。Implementation Plan 方式でID体系付きの計画書を生成
- 品質ゲート: 役割分離（計画者 ≠ 実装者 ≠ レビュアー）
- コンテキスト管理: Per-Feature Documentation + Re-read 戦略
- Human-in-the-Loop: 分析検証 + 技術選定 + 各フェーズ完了時
パターン選択のフローチャート
タスクを受け取る
│
├── 2ファイル以下？ ─── Yes → Express（即実行）
│
├── バグ？再現手順あり？ ─── Yes → Debug（原因調査→修正→検証）
│
├── 繰り返し処理？ ─── Yes → Loop（各アイテムをExpress/Mainに分類）
│
├── 3〜10ファイル？ ─── Yes → Main（計画→実装→自己採点）
│
└── 10+ファイル or アーキテクチャ変更？
─── Yes → Pipeline（計画分離+中間成果物+チェックポイント）
参考: 本記事で参照したエージェント定義一覧
本記事で分析したエージェント定義は、github/awesome-copilot リポジトリで公開されている。GitHub Copilot 向けだが、ワークフロー設計のアイデアソースとして他のAIツールユーザーにも有用だ。
| エージェント | 本記事での主な言及箇所 |
|---|---|
| blueprint-mode.agent.md | 4ワークフローの自動選択、信頼度スコア、自己採点 |
| gem-orchestrator.agent.md | 15+エージェントへのルーティング、フェーズ検出 |
| implementation-plan.agent.md | 計画と実行の分離、ID体系、テンプレート構造 |
| gem-planner.agent.md | DAGベース計画、Waveスケジューリング、プレモーテム分析 |
| tdd-red.agent.md | TDD Red Phase — テストファースト、実装禁止 |
| tdd-green.agent.md | TDD Green Phase — 最小実装、テスト修正禁止 |
| tdd-refactor.agent.md | TDD Refactor Phase — 品質改善、セキュリティチェック |
| modernization.agent.md | 外部メモリ戦略、Per-Feature Documentation、HITL設計 |
| 4.1-Beast.agent.md | 完全自律実行（Human-in-the-Loop 比較） |
| prompt-builder.agent.md | Builder/Tester の役割分離（品質ゲート比較） |
| gem-critic.agent.md | スコープ別監査基準（品質ゲート比較） |
| doublecheck.agent.md | 3層検証パイプライン（品質ゲート比較） |
Discussion