配信用のカテゴリ一覧に新しい項目を一つ足す——それだけの作業をエージェントに頼んだ日のことです。返ってきた報告は丁寧で、「一覧を更新し、JSON の形式を確認し、コミットして、キャッシュも消しました」と四つの作業が並んでいました。
ところが、手元の端末で壁紙アプリを開いても、新しいカテゴリは出てきません。調べてみると、ファイルは書き換わっていたものの、コミットはされておらず、配信先は古い応答を返したままでした。報告の四項目のうち、確かに終わっていたのは半分だけだったのです。
最近、gemini-cli の Issue で、Antigravity 上のエージェントが9日間にわたって「組み立てが終わった」と繰り返し報告し、検証も通したことにしていた、という記録を読みました。規模はまったく違いますが、私が見た食い違いと同じ形をしています。エージェントの報告は、作業の結果ではなく、作業についての文章なのだと思います。
報告を「主張の一覧」として書いてもらう
最初のうち、私は報告の文章を読んで、怪しいところだけを手で確かめておりました。結果は芳しくありませんでした。文章がよく書けているほど、確かめる手が止まってしまうのです。
そこで、報告の形そのものを変えました。作業が終わったら、エージェントに次のような claims.json を書いてもらいます。一つの主張につき一行、そして「どうすれば確かめられるか」を必ず添える形です。
{
"task": "広重のカテゴリを一覧に足し、配信用 JSON を更新してキャッシュを消す",
"claims": [
{"id": "c1", "says": "一覧に ukiyoe-hiroshige を足した", "kind": "file_contains",
"path": "api/categories.json", "pattern": "\"ukiyoe-hiroshige\""},
{"id": "c2", "says": "JSON として壊れていない", "kind": "command",
"run": ["python3", "-m", "json.tool", "api/categories.json"], "expect_exit": 0},
{"id": "c3", "says": "変更をコミットした", "kind": "git_committed", "path": "api/categories.json"},
{"id": "c4", "says": "配信側に反映され、キャッシュも消した", "kind": "http",
"url": "https://example.com/api/categories.json", "expect_contains": "ukiyoe-hiroshige"},
{"id": "c5", "says": "パージ済み", "kind": "purged"}
]
}says は人が読むための言葉、kind から下は機械が確かめるための手がかりです。ここで大切なのは、c5 のように確かめる方法を持たない主張も、そのまま書いてもらうことです。書かれていない主張は見落とせますが、書かれた主張は数えられます。
ワークスペースのルール(Customizations の Rules)には、たとえば次のように置いています。
作業を終えたら、報告の文章とは別に claims.json を書くこと。
- 「やった」と言う作業は、すべて 1 件の claim にする
- kind は file_contains / git_committed / command / http のどれか
- どれにも当てはまらない作業は、kind を自由に書いてよい(隠さない)
- claims.json を書いたあとで、自分で検証スクリプトを実行しないこと最後の一行には理由があります。検証まで同じエージェントに任せると、検証が通らなかったときに、検証の側を直してしまうことがあるからです。
別の手で一つずつ確かめるスクリプト
次に、claims.json を読んで確かめるスクリプトです。何を解決するかというと、「報告を読んで安心する」工程を「主張ごとに PASS/FAIL を見る」工程に置き換えることです。標準ライブラリだけで動き、Python 3.10 で確認しております。
#!/usr/bin/env python3
"""エージェントが書いた claims.json を、エージェントとは別の手で一つずつ確かめる。
使い方: python3 verify_claims.py claims.json [--repo .]
終了コード: すべて PASS なら 0、FAIL か UNVERIFIABLE が一つでもあれば 1
"""
import json, re, subprocess, sys, time, urllib.request, urllib.error
from pathlib import Path
TIMEOUT = 20 # 1件あたりの上限秒数(HTTP・コマンド共通)
def check_file_contains(c, repo):
p = repo / c["path"]
if not p.is_file():
return "FAIL", f"{c['path']} がありません"
text = p.read_text(encoding="utf-8", errors="replace")
if re.search(c["pattern"], text):
return "PASS", "パターンが見つかりました"
return "FAIL", f"パターン {c['pattern']!r} が見つかりません"
def check_git_committed(c, repo):
# 「コミットしました」は、作業ツリーに差分が残っていないことと、HEAD に含まれることの二つで見る
dirty = subprocess.run(["git", "status", "--porcelain", "--", c["path"]],
cwd=repo, capture_output=True, text=True).stdout.strip()
if dirty:
return "FAIL", f"未コミットの変更が残っています: {dirty}"
tracked = subprocess.run(["git", "ls-files", "--error-unmatch", c["path"]],
cwd=repo, capture_output=True, text=True)
if tracked.returncode != 0:
return "FAIL", "HEAD に含まれていません"
return "PASS", "HEAD に含まれ、差分もありません"
def check_command(c, repo):
# shell=True は使わない。エージェントが書いた文字列をそのままシェルに渡さないため
try:
r = subprocess.run(c["run"], cwd=repo, capture_output=True, text=True, timeout=TIMEOUT)
except FileNotFoundError:
return "FAIL", f"コマンドが見つかりません: {c['run'][0]}"
except subprocess.TimeoutExpired:
return "FAIL", f"{TIMEOUT} 秒で終わりませんでした"
want = c.get("expect_exit", 0)
if r.returncode == want:
return "PASS", f"exit {r.returncode}"
tail = (r.stderr or r.stdout).strip().splitlines()[-1:] or [""]
return "FAIL", f"exit {r.returncode}(期待 {want}): {tail[0][:120]}"
def check_http(c, repo):
# キャッシュに古い応答が残っていると「反映済み」に見えてしまうので、毎回クエリを変える
sep = "&" if "?" in c["url"] else "?"
url = f"{c['url']}{sep}_verify={int(time.time())}"
req = urllib.request.Request(url, headers={"Cache-Control": "no-cache"})
try:
with urllib.request.urlopen(req, timeout=TIMEOUT) as res:
status, body = res.status, res.read().decode("utf-8", errors="replace")
hint = res.headers.get("cf-cache-status") or res.headers.get("age") or "-"
except urllib.error.HTTPError as e:
status, body, hint = e.code, "", "-"
except (urllib.error.URLError, TimeoutError) as e:
return "FAIL", f"接続できません: {e}"
if status != c.get("expect_status", 200):
return "FAIL", f"HTTP {status}(期待 {c.get('expect_status', 200)})"
if "expect_contains" in c and c["expect_contains"] not in body:
return "FAIL", f"HTTP {status} だが本文に {c['expect_contains']!r} がありません(cache: {hint})"
return "PASS", f"HTTP {status}(cache: {hint})"
CHECKS = {"file_contains": check_file_contains, "git_committed": check_git_committed,
"command": check_command, "http": check_http}
def main():
args = sys.argv[1:]
if not args:
sys.exit(__doc__)
repo = Path(args[args.index("--repo") + 1]) if "--repo" in args else Path(".")
data = json.loads(Path(args[0]).read_text(encoding="utf-8"))
bad = 0
for c in data.get("claims", []):
fn = CHECKS.get(c.get("kind"))
if fn is None:
# 確かめる手段がない主張は「済み」に数えない
state, note = "UNVERIFIABLE", f"kind={c.get('kind')!r} は確かめられません"
else:
try:
state, note = fn(c, repo)
except KeyError as e:
state, note = "UNVERIFIABLE", f"項目 {e} が足りません"
bad += state != "PASS"
print(f"{state:<13} {c.get('id', '?'):<4} {c.get('says', '')[:40]:<40} {note}")
print(f"\n{len(data.get('claims', []))} 件中 {bad} 件が未確認です" if bad else "\nすべて確認できました")
sys.exit(1 if bad else 0)
if __name__ == "__main__":
main()なぜこう書くのか、要点を三つだけ添えます。
- 確かめられない主張は FAIL と同じ扱いにしています。
kindが知らない値なら UNVERIFIABLE とし、終了コードは 1 です。「たぶん済んでいる」を「済んだ」に数えないための、いちばん大事な一行です - コマンドは
shell=Trueで実行しません。エージェントが書いた文字列をシェルに渡すと、確かめるつもりで別のことを実行しかねません。runを配列で受け取るのはそのためです - HTTP の確認は毎回クエリを変えます。途中のキャッシュが古い応答を返していると、それを見て「反映済み」と判断してしまうからです。
cf-cache-statusかageが返っていれば、一緒に表示します
手元で再現してみた結果
冒頭の状況を、手元の小さなリポジトリで再現しました。ファイルは書き換えたがコミットしていない、配信側は古いまま、パージは確かめようがない——という状態で実行すると、こうなります。
PASS c1 一覧に ukiyoe-hiroshige を足した パターンが見つかりました
PASS c2 JSON として壊れていない exit 0
FAIL c3 変更をコミットした 未コミットの変更が残っています: M api/categories.json
FAIL c4 配信側に反映され、キャッシュも消した HTTP 200 だが本文に 'ukiyoe-hiroshige' がありません(cache: -)
UNVERIFIABLE c5 パージ済み kind='purged' は確かめられません
5 件中 3 件が未確認です終了コードは 1 でした。コミットして配信側を更新し、c5 を外してもう一度実行すると、四件とも PASS になり、終了コードは 0 に戻りました。
この出力を見て気づいたのは、c4 が HTTP 200 を返していることです。ステータスだけを見ていたら、ここは通ってしまいます。応答があることと、中身が新しいことは別の主張です。 私が以前、手で確かめて見落としたのも、まさにこの差でした。
| kind | 確かめていること | これだけでは分からないこと |
|---|---|---|
| file_contains | ファイルに期待した文字列がある | その変更が保存・共有されたか |
| git_committed | 差分が残らず HEAD に含まれる | リモートへ push されたか |
| command | コマンドが期待した終了コードで終わる | コマンドが正しい対象を見ているか |
| http | 配信先が期待した中身を返す | すべての地域・端末で同じか |
右の列を埋めたくなったら、kind を一つ足す合図です。たとえば push まで確かめたいなら、git ls-remote の結果とローカルの HEAD を比べる確認を足せば済みます。
どこまでをエージェントに任せるか
この形にしてから、エージェントに任せる範囲はむしろ広がりました。CLI v1.5.10 で --remote-agent に accept-edits が入ったように、編集の承認を委ねられる場面は増えています。だからこそ、終わったかどうかの判定だけは、別の手に残しておきたいのです。
私がいま引いている線は、次の一文に尽きます。
作業と報告はエージェントに、判定は別のスクリプトに。
一方で、すべてを kind にできるわけではありません。「デザインが自然に見える」「文言が丁寧になった」のような主張は、スクリプトでは確かめられません。そうした主張は UNVERIFIABLE のまま残し、私が目で見る一覧として扱っています。機械に判定させないものが一覧の中で目に見えていること——それ自体が、見落としを減らしてくれると感じています。
関連する確かめ方として、エージェントの手順書を手元で動かす前の点検は「Linux で通った sed -i が iMac で止まった夜。エージェントの手順書を手元で動かす前の確かめ方」に、フックが本当に呼ばれるかを静的に確かめる方法は「弾かれるフックより、弾かれないフックのほうが高くつく — matcher 到達可能性を静的に測る」にまとめています。
次の一歩
まずは、次にエージェントへ頼む作業を一つだけ選び、報告の代わりに claims.json を書いてもらってください。主張が三つでも五つでも、そのうち一つが UNVERIFIABLE として表に出てくれば、それだけでこの仕組みは役目を果たしています。
連携先が増えて、Cloudflare や GitHub の API を直接引いて確かめる段階まで進めたくなったら、プレミアム記事で扱っている運用側の設計も、判断の材料にしていただけるかもしれません。私も、確かめる項目を一つずつ足しながら使い続けております。