AIに二度同じ注意をしたら、それはプロンプトではなくシステムのバグである

ここ最近、ChatGPT、Claude Code、Codexをかなり本気で開発に使っています。

ChatGPTで設計を詰める。Claude Codeに実装させる。Codexに品質を確認させる。

コードを書く量は明らかに減りました。実装も速い。以前なら数日かけていた変更が、数時間で形になることもあります。

それでも、正直かなりイライラしました。

「それ、さっき言ったよな」

「昨日も同じことを直したよな」

「完了って言ったけど、本当に？」

AIとの開発で消耗するのは、大事故ばかりではありません。むしろ、小さな確認を何度も繰り返させられることが効いてきます。

一度決めた運用ルールが抜ける。CIが通っただけで「完了」と報告する。PRはmergeされたのか聞く。Productionに出ているのか聞く。今動いているSHAと検証したSHAは同じなのか聞く。本番で本当に動かしたのか聞く。

また確認する。また貼り直す。また指示する。

こういうことが続くと、ある瞬間に思います。

**「AIを使って楽になるはずだったのに、なぜ俺がずっと見張っているんだ？」**

ここから、開発方法そのものを見直しました。

そして今は、一つのルールを置いています。

**AIに同じ注意を二度したら、三度目の注意文を書く前にシステムを直す。**

二度目の注意は、AIへの教育というより、開発システムから上がってきた障害報告として扱います。

この記事では、実際に何度も繰り返した「確認」を、Controller、Evidence Ledger、Gateへどう移しているのかを書きます。

人間のエンジニアとAIを競わせたいわけではない

最初にここは明確にしておきます。

人間の開発チームでも、認識違い、確認漏れ、手順の省略は起きます。私自身も同じ失敗をします。

だから良い開発チームは、失敗を個人の記憶だけに預けません。

テストにする。CIにする。レビュー項目にする。権限で止める。監視する。

「次から気をつけよう」で終わらせず、**次から気をつけなくても止まる構造にできないか**を考えます。

AIエージェントとの開発にも、この発想が必要でした。

AI特有の難しさは、セッション、コンテキスト、実装担当、監査担当、GitHub、CI、Productionが簡単に分断されることです。その場では理解していても、次のセッションの行動まで自動で保証されるわけではありません。

問題の中心は「人間とAIのどちらが優秀か」ではなく、**共有状態と統制機構をどこに置くか**です。

AIに怒っても、次のセッションは知らない

例えばClaude Codeに、こう伝えます。

mainへ直接pushしないこと。

その場では理解します。実際、そのセッションでは守ることも多い。

ところが別の作業、別のコンテキスト、別のエージェントになると、同じ前提が抜けることがあります。

こちらとしては、**「いや、それはもう決めただろ」**となります。

一度なら、その場で修正してもいい。

二度目まで人間が同じ注意をしたなら、現在の仕組みでは再発を防げていないことが分かります。

そこで、三度目を人間の記憶力に賭けるのをやめます。

• mainへの直接pushが問題なら、Branch Protectionや権限で止める
• exact head以外のCIを証拠に使うなら、subject SHAをGateで照合する
• Production未確認で完了扱いするなら、Production Smokeを必須Evidenceにする
• AI同士の引き継ぎが抜けるなら、状態をControllerへ集約する

注意文を強くするより、条件式へ変える方が再現性があります。

プロンプトを長くするほど疲れていった

同じ問題が起きると、最初はプロンプトを追加しました。

「必ず確認してください」

「絶対に省略しないでください」

「完了条件は以下です」

「以前この問題があったので注意してください」

どんどん長くなります。

そして、また問題が起きる。さらにルールを足す。

これはかなり不毛でした。

プロンプトは重要です。目的、制約、背景、判断基準を渡すには欠かせません。

ただ、プロンプトには強制力がありません。

例えば「mainへ直接pushするな」と100回書いても、その文章自体がGitHubの権限を止めてくれるわけではありません。

「CIが通っただけで完了扱いするな」と書いても、ProductionのSHAを勝手に照合してくれるわけでもありません。

ここでようやく整理できました。

**方針はプロンプトに書く。守らせたいルールはシステムにする。**

この二つを混ぜていたことが、かなり大きな原因でした。

気づけば、私がAI同士をつなぐAPIになっていた

私の開発では、次のような分業をよく使います。

この役割分担自体は機能します。詳しい分業設計はChatGPT・Claude Code・Codexの分業開発で書きました。

問題は、役割間の接続でした。

Claude Codeが作業結果を出す。

私がコピーする。

ChatGPTに貼る。

ChatGPTが次の指示を作る。

それをClaude Codeへ貼る。

