「未決」をプロジェクトの進捗として残す — 不明仕様との付き合い方

なぜ書いたか

レガシー移行では、元コードを読んでも「これは仕様なのか、たまたまそう動いているだけなのか」がわからない部分が必ず残ります。AIに実装させると、その曖昧領域を 何となく埋めてしまう。それが後から「業務的に違う」と差し戻しになる、というのを何度かやりました。今回はそれを止めるための運用の話です。

やったこと

ルールはシンプルです。

• 不明仕様を見つけたら、実装範囲外として明示する
• mappingドキュメントとtask logの両方に「未決として残した」を書く
• 次のサイクルで再着手できるよう residual gaps セクションに残す

たとえば、画面のフッターボタン群を移行するスライスで「帳票出力」「一括承認」のような複雑な業務動作が含まれていたとき、私は そのスライスでは導線だけ実装して、本処理は未決 として明示的に切り離しました。

mappingにはこう書きます。

S4 一部完了:
- フッター 6 ボタン中 3 ボタンを正式実装
- 帳票出力・一括承認は未対応メッセージで導線のみ表示（未決）
- residual: 元実装の帳票テンプレ XX 系統のうちどれを使うか要確認

わかったこと

• 「未決」は 不名誉 ではなく 進捗 です。書き残すことで、後続が戻れる地点になります
• AIに判断させると、不明領域を妥当そうな実装で埋めてくる率が高い。「埋めない」を明示的に指示するほうが結局速い
• mappingとtask logの2箇所に書くのは冗長に見えて、片方だけだと必ず忘れます。migration_mapping.md は全体俯瞰、task logはスライス単位の証跡

残課題運用のコツ

• known unknowns を1行で書く（誰が読んでもわかる粒度に）
• 再着手のために必要な情報源（VBのどのファイルを見るか等）も同じ場所に書いておく
• 残課題が積み上がってきたら、まとめて1サイクル取って棚卸し する。気づくと放置されがちなので

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

• 残課題リストが伸びてきたとき、優先度を付ける運用がまだ甘い。ビジネス影響度で並べ替えるルールを足したい
• 「未決として残す」判断をAI側にも任せたいが、AIは埋める方向に偏るので、現状は人間判断にしている