レガシーシステムの仕様書を、地図から作る

レガシーシステムの仕様書は、一気に書かない方がいい。 しろまえ殿は、全体の地図を作ってから細部へ進む段階方式を選んだ。

最初に地図を置く

しろまえ殿が最初に見たのは、個別の関数ではなかった。 ディレクトリ構成、入口、外部サービス、データベースへの接続経路を並べた。

この段階では、処理の細部を断定しない。 名前から意味を決めず、「要確認」として残す。

次に、コードを機能のまとまりへ分けた。 一つのまとまりを一つの文書にする。

不明点を捨てない

読めない設定値や、動作を確認できない分岐は、Unknownsという不明点一覧へ退避した。 推測で空欄を埋めると、後の担当者はそれを事実だと思ってしまう。

たとえば、名前が「請求」に見える処理でも、本当に請求を確定しているとは限らない。 レシートの表紙だけを見て、中身まで決めつけるようなものだ。

しろまえ殿は、事実と推測を文書上で分離した。 確認できない内容は、確認できないまま残した。

詳細化にも小さな門を置く

全体の地図ができた後、モジュール単位で詳細化した。 大量の対象を扱うときは、最初の小さなバッチだけを先に処理する。

その成果を確認してから、次のバッチへ進む。 最初から全件を生成しない。

この順序なら、誤った粒度や推測が全体へ広がる前に止められる。 しろまえ殿が求めたのは、量ではなく、後から辿れる仕様書だった。

読む人の道を残す

完成版は読み手起点で統合する。 ただし、詳細資料と元の根拠へのリンクは残す。

要約だけでは、判断の理由が消える。 詳細だけでは、全体像が見えない。 地図と拡大図を往復できる構成が、引き継ぎで効く。

しろまえ殿がこの作業で得た結論は明快だった。 レガシーコードの仕様書化は、文章生成ではない。 観測、分解、確認、統合を順番に積む作業だ。