◉ANTIGRAVITY LABEN
記事一覧/連携・プラグイン
⬡ 連携・プラグイン/2026-11-19中級

エージェントの「連携できました」を、主張の一覧と小さな検証スクリプトで確かめる手順

エージェントが外部サービスとの連携作業を「完了しました」と報告しても、実物が追いついていないことがあります。報告を主張の一覧(claims.json)として書かせ、エージェントとは別の検証スクリプトでファイル・コミット・コマンド・配信先を一つずつ確かめる手順を、動くコードつきでまとめました。

Antigravity419エージェント80検証9連携Python27

配信用のカテゴリ一覧に新しい項目を一つ足す——それだけの作業をエージェントに頼んだ日のことです。返ってきた報告は丁寧で、「一覧を更新し、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 を直接引いて確かめる段階まで進めたくなったら、プレミアム記事で扱っている運用側の設計も、判断の材料にしていただけるかもしれません。私も、確かめる項目を一つずつ足しながら使い続けております。

シェア

お読みいただきありがとうございます

Antigravity Lab は広告なしで運営しており、サーバー費用などの運営コストはメンバーシップのご支援で賄っています。実装コード・ベンチマーク・本番設計パターンなど、実務でお役立ていただける記事を毎日更新しています。もし読んでよかったと感じていただけましたら、ぜひご覧ください。

  • ✦コピー&ペーストで使える実装コード付き
  • ✦毎日新しい上級ガイドを追加
  • ✦¥580/月 または ¥1,480 の永久アクセス
メンバーシップを見る →

もしこの記事がお役に立ちましたら、チップ(¥150)で応援いただけると大変励みになります。広告なしでの運営を続けるため、皆さまのご支援が大きな力になっています。

関連記事

⬡ 連携・プラグイン2026-10-22
文字コードを宣言しないページをエージェントに読ませる前に、UTF-8 のテキストにして渡す小さなスクリプト
ReadURL が UnicodeDecodeError でエージェントごと止まる報告を手がかりに、標準ライブラリだけで文字コードを判定して UTF-8 に直すスクリプトを作りました。最初の版で見落とした BOM・Shift_JIS の機種依存文字・改行タグの扱いを、十枚のテストページで塞いだ経過と切り分け表も残します。
⬡ 連携・プラグイン2026-09-20
10月5日に止まる antigravity-preview-05-2026、差し替えで済む構成と済まない構成
antigravity-preview-05-2026 の停止日が10月5日に決まりました。公式が示すのは日付と後継名だけです。output_text だけを読む構成なら差し替えで終わり、steps を読む構成なら改修が要ります。その分かれ目を切り替え前に確かめる手順です。
◈ Agents & Manager2026-11-19
Issue の本文をエージェントに読ませる前に、GitHub Actions を「読む係」と「書く係」に分けて secrets を遠ざける
Issue の本文は誰でも書ける入力です。それをエージェントに読ませる GitHub Actions を、権限のない「読む係」と、エージェントを動かさない「書く係」の2ジョブに分け、本文をシェルに展開させない書き方と、提案を検める小さな Python スクリプトまでを動くコードつきでまとめました。