コードベースは文書化されています。しかし、意思決定は文書化されていません。

適切に運営されている開発チームのほとんどは、コメント、README、APIドキュメント、型シグネチャ、docstringなど、妥当なコードドキュメントを備えています。コード自体が、システムが何を行うかを示すドキュメントの役割を果たします。コードベースを読む能力のあるエンジニアであれば、あらゆるコンポーネントの現在の動作を理解できます。

コードだけからでは理解できないのは、「なぜそのようにしたのか」という理由です。

なぜ認証サービスは、モノリス内のモジュールではなく、別のマイクロサービスになっているのでしょうか？ なぜデータパイプラインはストリーミングではなくバッチ処理を使用しているのでしょうか？ より人気のある代替ライブラリが存在するのに、なぜHTTPリクエストにこの特定のライブラリが使用されているのでしょうか？ なぜスキーマには、データが入力されているにもかかわらず一度も読み取られないlegacy_statusというカラムがあるのでしょうか？

これらの質問にはそれぞれ答えがあり、その答えは過去のある時点で議論され、討論され、決定されたものです。その議論は、おそらくSlackのスレッド、ミーティング、あるいはPR（プルリクエスト）のコメントで行われたのでしょう。決定が下され、コードが書かれ、そしてその意思決定の理由は消え去ってしまいました。

意思決定が失われることの代償

決定の背後にある理由が失われると、2つのことが起こります。

新しいエンジニアが、チームがすでに犯した過ちを繰り返します。 認証サービスがなぜモノリスから分離されているのかを知らないエンジニアは、それらの統合を提案し、概念実証（PoC）の構築に1週間を費やし、その後のレビューで、2年前に苦労して発見された遅延問題のために分離されていることを知るかもしれません。その理由が文書化されていなかったために、その1週間は無駄になってしまいました。

解決済みの決定が再審議されます。 誰かがデータパイプラインについて「バッチかストリーミングか」という疑問を提起します。チームはミーティングでそれについて議論を重ねます。その途中で、誰かがこれは1年前に議論され、ストリーミングにはインフラの変更が必要であり、それに見合うほどの遅延改善は得られないという結論に達していたことを思い出します。以前の決定とその理由が見つけられなかったために、そのミーティングは無駄になってしまいました。

これら2つのコストは、その瞬間には見えません（通常の技術的な議論のように見えます）。しかし、蓄積されると膨大なものになります（同じ決定が何度も議論され、歴代のエンジニアによって同じ間違いが繰り返され、誰かが新しくシステムに触れるたびに、同じコンテキストをゼロから再構築することになります）。

意思決定ドキュメントとはどのようなものか

意思決定ドキュメントは、大げさなものである必要はありません。必須の要素は以下の通りです：

問い。 何が決定されようとしていたのか？ 明確で検索可能な問いとして表現します。

検討された選択肢。 どのような代替案が議論されたのか？ 簡単なリストであっても、デフォルトで選ばれたのではなく、現在の手法が選択されたものであることを示すため、価値があります。

決定。 何が選ばれたのか？

理由。 なぜこの選択肢が選ばれたのか？ どのようなトレードオフが受け入れられたのか？ 決定を再検討するためには何が変わる必要があるのか？

日付と参加者。 これはいつ決定され、誰が関わっていたのか？

このフォーマットは、アーキテクチャ意思決定記録（ADR：Architecture Decision Record）と呼ばれることもあり、これを継続的に使用しているチームは、意思決定の再審議やオンボーディングの摩擦が大幅に減少したと一貫して報告しています。

自動化の観点

意思決定ドキュメントにおける課題は、すべてのドキュメントと同様です。誰かがそれを書く必要があり、決定した瞬間は、誰もそれに関するドキュメントを書く気にならない瞬間である、ということです。

自己執筆型ドキュメントは、実際に決定が行われたソースから決定事項をキャプチャできます。チームが2つのアプローチを議論して結論に達したSlackのスレッドを、自動的に意思決定記録として要約することができます。アーキテクチャの選択肢を議論したミーティングの書き起こし（トランスクリプト）から、構造化されたドキュメントを作成できます。一見わかりにくいデザインの選択を説明したPRの説明を、より広範な決定履歴に関連付けることができます。

決定はすでに行われています。議論はすでに起きています。不足しているのはキャプチャ（記録）することです。既存のチャネルからの自動キャプチャは、エンジニアに事後に決定事項を書き留めるよう求めるよりも、はるかに信頼性が高くなります。

よくある質問

小さな決定に対して、これはやりすぎではありませんか？ すべての決定に正式なドキュメントが必要なわけではありません。基準としては、新しいエンジニアがその仕様を目にしたときに「なぜこのようにされているのだろう？」と尋ねることが予想される場合、その理由は文書化されるべきです。基本的なアーキテクチャ、技術の選択、および重大なトレードオフに関する決定は、ほぼ常にこれに該当します。

意思決定ドキュメントはどこに置くべきですか？ システムドキュメントと並べて、検索可能で、関連するコードやシステムにリンクされている場所に配置します。エンジニアリングWikiから独立した意思決定ログであっても、ないよりはマシですが、関連するシステムドキュメントと統合されている決定事項の方がより有用です。

過去の決定を遡って文書化するにはどうすればよいですか？ 最も摩擦を生んでいる決定から始めましょう。つまり、最も頻繁に再審議されるものや、新しいエンジニアが最も頻繁に質問するものです。それを覚えている人々から理由を聞き出して書き留め、古い決定については、確実な決定事項としてではなく「再構成されたもの」としてマークする必要があるかもしれないことを受け入れましょう。

関連の読み物：バス係数、属人化された知識の隠れたコスト、ドキュメント負債。 関連ページ：自己執筆型ドキュメント、意思決定ログ、開発チーム向け。