Codexの監査結果をまた別の場所へ運ぶ。

これを何度もやっていました。

あるとき、**「俺はいったい何をやっているんだ」**と思いました。

私はプロダクトの方向や事業判断を考えたい。ところが実際には、AIからAIへ文章を運んでいる。

しかも単なるコピペ係でもありません。

毎回、報告を見ながら「これは本当に正しいのか」「何か取りこぼしていないか」「mainは更新されていないか」「Productionまで出ているか」を確認していました。

AIによって実装労働は減りました。

その代わりに、**監督労働が大量に発生した。**

ここはかなり大きな盲点でした。

一番ストレスがたまるのは「完了しました」

AIとの開発で、個人的に一番警戒するようになった言葉があります。

**「完了しました」**です。

何度か痛い目を見ると、反射的に疑うようになります。

「何をもって完了？」

「PRは？」

「mergeは？」

「mainは？」

「Productionは？」

「本番確認した？」

例えばAIが「修正とテストが完了しました」と報告しても、実際には次の状態があり得ます。

• Pull RequestがDraftのまま
• mergeされていない
• CIを通したあとにコードが追加されている
• mainが別の変更で進んでいる
• Productionは一つ前のSHA
• ローカル確認だけで本番未確認

そこで、「完了」という自然言語を完了条件にするのをやめました。

AIを信じるか疑うかで消耗するより、**信じる必要がない構造へ変える**方が早い。

その中心に置いているのが、Controller、Evidence Ledger、Gateです。

1. Controller：今どこまで終わっているのかを一か所で持つ

Controllerは、開発全体の現在地を管理する統括層です。

AIが何と言ったかより、**今、事実としてどの状態なのか**を見ます。

例えば状態を次のように分けます。

text DISCOVERED ↓ PLANNED ↓ IMPLEMENTED ↓ EXACT_HEAD_VERIFIED ↓ MERGED ↓ DEPLOYED ↓ PRODUCTION_VERIFIED ↓ READY

以前は、この区別を会話の中でやっていました。

「実装済みだけどmerge前」

「merge済みだけど本番未反映」

「本番には出たけど検証未完了」

と頭の中で覚えていた。

人間の頭を状態管理DBとして使っていたわけです。

Controllerを置くと、AIが「完了」と言っていても、状態がIMPLEMENTEDなら実装済み。MERGEDならmerge済み。PRODUCTION_VERIFIEDなら本番検証済み、と機械的に分けられます。

最後のREADYだけを、本当の完了として扱います。

Controllerが見るもの

• 現在のPull Request
• PR head SHA
• main SHA
• CI結果
• merge状態
• Production SHA
• Production Smoke Test
• 未解決Blocker

AIの文章から推測せず、GitHub、CI、ProductionなどのLive Stateから取得します。

Controllerがやるべき判断

Controllerの中心は「次へ進めるか」です。

例えば、EXACT_HEAD_VERIFIEDからMERGEDへ進むなら、現在のPR headに対する必須CIが成立しているかを確認する。

DEPLOYEDからPRODUCTION_VERIFIEDへ進むなら、Production上で対象SHAが動いているかを確認する。

途中でmainが進み、検証対象が変わったなら古い証拠を無効化する。

こうすると、人間が毎回「本当に？」と聞く回数を減らせます。

2. Evidence Ledger：「やりました」より「何を観測したか」を残す

次がEvidence Ledgerです。

これは、状態遷移を成立させた証拠を保存する台帳です。

例えばAIが「本番確認まで完了しました」と報告しても、その一文だけでは後から検証できません。

最低限、次のような情報を残します。

json { "task_id": "TASK-1234", "evidence_type": "PRODUCTION_SMOKE", "subject_sha": "abc123...", "result": "PASS", "status": "ACTIVE", "source": "production", "observed_at": "2026-08-19T12:34:56Z" }

ここで最も重要なのはsubject_shaです。

**何を検証したのか。**

これがなければ、「テスト成功」という情報はすぐに腐ります。

昨日のSHAでテストが成功した。その後コードが変わった。それでも会話には「テスト済み」という言葉だけが残る。

この状態が危ない。

そこでEvidenceには、有効性も持たせます。

text result = PASS status = ACTIVE

この組み合わせなら、現在のGateを満たせる成功証拠です。

対象SHAが変わったら、過去の成功は歴史として残しつつ、statusをSTALEへ落とします。

text result = PASS status = STALE

「前に成功した」と「今の変更を保証できる」を分けるためです。

Evidence Ledgerに最低限ほしい項目

ログを大量に残すことが目的ではありません。

**今も有効な証拠と、もう使えない証拠を区別できること**が重要です。

