この記事でわかること
- AIエージェントを無人で回すために、なぜプロンプトだけでは足りず強制層が要るのか
- allowlist・ラッパー・hooks をどう組み合わせたか
- アーキテクチャ図を腐らせずに保つ方法
- 出来上がったものをグラフエンジニアリングの設計論と突き合わせた結果
前提
- GitHub Issue を起点に、トリアージ→設計→実装→リリースまでを自律処理するパイプラインの構築記録です
- 前回の記事の続きにあたります
- 設計のエッセンスとアーキテクチャの要点に絞って書いています。個々のスクリプトの実装や具体的な設定の中身までは踏み込みません
前回は、GitHub Issue を自律処理するパイプラインを作っている途中経過を書きました。トリアージと設計までは動いていて、実装から先はまだ検証中、という段階です。
そのとき、こう書いて締めました。
工場を作る準備で一番時間がかかっているのは、モデルの賢さを引き出す工夫ではなく、ラッパースクリプトを切り出し、権限を絞り、ラベルの流れをコードで管理し、それらが想定通り流れていくかテストするという地味な整備です。無人で回しつづけられるかどうかを分けるのは、画面に映らないこの部分だと感じています。
あれから、複数の Issue がリリースまで到達するようになりました。そして、必要だったものは予想と一致していました。
プロンプトの指示は一定確率で破られる
前提として、ここが全ての出発点です。
指示を skills や手順書にどれだけ丁寧に書いても、逸脱はゼロになりません。人間なら「今回は例外」と判断できる場面でも、無人で回している最中の逸脱は誰も止めません。そして前回書いた通り、逸脱は複利で効きます。
なので、お願いで済ませる層と、コードで強制する層を分けました。今回はこの強制層を、三層にする必要がありました。
1. allowlist — 許可されていないコマンドは実行できない
そもそも実行できるコマンドを限定します。
2. 書き込みラッパー — 許可された中でもできることを縛る
allowlist を通ったコマンドでも、ラッパー経由でしか呼べないようにして、その中で何ができるかを制限します。
3. PreToolUse hooks — 手順にないコマンドは実行前に停止して、正しい手順を提示する
止めるだけでは同じ間違いを繰り返すので、「本来はこうしてください」を返します。
一層でも足りそうに見えますが、実際には抜けます。allowlist だけだと許可されたコマンドの中で想定外のことをしますし、ラッパーだけだと別経路から同じことをしようとします。三層あって初めて塞がりました。
コミット経路は git hooks で塞ぐ
コミット経路には git hooks を仕込んで、gitleaks による事前チェックを入れています。
実装の誤りは後から指摘して直せますが、シークレットがコミットに乗ってリモートに push されると履歴を消すのが困難だからです。取り返しがつかない操作だけは、事前に止まるようにしています。
ラッパーは禁止判定ではなく、手段を奪う
ラッパーを切り出していったら25本ほどになりました。勘所は2つありました。
1. 禁止判定ではなく、選択肢自体を消す
「この操作は禁止」と判定する形にすると、判定漏れがそのまま事故になります。そうではなく、やれることの一覧に最初から入れない形にしました。
たとえばラッパーが提供する操作にマージは入っていません。禁止しているのではなく、手段が存在しません。
状態ラベルも同じ考え方で、遷移テーブルを持たせています。テーブルにない遷移は拒否されます。「この遷移はダメ」を列挙するのではなく、許可された遷移だけが存在する状態です。
2. 読み取りにも allowlist が必要だった
これは作ってから気づきました。
書き込みさえ縛れば十分だろうと思っていたのですが、読み取り時も AI は自由にコマンドを組み立てます。 読み取り用のスクリプトをその場で書いて実行しようとしたりもします。結果として許諾ダイアログが出て、そこでループが止まります。
無人で回すという目的からすると、止まること自体が問題です。なので読み取り側にも allowlist を用意しました。
auto mode を使わなかった理由
最近 auto mode がデフォルトになった経緯もあり、ループも auto mode でいいのではないかと考えた時期がありました。
結論としては採用していません。この仕組みでは書き込みが頻繁に発生するため、意図しない書き込みのリスクを非決定的な処理に任せたくなかったからです。
sonnet ベースで実行ツールやコマンドが問題ないか確認してくれるとはいえ、sonnet 自身が「人間の許可が必要」と判断すれば、結局そこで許諾を取りにきます。そしてループが止まります。自動工場という観点からは、これを許容できませんでした。
正直なところ、この部分の制御が一番時間を食いました。検証も含めると、構築で最も重い工程だったかもしれません。
アーキテクチャ図は書かずに生成する
ループや処理が増えてくると、「どのループが何を入力して、何を出力し、どこへ渡すのか」が追えなくなってきます。
最初は図とドキュメントで管理しようとしましたが、すぐに諦めました。たまにメンテナンスする程度では、アーキテクチャ図はすぐ腐るからです。
行き着いたのは3点セットでした。
1. ループごとに入出力を宣言する YAML
ループごとに YAML ファイルを1つ用意して、そこに入力条件・責務・出力・ラベル遷移・使用するラッパースクリプトを宣言します。図やドキュメントではなく、この YAML が唯一の定義です。
2. 宣言を検証するスクリプト
宣言された遷移とラッパーが実在し、allowlist に載っていて、手順書にも書かれているかを検査します。
この実行は CLAUDE.md のルールベースにしていて、hooks では縛っていません。今は自分しか触っていないので、たまに走れば十分だからです。
3. 人間が読む資料は YAML から自動生成する
出力しているのは 2 の検証スクリプトです。宣言が正しいことを検査したうえで、同じ YAML から人間向けの資料を生成します。
図とドキュメントを手で書かないので、腐りません。
語彙は Kubernetes に寄せた
この分野に詳しいわけではなく、Claude が勧めてくれたので採用したのですが、結果として Issue がリソース、ラベルが状態、巡回がリコンサイルという構造になりました。
宣言ファイルの語彙も Kubernetes のマニフェストに寄せています。既にある考え方に乗ったほうが、後から読む人にも説明しやすいと感じています。
AI の自己申告を信じない
AI は成功報告を捏造することがあります。稀に「できました」と報告して、実際にはできていないケースがあります。
なので検証の規約を決めました。
- 成功を主張するときは、コマンドの生出力を引用する
- 生成物は読み取りを行い、実在を確認してから成功と言う
- 出力が空なら失敗として扱う
自己申告ではなく、証拠を出させる形にしています。
止まる設計と、復帰する設計
無人で回す以上、止まらないことより「安全に止まって、あとで再開できること」のほうが重要でした。
- 動作ログを残す
- 迷ったら止まって、Issue にコメントを残す
- どのラベル・どの処理状態で止まっても、次の巡回で復帰できるようにする
もう一つ、運用してから足したルールがあります。AI が人間に何かを依頼するときは、「回答するとこの後に何が起きるか」と「人間側の追加操作は不要であること」を必ず書かせています。
これがないと、人間の側が状況を推測して、想定していないラベルを手で動かすといった無駄な運用が発生してしまいます。人間もグラフの一部なので、人間に渡すときのインターフェースも設計対象でした。
答え合わせ:グラフエンジニアリング
作っている間に、この分野に「グラフエンジニアリング」という名前が付きました。
2026年7月、OpenClaw の作者である Peter Steinberger が X で「まだループの話をしているのか、それとももうグラフに移ったのか」と投げかけたことをきっかけに広まった言葉です。エージェントを、ノード・エッジ・状態からなるグラフとして明示的に設計する、という考え方です。
- 「グラフエンジニアリング」とは何か? - サーバーワークスエンジニアブログ
- FOD#159: Is Graph Engineering Real? Why Everyone Is Talking About It - Turing Post
構築の後半はこの議論を参考にしながら進めて、一区切りついてから改めて設計論を読み直しました。
一致していたもの
| グラフエンジニアリングの要素 | このシステムでの実体 |
|---|---|
| ノード(作業単位) | 定期巡回する各ループ |
| 共有状態 | GitHub Issue の状態ラベル |
| エッジ(遷移) | ラッパーが持つ遷移テーブル |
| コードが経路制御、LLM が判断に集中 | 決定的な処理は全部スクリプト、LLM は解釈と起草だけ |
| 人間は影響の大きいエッジに配置 | 仕様承認と PR マージの2箇所 |
| 失敗経路を正常系と同じ精度で設計 | どの状態からも「人間に渡す」へ落ちられる、再試行は有限 |
| 生成と検証の分離 | 作るループとレビューするループは別コンテキスト、検証側に書き込み権限を与えない |
作り始めた頃はこの言葉を知らないまま手探りで決めていて、構築の後半は議論を参考にしていました。参考にした以上は一致して当然な面もありますが、方向としては同じところに着地していました。
余談ですが、個人的には「ソフトウェアファクトリー」のほうが工場ゲームみたいで好きです。ただ、ループエンジニアリングの正当進化として考えると、グラフエンジニアリングのほうがしっくりきます。少しもやもやしています。
違っていたもの
中央オーケストレータがない
グラフを実行するランタイムが存在しません。各ループが独立に巡回して、共有の情報から自分の入力条件に合うものを拾います。エッジは呼び出しではなく、状態が変われば担当者が拾うという設計です。
これは調べてみたらコレオグラフィ型と呼ばれるものらしく、作ってから名前を知りました。
状態をメモリや DB に持たず、GitHub に依存している
ラベルを付ける・コメントする・マージする、という普通の GitHub 操作が、そのままグラフへの入力になります。
設計の明示だけでなく、コードで強制している
突き詰めるとこうなる気がしますが、明示的に設計するだけでは足りませんでした。プロンプトの指示は破られるので、想定しないエッジはラッパーが拒否するようにしています。
足りていなかったもの
手順書やプロンプトを変えたときの品質劣化を、機械的に確かめられない
ラッパーはテストで守られていますが、プロンプト側はノーガードです。
グラフエンジニアリングの定石では、代表的な入力から発生する正解パターンを数十用意しておいて、変更したら外れていないか検査するようです。難しそうではありますが、これが無いと手順やプロンプトの改善が怖くてできなくなるので、優先したいと思っています。
コストの計量がない
ノード単位のトークン消費量が見えていません。
失敗の原因別分類がない
止まった原因が散文でしか残らないため、自動復旧できるパターンがどれだけあるのかを正確に答えられません。失敗のパターンと進捗をできるだけ残して、何が原因でどこで止まったのかが分かるようにしたいところです。
この3つは Issue にしました。答え合わせをやってみたら宿題が増えましたが、もっと良くできそうな学びがあったので良かったです。時折プラクティスや一次情報と比べてみるのも大切だと思いました。
まとめ
前回の記事では、大事なのは画面に映らない地味な整備だろうと書きました。実際にその通りでした。
この記事の大半が hooks・ラッパー・検査・検証規律で埋まったことが答えです。リリースまで到達するのに必要だったのは、より賢いモデルでも、より精巧なプロンプトでもなく、仕組みづくりでした。
一区切りついたので、次はバグ修正のような単体 Issue への対応ではなく、インクリメンタルな開発もできるようにしていくこと、そしてローカルベースの動作をできるだけクラウドベースに寄せていくことを目標にしています。
この記事は Zenn にも投稿しています。