Evidence 3点運用 — 仕様の暗黙知を実装前に表に出す

なぜ書いたか

スライスを実装するとき、AIに「いきなり書いて」と頼むと、参照したファイルが曖昧なまま実装が進みます。後で「これはどこから来た仕様？」と聞いても、AIも自分も思い出せません。今回は、着手前に 3つの根拠を明示する 運用を入れた話です。

Evidence 3点とは

1. source of truth: 元実装（VBのソース、SQL、定義書）。実際の挙動が書かれている場所
2. migration intent: 移行方針ドキュメント、mapping。何をどう移すかの意図 が書かれている場所
3. target file: 移行先で触るファイル。どこに書くか を決める場所

着手前に、この3つをtask logの冒頭にフルパスで書きます。書かれていないとスライスを開始できない、というルールです。

ログの書き方

## task: 申請処理画面 S2 — Oracle 列追加スライス

### Evidence
1. source of truth:
   /path/to/legacy/<対象画面>/<モジュール>.vb
2. migration intent:
   /path/to/migration/docs/migration_mapping.md (S2 セクション)
3. target file:
   /path/to/new/src/Api/Controllers/<対象コントローラ>.cs
   /path/to/new/src/Web.Blazor/Components/Pages/<対象画面>.razor

なぜこれが効くか

• 方針ブレが減る: 着手前に「何を、どこから、どこへ」が固定される
• AIに渡せる: Evidenceをプロンプトに貼れば、AIが参照すべきファイルが明確になる
• レビューで追跡可能: Reviewerが「Evidenceと実装が乖離していないか」を見られる
• 再開コストが下がる: 翌日読み返しても、参照すべきファイルが書かれている

わかったこと

• 「実装してから根拠を後付け」はAIに必ず推測を混ぜさせる。先に固定 するだけで品質が上がります
• Evidence 3点は、実は人間にも効く。書くのに30秒、書かないと30分迷う、くらいの差
• AIレビュー時にも「Evidenceに書かれているファイルしか参照していないか」「Evidenceにないファイルを勝手に触っていないか」を観点に入れられる

補足

Evidence 3点は、私の場合はAGENTS.mdとOrchestratorのテンプレに組み込みました。各スライスの開始時に、Orchestratorが「Evidenceは揃っているか」を確認するルールにしてあります。

これで、AIがいきなり推測ベースで書き始める事故がほぼなくなりました。

次にやること / 未解決の問題

• Evidenceファイルの数が多くなる画面では、3つに絞れない。優先度の高い3つに絞る運用ルールをもう少し具体化したい
• AIにEvidenceを 自分で抽出させる ことができるか試してみたい。今は人間が指定している