半年後も、設計の理由を説明できるか

一つの文書へ背景、議論、現在の手順、将来案を集めれば、探しやすく見えます。ところが判断が変わるたびに、現在の仕様の途中へ古い議論が積み上がります。利用者は、結局いま何を守ればよいのか分からなくなります。

ここで現在の正しさと、過去の判断を分けました。仕様書は現在の契約を短く示し、意思決定記録（ADR）は、ある時点で何を比べ、なぜ選んだかを残します。

問い合わせ基盤では、失敗した処理を回復する方法として、出来事に応じて動く方式と、定期的に探す方式を比較しました。別の判断では、公開の自動化を完成させるために権限を追加する案と、自動化の範囲を狭める案を比べました。

現在の仕様だけなら、選ばれた経路しか見えません。ADRに捨てた案と理由があれば、利用量、権限モデル、運用体制が変わったとき、過去の結論を盲目的に守らず再評価できます。

後から別案へ移ったとき、古いADRの結論を書き換えると、当時なぜそう考えたかが消えます。古い記録は置き換え済みとし、新しいADRから変更理由を示します。

一覧や概要は生成できますが、判断の本文まで自動要約だけに任せると、重要な前提が落ちることがあります。現在状態の投影と、原文のDecision Historyを行き来できるようにします。

少人数なら口頭で済むと思いがちです。しかし一人が複数製品を見れば、半年前の自分も別の担当者です。外注先が変わる、AIが別のContextで作業する、緊急対応で順序が変わる。記憶だけでは引継げません。

すべての細かな実装へADRは不要です。後から戻すのが高い判断、複数の合理的な案があった判断、権限やデータの意味を変える判断を選びます。「なぜ」をもう一度調べる費用が、記録する費用を上回る場所から始めます。

仕様書に結論だけが残り、コードに実装だけが残ると、半年後に分からなくなるのは、なぜ別案を捨てたかです。将来の人は、今の仕様を否定したいのではなく、当時の制約がまだあるかを確かめたいだけかもしれません。そのためには、背景、選択肢、採った理由、受け入れた不利益、再検討する条件が短く残っている方が役に立ちます。

ADRは会議の逐語録ではありません。すべての発言を残すと、現在の仕様を探せなくなります。反対に結論だけでは、同じ調査が繰り返されます。Current Truthとして今の仕様を読みやすく保ち、Decision Historyとして当時の判断を変えずに残す。この二つを分けると、置換された決定も誤って現在の指示として使われません。

小さな組織では、記憶している人が一人だけという状態になりやすいからこそ、記録は重い手続きではなく継続の道具です。判断を変えるときも、古い記録を消さず、何が変わったために新しい選択をしたかを追加します。