AI Agent 運用の設計思想
GitHub Issue を起点とした開発を AI Agent に任せるために、どのような考えで仕組みを作っているか。 個別のスキル実装ではなく、その背後にある設計原則をまとめる。
何を解決したいか
AI Agent に開発を任せたときに起こりがちな問題は、大きく 3 つに整理できる。
- 実行のブレ — 複雑な手順を自然言語（Markdown）で指示すると、毎回の解釈が揺れて再現性がない
- one-shot 出力の品質 — 一発生成のコードや文章は、それらしく見えても穴がある
- 人の張り付き — 途中で質問や確認が散発すると、結局人がそばで監視し続けることになる
これらを解決するために、運用全体を「人の関与を最初と最後に寄せ、中間は機械的なゲートで品質を担保する」 形に設計している。
全体アーキテクチャ: 3 層に分ける
仕組みは「宣言」「制御」「実行」の 3 層に分けている。 ポイントは、順序制御・タイムアウト・成果物管理・合否判定といった「ブレてはいけない部分」を AI ではなく自作プログラム（Go 製 CLI）に持たせていることと、 実行層の AI Agent を差し替え可能にしていること。
設計原則
運用を支える原則を 4 つのテーマに分けて示す。
特定の AI Agent に依存しない
特定ベンダーの CLI 前提で運用を組むと、性能・価格・提供形態の変化で運用全体が崩れる。
Skill・カスタムエージェント定義・設定を 1 つの Git リポジトリで管理し、 Claude Code / Codex / Copilot / Gemini など複数の CLI へ同じ内容を配布する。 どの Agent でも同じワークフローが動く状態を保つ。
サードパーティ製オーケストレーションツールを使わない
外部のオーケストレーションツールは、課金形態の変更（定額→都度課金など）や開発停止のリスクを自分で制御できない。
制御層は自作の CLI として実装し、各 AI Agent の公式 CLI を直接呼ぶ。 依存はベンダー公式のインターフェースだけに限定する。
実行制御はプログラム、判断は AI
複雑な多段ワークフローを Markdown だけで指示すると、手順の解釈が毎回ブレて再現性がなくなる。
順序・ロック・タイムアウト・成果物生成はプログラム側で決定的に実行し、 AI Agent に任せる範囲を「判断が必要な作業単位」だけに絞る。Skill は薄い入口に保つ。
複数のゲートで合否を機械判定し、失敗したらやり直す
「完了したか」を AI の自己申告で決めると、未検証のまま完了報告される。
着手可否（readiness）、テスト等の検証、レビュー収束、コンフリクト、E2E といった ゲートを工程ごとに置き、通らなければ修正に戻るループを回す。未解決の必須アクションが残る限り完了扱いにしない。
判定根拠は自然言語ではなく構造化データ補足
AI の出力する要約文は、都合よく「成功」に丸められることがある。
各工程の結果は stdout JSON・イベントログ・証跡ファイルとして残し、 ゲートの合否や完了報告はそのデータを根拠にする。報告文はデータから生成されるものに過ぎない。
曖昧な指定は実行前に止める（fail-fast）補足
矛盾したオプションや解釈の余地がある指定を AI が「いい感じに」解釈すると、意図しない経路で実行される。
各入口の責務を 1 つに絞り（起票だけ・実装だけ・レビューだけ）、 組み合わせとして成立しない指定は作業開始前にエラーで停止する。途中で黙ってフォールバックさせない。
one-shot 出力をそのまま使わない
同じモデルが書いて同じモデルが見直すだけでは、盲点が共有されていて穴を見逃す。
生成物（Issue 案・コード・PR 文面）は、別の AI Agent やサブエージェントによる 検証・レビューを必ず通す。レビューは複数系統（複数のローカル Agent + GitHub 上の bot レビュー）を併走させ、 指摘が出なくなるまで収束させる。
デフォルトは安全側、環境に触る操作は opt-in補足
E2E テストや環境設定の変更を AI の判断で自動実行すると、ローカル環境や共有状態を壊しうる。
環境へ影響する工程はデフォルト off の opt-in にし、実行方法が一意に決まらない場合は 「ユーザー判断が必要」として停止する。勝手に進めない。
内部情報と公開情報の境界を管理する補足
AI は内部ツール名・秘匿値・ワークフロー用語を、公開される PR 本文や設定ファイルへ無自覚に書き出す。
設定のバージョン管理では秘匿値とホームパスを自動サニタイズし、 PR 本文など公開文面には内部ワークフローの用語を出さず公開向けの表現へ翻訳するルールを敷く。
AI からの質問は最初に集中させる
作業中に質問が散発すると、人が応答するまでワークフロー全体が止まり、結局張り付きになる。
着手前に Issue・依頼内容の不明点を洗い出して一括で確認し、前提を確定させてから実装に入る。 実装中に前提が崩れた場合だけ、チェックポイントで検出して停止する。
依頼後は完了まで人の判断を不要にする
途中の承認待ちが挟まるほど、自動化の価値（並列で別の仕事ができる）が失われる。
実装 → 簡素化 → 多重レビュー → 検証 → PR 作成までを 1 本のフローとして無人で完走させる。 人が見るのは最後の成果物（PR と証跡つきの完了報告）だけにする。
問題が起きたら都度 Issue 化して仕組みを改善する
運用上の不具合をその場しのぎで直すと、同じ失敗を別の Agent・別の日に繰り返す。
ワークフロー自体の問題も GitHub Issue として起票し、Skill・制御プログラム側に修正を入れる。 運用そのものを継続的な改善対象として扱う。
1 つの Issue が PR になるまで
原則を組み合わせると、実際の開発フローは次のようになる。デモで見せるのはこの流れ。
ダブルチェック体制の構造
「one-shot 出力を信用しない」を支える構造。生成した Agent とは別系統の視点を 複数並走させ、合否はレビュー結果のデータからプログラムが判定する。
デモで注目してほしいポイント
- 最初の質問だけに答えれば、あとは PR まで自動で進むこと（原則 10・11）
- レビュー指摘が出たとき、人が指示しなくても修正 → 再レビューが回ること（原則 04・07）
- 完了報告に「残アクション数」「検証結果」などの証跡が添えられること（原則 05）
- 同じワークフローが別の AI Agent CLI でも動くこと（原則 01）
※ Skill・制御プログラムの実装はプライベートリポジトリで管理しているため、この資料では設計原則のみを公開している。