承認ボタン連打選手権で優勝した私が、設計理解を取り戻すまで

TL;DR

• AIエージェント開発で危ないのは生成そのものより、内容を確認しない承認フローだった。
• What だけでなく Why を取り戻すために、設計意図を逆算させる固定プロンプトを使っている。
• 理解を深めるには、読むだけでは足りない。小さく壊して挙動を観測する実験が効く。

はじめに

AIエージェントでの開発は速い。
ただ、提案を流れで承認していると、あとで自分が困る。

「動いているけど、なぜこの設計なのか説明できない」

この状態になると、追加実装もリファクタも全部こわくなる。
実際に詰まるのはコード読解より、設計意図の不在だった。

失うのは What ではなく Why

処理内容 (What) は追える。
でも本当に必要なのは、次の判断材料だと痛感した。

• なぜこの構成を採用したのか
• なぜ別の実装を捨てたのか
• どこが将来の負債ポイントなのか

ここが曖昧だと、機能追加のたびに「たまたま動く変更」を積み上げることになる。

理解を取り戻すための固定プロンプト

そこで私は、AIに「経験豊富なテックリード兼、真の設計者」として解剖させるプロンプトを毎回使っている。
要点は次の4つ。

1. README.md / AGENTS.md / docs/ から、先に仕様と制約を掘らせる
2. アーキテクチャを1分で俯瞰させる
3. 実装の Why と捨てた選択肢を明示させる
4. 破壊と実験のメニューまで提案させる

単なるコード解説で終わらず、「次に自分が判断できる状態」に戻すことが目的。

なぜ実験までやるのか

読むだけだと、わかった気になりやすい。
理解を定着させるには、わざと壊して、挙動とエラーを観測するのが一番速い。

例えば以下のような小さな実験を回す。

• バリデーション条件を1つ外して、どこで防波堤が効いているか確認する
• 依存ライブラリの設定値を変更して、想定外の副作用を可視化する
• エラーハンドリングを1段浅くして、障害時の影響範囲を観測する

実験で得た手触りが、そのまま設計の解像度になる。

まとめ

AIエージェント開発で事故るポイントは、実装速度ではなく承認速度だった。
だから私は、承認を流してしまったと感じたタイミングで、必ずリバースエンジニアリングを挟む。

「動くコード」を「説明できるコード」に戻すために。