リプレースで消える「暗黙の仕様」を掘り出す

システムを作り直したあと、最初に届くバグ報告の多くは「新機能が動かない」ではなく「前はできたのに」です。一覧の並び順が変わった、金額の端数が1円ずれる、前回の入力値が自動で入らなくなった。どれも仕様書には書かれていなかったのに、利用者は毎日それに頼って仕事をしていました。

こうした、文書化されないまま守られていた挙動を本記事では「暗黙の仕様」と呼びます。リプレースや大規模改修では、要件定義の段階でこれを掘り出しておかないと、リリース後に「バグ」として一つずつ見つかることになります。

暗黙の仕様が消える仕組み

要件定義でよく使われる材料は、旧システムの設計書と機能一覧です。しかし長く運用されたシステムでは、実際の挙動は次のような場所に散らばっています。

• 設計書にないコード内の分岐（特定の取引先だけ締め日が違う、など）
• フレームワークや DB の既定の振る舞い（主キー順に並ぶ、文字列比較が大文字小文字を区別しない、など）
• 利用者が覚えている操作上の慣習（「この画面で Enter を押すと次の行に進む」など）

新システムは新しい設計書から作られるので、これらは「誰も消そうとしていないのに消える」のです。

掘り出す3つの手順

1. 現行画面の操作を記録する

主要業務を、実際の担当者に旧システムで通しでやってもらい、画面と操作を記録します。見るべきは「何をしたか」より「何をしなくて済んでいるか」です。

• 入力しなくても埋まる項目（前回値・初期値・自動補完）
• 並び順・絞り込みの初期状態
• 計算結果の丸め方・桁数・表示形式
• エラーにならずに通ってしまう入力（全角数字、前後の空白など）

2. 利用者にヒアリングする

「何が必要ですか」と聞いても暗黙の仕様は出てきません。本人も意識していないからです。代わりに次のように聞きます。

• 「この画面で、もし◯◯が無くなったら困りますか」
• 「月末や年度末だけ、やり方が変わる作業はありますか」
• 「システムの動きに合わせて、手元で工夫していることはありますか」

最後の質問は特に有効です。Excel での手作業の補正は、旧システムの挙動に依存した運用であることがよくあります。

3. 旧コードの分岐を読む

すべてを読む必要はありません。次の箇所に絞って grep するだけでも多くが見つかります。

# 特定値で分岐している箇所
grep -rnE "if .*(== ?['\"][A-Z0-9]{3,}|customer_id ?==)" src/
# 丸め・並び順・既定値
grep -rnE "round|floor|ceil|ORDER BY|default" src/

ハードコードされた ID や日付による分岐は、ほぼ確実に過去の個別対応です。経緯を知る人がいるうちに確認しておきます。

「残す／捨てる」を決める判断表

洗い出した挙動をすべて引き継ぐ必要はありません。1件ずつ次の表で判断し、結果を要件として明文化します。

大事なのは「捨てる」も決定として記録することです。リリース後に「前はできた」と言われたとき、意図して捨てたのか、見落としたのかを即座に答えられます。前者なら告知、後者ならバグとして扱えます。

よくある失敗

• 旧システムの設計書だけで要件を作る：書かれていない改修履歴がそのまま抜け落ちる
• ヒアリングを管理職だけに行う：日々の操作を知っているのは現場の担当者
• 受入テストを新しい仕様書だけで行う：旧システムと同じデータで結果を突き合わせる確認を入れておく

Bugoon での実践

暗黙の仕様の洗い出しには、Bugoon のウィジェットを旧システムの画面に埋め込んで使う方法があります。担当者に普段の業務を進めてもらい、「ここは自動で入る」「この並びが前提」と気づいた画面でスクリーンショットにアノテーションを付けて送ってもらいます。操作ステップも自動で記録されるため、どの順番で操作したときの挙動かが後から追えます。

集まった報告はカンバンボードで「残す／改善して残す／捨てる」の列に仕分け、残すものは GitHub Issue に連携して新システムの要件として管理できます。リリース後に「前はできた」という報告が届いたときも、同じボードで旧画面の記録と照らし合わせられます。