AKASHIC ZERO

AIの「直したら壊れた」ループを防ぐ設計:57行AGENTS.mdでトークン95%削減、別AIの3往復レビューと¥0ゲート

AIの「直したら壊れた」ループを防ぐ設計:57行AGENTS.mdでトークン95%削減、別AIの3往復レビューと¥0ゲート — 境界条件の検証コード・監査レシート・導入手順を同梱した実践技術キット。

ClaudeCodeAIエージェント個人開発生成AICursor

Claude Code、Codex、Gemini CLI、Cursor。どれを使っても、ある晩かならず出会う光景があります。

「修正しました」と言われて、テストを回すと、さっきまで緑だった別のテストが赤い。

この記事は、その“直したら壊れた”ループを、ルールの書き方・別のAIへの聞き方・最後に機械で止める門番の3点で断ち切るための実装キットです。

数値はすべて筆者の実機で測ったものだけを載せています。

深夜3時、「修正しました」が止まらない

瑞希「シロイ、見てくださいまし。深夜3時から同じ不具合をAIに直させて、『修正しました』を聞くのはもう何度目かわかりませんわ。しかも直るたびに、別のテストが赤くなりますの」
シロイ「……ん。ログを見た。直すのも確かめるのも同じモデルだね。自分の書いた答えを自分で採点すると、点は甘くなる」
瑞希「だって、ほかのAIに見せるのは手間ですし……そうこうしているうちに、5時間の利用枠が残りわずかですわ」
シロイ「……ん。手間を省いた分、枠で払ってる。今夜の請求書は、たぶんそっちのほうが高い」

起きていることは単純です。

実装したAIが、そのまま自分の差分をレビューしている。だから見落とし方も同じで、「直った」と判定した箇所の外側で別の箇所が壊れます。

そこへ数百行に膨らんだ CLAUDE.md が毎ターン読み込まれ、肝心の禁止事項は文章の奥に沈んでいく。利用枠とAPIクレジットだけが確実に減っていきます。

この記事で解く3つの痛み

痛みよくある対処実際に起きることこのキットの対処
修正ループ同じAIに「もう一度見直して」同じ盲点で同じ見落とし異種AIに3往復だけ監査させる
肥大したルール事故のたびに1行追記毎ターン遅く高くなり、小さいモデルは規則を落とす50行以内の索引型に置き換える
モデル選び迷ったら最上位モデル枠とクレジットが先に尽きる4層で振り分け、最後は¥0の決定論ゲート

直感に反する3つの発見(実機計測)

検証環境

計測はすべて筆者の開発機で行いました。

  • AMD RYZEN AI MAX+ 395(統合メモリ128GB構成)/Ubuntu 24.04.5 LTS/Python 3.12.3
  • Ollama 0.40.8、ローカルLLMは qwen3.6:35b-a3b と gemma4 系
  • 条件は temperature: 0、format: "json"、think: false。各条件3回

ローカルLLM 3モデルの速度とJSON精度だけを比べた無料の姉妹記事も公開しています。今回の土台になった計測です。

https://note.com/shiroi1229/n/n9b2f053609f7

発見1:大きいモデルは長いルールも守る。だから肥大に気づけない

1,800行(108,124字)の手引きの文章中に5つの規則を埋めた版と、同じ5規則を57行(3,741字)の索引型に書いた版。この2つを、同じ3つのレビュー課題で比べました。

指標1,800行の肥大版57行の索引型
入力トークン(qwen3.6:35b-a3b)28,533.71,331.7(95%減)
初回の応答開始(qwen3.6:35b-a3b)24,902ms1,261ms
初回の応答開始(gemma4:31b)132,826ms6,177ms
規則の遵守(gemma4:12b)2/3(66.7%)3/3(100%)
規則の遵守(qwen3.6・gemma4:31b)3/33/3

正直に書きます。大きい2モデルは、1,800行でも規則を守りました。

規則を落としたのは小さい gemma4:12b だけで、3回中1回、文章の奥に埋めた5番目の規則(R5_PUBLIC_DOMAIN_ONLY)を見落としました。

ここが落とし穴です。大きいモデルは長くても守るので、肥大化に気づけない。そのかわり毎回、約20倍のトークンと待ち時間を払い続けます。

発見2:同じAIに見直させても、見落としは減らない

不具合を4つ仕込んだPython関数を用意しました。境界の1ずれ、例外の握りつぶし、タイムアウトの欠落、floatでの金額計算です。

レビュー方式検出見逃したもの
qwen3.6:35b-a3b の自己レビュー3/4(75%)floatの丸め誤差
gemma4:12b の自己レビュー3/4(75%)例外の握りつぶし
決定論ASTゲート単体3/4(75%)境界の1ずれ
異種AI 3往復+ASTゲート4/4(100%)なし

面白いのは、75%どうしの見逃しが別の場所だったことです。モデルごとに盲点が違う。だから同じモデルに何度見直させても埋まらず、別のモデルに当てると埋まります。

3往復は、gemma4:31b が批評し、qwen3.6:35b-a3b が直し、再び gemma4:31b が承認する流れです。

批評役は仕込んでいない「未使用の引数」まで指摘し、修正後の差分はASTゲートの指摘0件で通りました。

ただし4件の仕込みバグでの結果です。どんな不具合も見つかるという意味ではありません。

発見3:最初に置くべきは「賢いモデル」ではなく「決定論ゲート」

