はじめに
最近色んな経験から、「なぜこの形になったのか」のような決定プロセスの記録がコードと同様に価値を持つんだなぁと気付きました。
私自身、残すべき記録は理解できているものの、残すタイミングや更新タイミングには迷っているところがあり、完ぺきではないですが、チームの開発生産性を高めるために残すべき記録の対象とその重要性について、まとめておこうと思います。
理想と現実、記録のメリット
「コードを読めば仕様と意図がわかる」というのは理想ですが、現実には不可能に近いと思っています。コードからは「How（どう実装されているか）」は分かっても、「Why（なぜその実装なのか、他の選択肢はなかったのか）」を読み取ることは困難だからです。適切な記録によって、以下のようなメリットを得られると思います。
- 新規メンバーのキャッチアップコストの削減
- 同じ議論を繰り返す、隠れたコミュニケーションコストの削減
- 意思決定の透明化によるチームの納得感向上
記録を残すべき対象
記録において重要なのは、何を決めたか（結果）だけではありません。より価値があるのは、その裏側にある「なぜそうしたのか（背景・文脈）」を残すことです。
これ以外にもあると思いますのが、主観で重要だと思うものを4つまとめました。
- アーキテクチャ・ライブラリの選定結果と、採用しなかった選択肢（ボツ案）
- UI/UXに関するデザインの意図と、「意図がないこと」の記録
- 実装を進めるうえで不足している情報（あるいは実装フェーズで決定した内容）
- 外部システム・APIの制約事項
アーキテクチャ・ライブラリの選定に関する記録
言うまでもなく、技術的な意思決定の根拠は将来のシステムの命運や実装スピードを大きく左右します。
- 残す理由:
- 「なぜこの設計思想なのか」や「なぜこのライブラリなのか」という問いに明確な理由を答えられるようにするため
- 数年後・数か月後の安全なバージョンアップや刷新の判断を補助するため
同様に、比較検討の末に「あえて選ばなかった理由」を残すことは、同程度重要だと最近思うようになりました。
- 残す理由
- 数年後の刷新の判断材料になるため：なぜ当時の環境でそのライブラリを選んだのかが分かれば、将来の移行判断が容易になります
- 「あえて選ばなかった理由（学習コスト、技術的制約など）」を記録し、同じ議論の繰り返しを防ぐため
UI/UXに関するデザインの意図 +「意図がないこと」の明文化
UI/UXにおける意図、そしてあえてこだわらなかった点を記録します。
- 残す理由
- 改善の心理的ハードルを下げるため：「ここは標準UIに従っただけでこだわりはない」というような記録は、後の担当者が安心してリファクタリングを行うための許可証になります
- あるいは、意図がないことを知ることで、エンジニアは副作用を恐れずにUIを洗練させることができるようになります
実装を進めるうえで不足している情報
実装を進めていくうえで、当初想定から抜けていたタスクやストーリーが出てくることがあります。また「具体的な処理方法は実装時に比較、検討する」といった進め方取ることもあると思います。
- 残す理由
- 「なぜこれが未実装・未検討なのか」を記録し、後続の担当者の迷いをなくし、余計なコンテキストスイッチを減らすため
外部システム・APIの制約事項
自分たちでコントロールできない「外部要因」への対応策を記録します。
- 残す理由
- トラブル対応の迅速化のため：「API側のバグ回避のためにここだけ特殊な処理を入れている」といった記録があれば、原因不明のバグ調査時間を大幅に削減できます
記録のコツとフォーマット
記録を形骸化させず、チームで運用し続けるための具体的な手法をまとめます（あくまで例なので、読者皆さんの環境に応じて読み替えてください）。
意思決定の標準フォーマットとしての「ADR」の活用
技術選定などの重要な決定には、ADR (Architecture Decision Records) を利用するのが効果的です。以下の項目をテンプレート化しましょう（具体的なテンプレートはAI君に頼めばちゃちゃっと出してくれるので省略）。
| 項目 | 内容 |
|---|---|
| 背景 (Context) | どのような課題があり、何が制約となっていたか |
| 決定 (Decision) | どう解決することにし、何を採用したか |
| 結果・影響 (Consequences) | その決定によるメリットと、受け入れたトレードオフ（妥協点・懸念点） |
記録に含めるべき必須要素
どのような形式であれ、以下の要素が含まれていることが望ましいと考えています。
- 当時の前提条件: スケジュール（納期が押しているかどうか）、当時の開発環境、その他制約
- 比較した形跡: 「A案・B案を比較して、〇〇の理由でAにした」というような情報が表としてまとまっているとなお良い
- 妥協したポイント: 「スピード優先のため、拡張性は一旦捨てた」といった、どうしても選ばざるを得なかった背景の情報
いつどのように記録を残すべきか
日々のコミュニケーション（フロー）に応じて記録を残すタイミングが変わると思っています。毎日、各開発者のコミュニケーション量が多ければ、記録を柔軟に変更するようなフローが必要だと思います。
ここでの「柔軟な変更フロー」とは、厳密なレビューを必要とするフローではなく、誰もが必要に応じて記録を残し、不要になれば簡単に削除できるフローです。ただし、1日2日で簡単に内容が入れ替わるような記録は残さず、あくまで長期的に変更されないであろう方針について記録すべきと考えています。
記録を残す先としては以下のような場所が挙げられます。これはプロジェクトの背景によって変わるので、読者皆さんの環境に応じて読み替えてください。
- GitHub Issue / PR: 実装時の葛藤や疑問点などを会話した記録を残す
- Slackの議論ログ: 盛り上がった議論の結論をドキュメントに数行で転記し、元のスレッドへリンクを貼る（貼る先はADRやドキュメント管理用サービスなど）
- MTG議事録: ステークホルダーとの合意形成の証跡を、ADRや個別のドキュメント管理サービスに追記する
まとめ
今までしっかりと記録を残す文化の無かったチームや大きな組織では、短期的には手間に感じるかもしれません。
しかし、数週間の短期～数年の長期間に渡って、コンテキスト（文脈）の保存はプロジェクトへの重要な投資です。未来の自分、そして未来のチームメイトのために、ぜひ「Why」を記録し始めてください。