3. Gate：人間が「待て」と言わなくても止まる

最後がGateです。

必要なEvidenceが足りなければ、次の工程へ進ませません。

以前は人間が会話を見ながら、「いや、それまだmergeしてないだろ」「Production確認してから」と止めていました。

その役割を条件式へ移します。

例えば最終的なREADY判定は、概念的には次のように書けます。

text READY = EXACT_HEAD_CI が PASS / ACTIVE AND PR_MERGED が PASS / ACTIVE AND MAIN_SHA == CANDIDATE_SHA AND PRODUCTION_SHA == MAIN_SHA AND PRODUCTION_SMOKE が PASS / ACTIVE AND UNRESOLVED_BLOCKERS == 0

AIがどれだけ自信満々でも、一つ欠けていればREADY = falseです。

このくらい機械的でいい。むしろ機械的だから助かります。

Scope Gate

変更範囲と権限を確認します。

• 指定されたブランチで作業しているか
• mainへ直接変更していないか
• 許可されたファイルだけを変更しているか
• 別タスクの変更を混ぜていないか

複数AIを同時に動かす場合、この境界は特に重要です。並列運用の具体設計はAIエージェントを並列で動かしても壊さないで整理しています。

Quality Gate

現在の対象SHAに対する品質を確認します。

• lint
• typecheck
• test
• build
• 必要なセキュリティ検査
• 仕様と差分の整合

ポイントは「テストが通ったか」だけでなく、**どのSHAに対するテストなのか**です。

Integration Gate

GitHub上で変更が統合されたことを確認します。

• Pull Requestがmergeされている
• merge後のmainに対象変更が存在する
• candidate SHAとmain SHAの関係が確定している
• 必須CIやBranch Protectionを迂回していない

Production Gate

Productionへ同じ変更が反映され、動作していることを確認します。

• Production SHAと対象main SHAが一致している
• deployが成功している
• 本番環境で必要なSmoke Testが成功している
• 認証が必要な機能は認証済み状態で確認している
• 重大なエラーや監視アラートが発生していない

ここまで揃って初めて、READYへ進めます。

実例：「今のmainと本番は同じSHA？」を二度聞かない

以前なら、こんな会話をしていました。

私：「今のmainと本番は同じSHA？」

>

AI：「確認します」

>

AI：「異なっていました」

>

私：「じゃあ完了じゃないだろ」

一度なら、会話で済ませてもいい。

二度目も同じ確認が必要になったなら、次はProduction Gateへ入れます。

text MAIN_SHA == PRODUCTION_SHA

別の例です。

私：「このCI、最新のheadに対するもの？」

>

AI：「確認したところ、一つ前のSHAでした」

これも二度目からは会話で解決しません。

text CI.subject_sha == PR_HEAD_SHA

をGateへ入れる。

つまり、**私がイライラした箇所を一つずつ条件式へ変えていく**わけです。

感情をそのままプロンプトへ書き足すより、この方が効きます。

「二度目」を仕組み化のトリガーにする

二度という回数に、数学的な意味があるわけではありません。

実務上、判断を先送りしないための基準です。

一度目の失敗では、偶発的か構造的か分からないことがあります。

同じ注意を人間が二度行ったなら、少なくとも現在の仕組みでは再発を止められていません。

その時点で、次のように分類します。

すべての注意をBlocking Gateへ入れると、今度は開発が動かなくなります。

見るべきなのは、**再発したか、影響が大きいか、機械的に判定できるか**です。

Gateを増やしすぎると、今度は別の地獄になる

怖いから全部チェックする。

毎回Full Test。毎回Codex QC。定期cronでずっと状態確認。同じSHAでも再検査。

こうすると安心感は増えます。同時に、CIコストと待ち時間も増えます。

実際、私たちの運用でもGitHub ActionsやCodex QCを使いすぎる問題が起きました。

安全装置を作った結果、その安全装置自体が重くなる。

これでは別の意味でイライラします。

そこでGateにもコスト設計が必要になります。

高リスク変更は重く確認する。

• 認証
• 課金
• 権限
• DB migration
• Production deploy
• セキュリティ境界

低リスク変更では、必要十分な検査へ絞る。

さらに、同じSHAですでに有効なEvidenceが存在するなら再利用する。cronで常時確認するより、PR更新やdeployなどのイベントを起点にする。

この考え方は、AIエージェントはGitHub Actionsを使いすぎるで、CIの発火設計として詳しく書きました。

**必要な危険だけを、必要なコストで止める。**

品質と速度の両方を見るところまで含めてGate設計です。

人間に残したい仕事

