はじめに
注意書き
この記事は生成AI・AIエージェント運用の超初心者向けです。「そんなの当たり前でしょ」でしかないので玄人の方はそっとブラウザバックしていただければと思います
生成AIを組み込んだ設計書作成パイプラインを運用しています。
パイプラインを動かしていると当然色々と不具合が出てきます。生成結果の品質が微妙だったり、長時間処理の途中で落ちたり、再実行したら結果が明らかにおかしくなったり……。
最初の頃、私はこうやってAIエージェントに直していました。
「このIssue対応して」
もちろん手ぶらで投げていたわけではありません。Issueには 原因も対策（修正方法）もかなり詳細に書いていました。「ここがこう壊れていて、こう直せばいい」まで書いた、いわば答え付きのIssueです。
これだけ書いてあれば余裕だろう、と思っていました。
甘かったです。
Issueを1件ずつ処理してもらうたびに、その場では「もっともらしい」修正が返ってきます。個々の修正はレビューしても妥当に見えるし、実際そのIssueは解決します。
でも修正を重ねていくと、前に直したところと、後から直したところの前提が少しずつズレていくんです。気づいたら一つ直すと別のところが壊れる、直しては壊れの無限ループに突入していました。
この記事では、
- なぜ「詳細に書いたIssueに対応して」だけではダメだったのか
- どこまで事前に防げるのか
- 結局何が一番効いたのか
を、特定の製品名を出さずに一般化してまとめます。
目の前のIssueが解決することと、パイプライン全体が正しく動き続けることは、実は別問題です。
想定しているパイプライン
この記事で扱うのは、入力資料から設計書を生成し、AIレビューと機械的な検査を経て修正する、よくあるタイプのパイプラインです。
実際の運用は、一度実行して終わりということはまずありません。
- 生成品質が十分でなく、一部を再実行する
- 実行結果を評価し、判定方法自体を修正する
- メモリ不足などで処理が途中で落ちる
- 修正後の設計書と過去のレビュー結果が噛み合わなくなる
- 中断地点から再開したら、異なる時点のデータが混在する
- 再実行すると別の問題が新たに出てくる
なので、実態はこういう開発ループになります。
なぜ「詳しいIssue」を渡すだけではダメだったのか
これが今回一番言いたいことです。
Issueに原因と対策を書けば、AIエージェントはその通りに直してくれます。それ自体は間違いありません。AIエージェントは、目の前のIssueに対しては驚くほど正確に働きます。
問題は、AIエージェントが見ているのは「そのIssue」だけだということです。
- 「成果物が変わったら過去のレビュー結果は使わない」という前提で直したIssue
- 「再実行時も過去のレビュー結果を活用してコストを抑えたい」という別のIssue
この2つ、Issue単体で見るとどちらも正しいのですが、両方適用すると、前提が矛盾します。
- どの変更なら過去の結果を使っていいのか
- 何を再確認すべきなのか
- 今の成果物と過去の判定、どっちを基準にするのか
- 判断できないときは続行するのか止めるのか
こういう「Issueとして書かれていない前提」は、いくらそのIssue自体を詳しく書いても、AIエージェントには渡らないんですよね。当たり前と言えば当たり前なんですが、実際にハマるまで気づきませんでした。
つまり、
「このIssue、原因も対策も書いてあるから対応して」
は、そのIssueだけを見れば正しい依頼なんですが、過去の修正との整合性までは保証してくれない依頼だったということです。
AIエージェントが出す修正案は、どれも「単体では」妥当だった
実際に提案・実装された改善は、こんな感じでした。
| 提案 | 期待した効果 | 単体での評価 |
|---|---|---|
| 並列評価 | 実行時間の短縮 | 妥当 |
| ハッシュ値による鮮度確認 | 古いレビュー結果の誤使用防止 | 妥当 |
| 評価キャッシュ | 同じ判定の再実行防止 | 妥当 |
| 文書単位チェックポイント | 中断後の部分再開 | 妥当 |
| 再レビュー抑止 | 時間と利用コストの節約 | 妥当 |
どれも単独で見れば妥当です。技術選定自体が間違っていたわけでもありません。
問題は、これらが時間差で1つずつ追加されたことです。追加するたびに、それぞれの機能が前提としている「正しい状態」がじわじわとズレていきました。
結果的にどう壊れたか
ハッシュ値による鮮度確認が「成果物が変わったら過去のレビュー結果は無効」という前提で動いている一方、再レビュー抑止は「途中から再開時は過去の結果を使い回してよい」という前提で動いていました。両者は別々のタイミングで追加されたので、実装した時点では誰も矛盾に気づきません。
その結果、自動修正でハッシュ値が変わった箇所が軒並み「無効なレビュー」として扱われ、全体の再レビューが走り、AIの利用コスト（クレジット）を大量に消費してしまいました。
一つの機能を直すたびに、別の機能が前提にしていた「正しい状態」を壊す。これを繰り返して、ようやく「個々の修正のレビューを積み重ねても、全体の整合性は保証されない」と気づきました。
一番効いたのはコレでした：「修正履歴1枚markdown」を毎回読ませる
ここが本題です。色々試した中で、体感で一番効果があった方法をお伝えします。
やったことはシンプルで、
「これまで何が問題で、なぜその修正をしたか」を1枚のMarkdownファイルにまとめて、毎回それを読ませてから作業させる
これだけです。
イメージとしてはこんなファイルです。
# 修正履歴
## 2026-XX-XX: 評価キャッシュを追加
- 問題：同じ判定を毎回やり直していて時間がかかっていた
- 対策：ハッシュ値で成果物の同一性を確認し、変わっていなければキャッシュを使う
- 前提：成果物が変わっていなければ「完全に同一」とみなす
## 2026-XX-XX: 再実行時に過去レビューを再利用
- 問題：再実行のたびにレビューコストがかかりすぎる
- 対策：一部項目は過去のレビュー結果を引き継ぐ
- 前提：上記キャッシュの「完全同一」判定とは別に、
「軽微な変更なら一部だけ再チェックする」という新しい基準を追加した
- 注意：これは前の修正の前提を"部分的に"上書きしている
これを「今回のIssue対応の前に必ず読んでください」という形でAIエージェントに渡すようにしてから、明らかに事故が減りました。
なぜ効いたかというと、Issue単体では見えない「過去の前提」が、この1枚に集約されているからです。AIエージェントは目の前のIssueに対しては優秀なので、「過去にこういう前提で直しています。矛盾しないように直してください」と一言添えるだけで、局所最適な修正から一歩踏み出してくれるようになりました。
それでも不具合はゼロにできるのか
結論から言うと、ゼロにはできません。
実データでしかわからない問題・全体規模でしかわからない問題は必ずあります。
ですが、事前にある程度防げる問題もあります。
- 過去に発生した不具合の再発
- 入出力件数の不一致
- 必要な判定結果の欠落
これは回帰テストと、先ほどの修正履歴markdownでかなり防げます。
AIエージェントへの依頼例（Issue対応の前段）
いきなり実装させず、まず影響範囲を整理させるのがおすすめです。
この修正が変更する状態と成果物を列挙してください。
初回実行、成果物の自動修正後、異常終了後の再実行について、
- 判断基準となる成果物
- 再利用する情報
- 無効にする情報
- 停止条件
を表にしてください。
その後、これまでの修正履歴（別添のmarkdown）と矛盾しないかを確認してください。
実装後には、あえて反証させます。
この修正が局所的には正しくても、後続工程で不整合を起こす例を挙げてください。
各例について、現在のテストで検出できるかを示してください。
検出できない場合は、必要な観測項目または停止条件を提案してください。
AIエージェントには実装案だけでなく、前提・反例・失敗条件までセットで出してもらうようにしています。
さいごに
「Issueに原因と対策をこれだけ詳しく書いたんだから、対応してと言えば通じるだろう」と思っていましたが、通じませんでした。AIエージェントは目の前のIssueに対してはとても優秀ですが、そのIssueに書かれていない過去の前提までは読み取ってくれません。
一番効果があったのは、特別な仕組みを導入することではなく、「何が問題で、なぜその修正をしたか」を1枚のmarkdownに書き溜めて、毎回読ませるという、地味だけど確実な方法でした。
AIエージェントの提案を疑うこと自体が目的ではありません。もっともらしい提案を安全に採用できるように、防げる問題は防ぎ、防げない問題は早く見つけて損失を小さくする。これに尽きるかなと思います。