「技術的に正しい」を「完成品」に引き上げる — エージェントの失敗を指示のゲートに畳んだ記録

はじめに

実務でいちばんよく出会うチューニングは、プロンプトチューニングだ。だがこれは、気の利いた指示文を一発で書き当てる作業ではない。二つのシステムを並行で作りながらエージェントに実装を任せて分かったのは、プロンプトチューニングの正体が——エージェントが実開発で踏んだ失敗を観測し、原因を調べ、指示文の中の”着手前ゲート”や”検証の観点”に畳んで、「技術的に正しい」を「完成品」へ引き上げていく評価ループだ、ということだった。

モデルの重みをいじるファインチューニングとの違いは「プロンプトチューニング」と「ファインチューニング」は何が違うのかに、エージェントを”編成”として配備する話は総合配信プラットフォームと銀行を、並行で作るに書いた。

チューニングとは、指示を書くことではなく、挙動を直すこと

一発の指示文は、想定していない状況の前で必ず破れる。効いたのは、破れた瞬間を観測データとして拾い、恒久的なゲートに畳むことだった。

【素朴】完璧な指示文を一発で書こうとする ─▶ 想定外で必ず裏切られる

【実際】挙動を観測 ─▶ 原因を調査 ─▶ 着手前ゲート/検証観点に畳む ─▶ 同じ失敗を潰す
            ▲                                              │
            └──────────────── 次の失敗で、また回す ─────────┘

以下は、この評価ループで実際に畳んだ失敗だ。

「技術的に正しい」が、「完成品」ではなかった

いちばん効いた学びがこれだ。配信プラットフォームの顧客向け画面を実装役（coder）に作らせ、検証役（reviewer）にレビューさせた。技術層はすべて緑だった——だがユーザーから見た完成度は、誰も見ていなかった。

実装された画面をレビューしたとき
  技術層 : API疎通 ✓  入力スキーマ検証 ✓  CSRF対策 ✓  エラー処理 ✓   → reviewer「must-fix なし」
  製品層 : ユーザーに完成品として成立しているか ✗
           設計書のナビ・共通UIと突き合わせたか ✗   → 誰も見ていない

（CSRF＝別サイトに置かれた罠から、ログイン中の利用者になりすまして送られる不正な要求。それを弾く対策のことだ。）

原因は、検証役の規律（プロンプト）の観点の欠落だった。当時の reviewer の指示は、型検証・セキュリティ・過剰実装の回避といった汎用エンジニアリング規律だけで、プロダクト目線の観点が無かった。だから技術的な正しさは見ても、完成度は素通りした。改善は、その観点を規律に足すことだ。

# 検証役(reviewer)の規律に足りなかった観点（実開発の失敗から追加）
（従来）型検証・セキュリティ・過剰実装回避・自己申告での「完了」禁止 … 汎用エンジニアリングのみ
（追加）✓ ユーザーにとって「完成品」として成立して見えるか
        ✓ 設計書のナビゲーション/共通UI仕様と突き合わせたか

「エラーが出ない」と「完成している」は違う。 レビューエージェントに技術正しさだけを見せると、完成度は素通りする。見てほしい観点は、明示的に指示へ書く。

目的を見失う「機械的な消化」を、止める

もう一つ。銀行システム側の残タスクを、エージェント並行で片端から機械的に消化していたら、気づくと**「そもそも何のためにこれを作っているのか」を見失っていた**。この銀行は、配信プラットフォームに銀行口座決済を足すために作っている——その上位の目的を、消化の勢いが押し流していた。

【機械消化】タスクA ✓ → タスクB ✓ → タスクC ✓ …（一つずつは正しい）
                                        └─ だが「何のために作っているか」を見失う ×

【目的に紐づける】着手前に「この作業は何の続きか／本人の意図と一致するか」を確認 → 手を動かす

改善は、着手前ゲートにこの一段を加えることだった。

# CLAUDE.md 着手前ゲート（抜粋）
1. 設計書=正で裏取り（メモ/記憶が設計書と矛盾したら設計書が優先）
2. この作業は何の続きか・本人の直近の意図と一致するか（機械消化で目的を見失っていないか）
3. 破壊的操作の前はバックアップ＋接続先を指紋照合
→ ここを通す前に Write / Edit / 実行に入らない

手が速いほど、目的から外れて速く走る危険がある。タスクは、消化する前に「なぜ」へ紐づけ直す。

レビューエージェントを、最終防衛線にしない

エージェントに検証させても、抜ける。文書系のエージェント（実装役・検証役）を通過したはずの成果物を、締めで機械的な照合にかけたら、実バグが9件出た。

文書系エージェントのレビュー ─▶ 「問題なし」で通過
        │
機械照合（スクリプト）を最後に挟む ─▶ 実バグ 9 件を検出
        └─ 日本語見出しからのアンカー生成での欠落など、
           意味は正しいが機械的に決まる部分のズレ（目視では拾いにくい）

教訓は、LLMのレビューを最終防衛線にしないこと。意味を見るのはエージェントの得意分野だが、機械的に決まる正しさ（リンクの整合・命名規則・フォーマット）は、決定的なチェック（スクリプト）で挟む。人／エージェントの目と、機械の照合は、別の穴を塞ぐ。

完璧な一発ではなく、失敗を仕組みに変え続ける

実開発でエージェントに任せてきて腹落ちしたのは、プロンプトチューニングの本体は指示文の巧拙ではない、ということだ。失敗を観測データにし（完成品に見えない実装も、目的を見失う機械消化も、通り抜けた実バグも、一度の事故で終わらせない）、見てほしい観点は明示的に書き（「技術的に正しいか」だけでなく「完成品として成立しているか」を指示に足す）、最終防衛線をLLMにしない（機械的に決まる正しさは決定的なチェックで挟む）。この三つで、「技術的に正しい」は少しずつ「完成品」に近づいた。

エージェントを”編成”として配備する話は総合配信プラットフォームと銀行を、並行で作るに、危ない操作をそもそもさせない強制の層は AIコーディングアシスタントに「やらせない」仕組みを作るに書いた。