「仕様どおり」より「運用どおり」を優先する瞬間

なぜ書いたか

レガシーの業務システムを移行していると、ドキュメントに書かれている仕様と、実際の挙動が違っているケースに出会います。AIに「仕様どおりに作って」と頼むと文書の方を採用するんですが、現場では 実装の挙動を前提に業務が回っている ことがあります。今回はその扱い方の話です。

何が起きやすいか

• 仕様書では「履歴モードでは削除不可」と書いてあるが、実装では特定の条件下で削除できる。現場はそれを使っている
• 仕様書には書かれていない自動コピー処理が、実装中で動いている。それに依存した業務フローが組まれている
• 仕様書のフィールド名と実装のフィールド名が違う。現場は実装の名前で呼んでいる

文書が古い、というだけのケースもあれば、文書化されていない仕様変更が実装にだけ反映された、というケースもあります。どちらにせよ、移行先で「仕様どおり」に作ると業務が止まる リスクがあります。

やったこと

判断ルールはこうしました。

1. 乖離を見つけたら、まずレビューで可視化する: 「ここが違います」をmappingに書く
2. 業務影響を聞きにいく: 利用者か業務担当に「現場ではどっちを使っていますか」を確認
3. 「運用どおり」を採用するなら、その根拠をログに残す: 「仕様書X章Y節と差異あり、運用優先と判断」と書く
4. 「仕様どおり」に直すなら、利用者への通知が必要: 業務フローが変わるので、移行のリリースノートに明記

つまり、AIに勝手に決めさせない。判断は人間が、根拠は文書で、を徹底しました。

わかったこと

• 「仕様どおり」は中立に見えて、実は 判断の放棄 になりやすいです。書いてあるとおりに作るのが最善とは限らない
• AIは仕様書を信じる傾向がある。元コードの挙動をAIに読ませて「文書と違う動きをしている箇所はないか」を先に洗うほうが、後で揉めません
• 採用した判断は 必ず文書に残す。残しておかないと、半年後の自分や他の人が「なんでこうなってるの？」を再調査することになります

例

ある画面で、履歴モード時の操作可視条件が、仕様書では「すべて非表示」、実装では「特定の高権限ユーザーのみ表示」になっていました。現場では高権限ユーザーがそれを使って業務をしていたので、「実装どおり」を採用しました。mappingにはこう書きました。

履歴モード時の操作可視条件:
- 仕様書: すべて非表示（不一致）
- 実装: 高権限ユーザーのみ表示
- 採用: 実装どおり（運用で使われているため）
- 根拠ログ: <該当 task log のリンク>

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

• 「仕様書とのズレ」を発見した数をmappingにカウントしている。多い画面は「仕様書のリビューが必要」と判定する基準を作りたい
• AIに「文書と実装の差分を網羅的に列挙する」をやらせるプロンプトはまだ詰まっていない。今は人間が見ている