同じ4件に対して、ASTゲート(Pythonの構文木を機械的に調べるだけの検査)は約1.2ミリ秒で3件を見つけました。費用は¥0です。

一方、3往復の1往復目、gemma4:31b の批評には36.3秒かかっています。

つまり順番が大事です。機械で判定できるものを先に1ミリ秒で落とし、AIには「意味を読まないと分からない残り」だけを渡す。賢いモデルを最初に呼ぶのは、いちばん高くつく順番です。

この設計を鍛えた本番環境

この記事の設計は、机上の思いつきではありません。

筆者が運営するシロイスタジオ(25xx STUDIO)は、SF世界観 World Archive 25XX の小説・動画・技術記事を作っています。

制作は、複数のAIエージェントで毎日回しています。

その開発環境の入口は、57行の AGENTS.md と48行の DEVELOPMENT.md の2枚だけです。

項目実数
管理しているモジュール982
品質ゲートで固定した検査点3,916
公開済みの動画190本
エージェント共通の入口ファイルAGENTS.md 57行/DEVELOPMENT.md 48行

制作した動画はYouTubeで公開しています。

https://www.youtube.com/@shiroi1229_studio

瑞希「57行で982モジュールが回っているなんて、正直、桁を見間違えたかと思いましたわ」
シロイ「……ん。中身を書かないから短いんだ。規則の本文は各アプリのREADMEにあって、AGENTS.mdは『何をするときに、どこを読むか』だけを持ってる」
瑞希「辞書の本文ではなく、目次だけを毎回渡す……と。それなら長くなりようがありませんわね」
シロイ「……ん。長くならないから、AIも最後まで読む。逆説みたいだけど、それが一番効いた」

放置コストを計算してみる

ループを放置すると、何が失われるのか。実測ではなく、条件を明示した試算です。数字はご自身の現場に置き換えてください。

項目前提・式月額
手戻りの時間週3回 × 40分 × 4.33週 = 519.6分(8.66時間)―
手戻りの人件費8.66時間 × 時給3,000円25,980円
最上位モデルだけで回すAPI費月200タスク × 3.2回 × 1回26.21円16,776.01円
4層に振り分けた場合のAPI費ローカル130件¥0+高速モデル60回+最上位22回374.34円
防げる損失の合計25,980円 + 差額16,401.67円42,381.67円

API費は、肥大版の28,534トークンを毎回読ませる前提です。

単価は100万トークンあたり、Claude Opus 5.5が入力$4/出力$20、Sonnet 5.5が$2/$10。1ドル159.70円で、2026年11月14日に確認した値です。

手戻りがゼロになる前提なので、上限の目安として見てください。半分しか防げなくても、月2万円を超えます。

導入判断:採用(Go)/見送り(No-Go)

合わない人に買わせても、お互い損をします。判断基準を先に全部出します。

判断条件
採用(Go)週に何度もAIへ修正を任せている/同じバグの再発を経験した/ルールファイルが100行を超えた
条件付きGoチームの承認が必要。まず個人リポジトリの Staging QC 設定で2週間試す
見送り(No-Go)AIコーディングを使っていない/使い捨てスクリプトしか書かない/既に異種AIレビューとCIゲートを運用中

ここから先で渡すもの

まとめ

ループの原因は、AIの賢さ不足ではなく構造です。

同じAIに採点させない。ルールは目次にする。最後は機械で止める。この3つを、今日コピペで入れられる形にしました。

有料パートの収録物

#収録物形式
150行索引型 AGENTS.md/CLAUDE.md テンプレートMarkdown(コピペ用)
2異種AI 3往復セカンドオピニオン指示文パック+4層モデル振り分け表テキスト+判断表
3ai_workflow_gate.py(標準ライブラリのみ・実行確認済み)+pre-commit/systemd/GitHub Actions 設定Python・Bash・YAML
4実機の計測レシートと標準出力ログ(verified_at/input_sha256 付き)JSON・テキスト
5判断記録 ADR-2026-MULTI-AI-GATE、4つの運用プロファイル、失敗回避チェックリスト10項目、3分トリアージ表Markdown

¥380のROI:何分で回収できるか

時給3,000円なら、1分あたり50円です。

¥380 ÷ 50円 = 7.6分。修正ループを1回(40分)防げば2,000円分の時間が戻るので、最初の1回で元が取れます。

向いている人/向いていない人

向いている人:

  • Claude Code・Codex・Gemini CLI・Cursor を毎日使い、修正ループで利用枠を溶かした経験がある
  • CLAUDE.md や AGENTS.md が長くなり、守られていない気がしている
  • ローカルLLM(Ollama)を、レビュー係として実務に組み込みたい

向いていない人:

  • AIにコードを書かせていない、または今後も予定がない
  • 理論の解説だけを読みたい(この記事の中心は貼って動かす現物です)

返金とPDF特典について

本記事はnote公式の返金申請を受け付けています。内容が合わなかった場合は、noteの規約に沿って申請してください。

瑞希「つまり必要なのは三つですわね。短い目次、別のAIに投げる質問文、それから最後に機械で止める門番」
シロイ「……ん。三つとも、そのまま貼れる形で下に置いた。考える時間は、自分のバグのほうに使って」

FREE TECHNICAL BRIEFING

実測ポストモーテム・修正パッチの続報を受け取る

一次検証データ・Fail-Closed 境界実装・新規無料記事の公開時にのみ配信します(広告なし・いつでも1クリック解除可能)。プライバシーポリシーに同意のうえご登録ください。

購読管理フォームを別タブで開く ↗