この仕組みを作っている理由は、人間を開発から消したいからではありません。

私自身、人間が考えるべき仕事はかなり残ると思っています。

• 何を作るのか
• 顧客は本当に困っているのか
• その機能に投資する価値があるか
• 品質と速度をどう配分するか
• どこまでリスクを許容するか
• 何を捨てるか
• 障害時に誰へどう説明するか

こういう判断には、事業、顧客、組織、感情、責任が絡みます。

私はそこに時間を使いたい。

反対に、「PRはmerge済みか」「SHAは一致しているか」「CIは最新headに対するものか」という確認を毎日何度もしたいとは思いません。

人間の判断力を、機械的な状態確認で消耗させない。

これが狙いです。

AI開発のKPIも変わった

以前は「どれだけ速く実装できたか」をかなり見ていました。

もちろん今も重要です。

ただ、今は別の数字も気になります。

• 人間が介入した回数
• AIからAIへ人間が情報をコピーした回数
• AIの完了報告とLive Stateが食い違った回数
• 同じ注意を二度した回数
• 古いEvidenceを有効だと誤認した回数
• 同一SHAに対して無駄な再検査をした回数
• 一つの変更をREADYにするまでの総コスト

AIが一日に100件実装できても、その100件すべてに人間が付き添うならスケールしません。

「AIが何件仕事をしたか」より、**人間が何回呼び戻されたか**の方が、AIエージェント運用の成熟度を表している気がしています。

「またか」と思った瞬間を記録する

今はAIに対して「また同じことをやってる」と思った瞬間を、以前ほど無駄だと感じなくなりました。

もちろん、その瞬間は普通に腹が立ちます。

何度も説明したことが抜けていればイライラします。「なぜそこを確認しなかった」と思うこともあります。

ただ、その苛立ちをAIへぶつけて終わると、次回また同じことが起きます。

だから、**なぜ自分が今イライラしたのか**を考えます。

私が覚えていたから防げたのか。

私が確認したから見つかったのか。

私がAI同士をつないだから進んだのか。

もしそうなら、その場所にはまだ人間が担っているControl Planeがあります。

そこを一つずつ外へ出す。

Controllerにする。Evidenceにする。Gateにする。

まとめ：三度目の注意を書く前に、システムを直す

「AIに二度同じ注意をしたら、それはプロンプトではなくシステムのバグである」という言葉は、AIを責めるために置いたものではありません。

むしろ、自分たちの運用を疑うためのルールです。

同じ注意を一度した。

二度目もした。

それなら三度目は、人間がまた注意するより、仕組みを変える。

人間が覚えていたから事故を防げたなら、Controllerへ移す。

人間が証拠を探して確認したなら、Evidence Ledgerへ移す。

人間が危ないと思って止めたなら、Gateへ移す。

AIとの開発で感じる苛立ちは、邪魔な感情だけではありません。

かなり優秀なデバッガでもあります。

**「また俺がこれをやっている」**

と思った場所には、まだ人間の注意力で支えている仕事があります。

私は今、その苛立ちを一つずつ開発システムへ変換しています。

AIをもっと上手に叱る方法を考えるより、その方がずっと建設的でした。

最終的に作りたいのは、AIが一度も間違えない環境ではなく、**同じ注意を人間が二度しなくていい開発環境**です。

よくある質問

AIに同じ注意を二度したら、必ずGateにするのですか

何でもBlocking Gateにすると開発が止まります。

影響が大きく、再発していて、機械的に判定できるものからGateへ移します。デザイン上の好みや状況依存の判断は、プロンプトやガイドに残す方が向いています。

プロンプト改善はもう不要ですか

プロンプトは引き続き重要です。

目的、背景、制約、判断基準をAIへ渡す役割があります。ただし、権限制御や状態検証まで自然言語だけに背負わせると不安定になります。

Controllerとは何ですか

AIエージェントの作業状態、GitHub、CI、Production、Blockerなどを横断して、現在どこまで成立しているかを管理する統括層です。

Evidence Ledgerとは何ですか

「やった」という報告より、CI結果、対象SHA、merge状態、本番確認など、状態遷移の根拠になる証拠を記録する仕組みです。対象SHAと証拠の有効性を結び付けることが重要です。

Gateとは何ですか

必要なEvidenceが成立していない限り、merge、deploy、READY判定など次の工程へ進ませない制御です。

AIエージェント開発で最初に仕組み化するなら何ですか

人間が繰り返し確認している項目から始めます。

「最新headのCIか」「mainへmerge済みか」「Productionに同じSHAが出ているか」のように、答えが客観的に決まる確認は仕組み化しやすく、効果も測りやすい領域です。