この記事は、CYBOZU SUMMER BLOG FES ’25の記事です。
本記事の狙い
こんにちは、iOSエンジニアの内田です。
みなさんは自信を持って意思決定を行えていますか？
「なぜこの決定をしたのか、あとからわからない」
「チームメンバーに意思決定を説明しても、うまく伝わらない」
このような悩みを抱えている方は少なくないのではないでしょうか。
そんな方にお勧めしたいのがADR（Architectural Decision Record）です。
社内にADRを運用しているチームがあります。僕はそこに加わり、「良いADRとは何なのか」がわからない状態から始まりましたが、試行錯誤を重ね、今では自分でも実践し運用できるようになりました。
その過程で思ったよりもハマりがちなアンチパターンがあることに気づいたり、質の高いADRを書く技術を身につけることで意思決定の質を向上させるだけでなく、技術的卓越にもつながると実感しました。
この「技術的卓越」とはアジャイル宣言の背後にある原則で以下のように述べられている、アジャイル開発を実践する中で僕が目指しているいるものです。
技術的卓越性と優れた設計に対する
不断の注意が機敏さを高めます。
本記事では僕がADRの実践を通じて学んだことをお伝えし、意思決定に自信を持てず不安な人が、自信を持って説明・提案できるようになることを目指します。
この記事のターゲットとアウトカム
ADRの質を高めたい人
- ADRをすでに書いているが、いまいち自信が持てない、形骸化している
- ADRに興味があるが、どう書いたら良いかわからない
→ 自分のADRの質を高めるための改善点を見つけられる
意思決定に自信を持ちたい人
- 意思決定の妥当性に自信が持てず不安になる
→ 意思決定を自信を持って説明・提案できるようになる
- 意思決定をチームメンバーに説明する際、うまく伝わらない
→ 説明・提案に不足している要素に気づき改善できる
目次
なぜ今ADRが重要なのか
そもそもADRとは
ADRは、ソフトウェアアーキテクチャの重要な決定を記録する文書です。
単なる設計書ではなく、なぜその決定をしたのか（Why）に焦点を当てた意思決定の記録です。
ADRを作成することで
- 意思決定の質が高まり、良いフィードバックサイクルを回し学習効果を高められる
- 技術的卓越につながる
という効果があります。
ドキュメントの重要性が高まっている
アジャイルマニフェストに
包括的なドキュメントよりも動くソフトウェアを
とありますが、ドキュメントが不要というわけではありません。ドキュメントの重要性が高い状況もあるわけです。
近年は
- 開発組織の大規模化
- 生成AIの進化
という変化が起きているため、ドキュメントの重要性が高まっていると考えています。
そしてこのドキュメントに意思決定を質高く記録するためにADRが有効であり、ADRの重要性も高まっているというわけです。
今なら生成AIにADRを書かせれば良いのでは？
「今なら生成AIが進化しているんだから、ADRも生成AIに書かせれば良いのでは？」と思う方もいるかもしれません。
しかし少なくとも現時点では、ADRに関しては難しいというのが僕の結論です。
コードベースからはADRに必要な要素は読み取れないためです。
コードベースは複数の選択肢の中から意思決定し選択されたものが残っています。
意思決定の理由はビジネス上の都合だったり、開発者の技術や好みといったものが影響しているはずです。
しかし意思決定の理由や、そもそも検討していた別の選択肢はコードベースには残っていないことが多いです。
「コードコメントには Why notを書こう」というt_wadaさんの言葉もありますが、『ソフトウェアアーキテクチャの基礎』には以下のような記述があり、ADRはさらにこの考えをエクストリームに突き詰めたものだと考えています。
ADR の決定セクションの最も強力な側面には、アーキテクトがHowよりもWhyに重点を置けるという点がある。ある決定がなされた理由を理解することは、何かがどう機能するかを理解することよりもはるかに重要だ。ほとんどのアーキテクトや開発者は、コンテキスト図を見れば物事がどのように機能するかを特定できる。しかし、なぜその決定がなされたのかは図だけでは特定できない。ある決定がなされた理由と、その決定に対応する正当な理由を知ることは、問題のコンテキストをよりよく理解するのに役立ち、問題が発生する可能性のある別のソリューションへのリファクタリングによるミスを回避することに繋がる。
また生成AIの仕組みから理由を考えることもできます。
生成AIはコンテキストを与えて圧縮する装置です。
一方でADRはコンテキストを創造して記述するためのものです。
そのためそもそも生成AIは新たにコンテキストを創造するADRには不向きというわけです。
ADRはいつ、何のために、何を書くのか
ではそんなADRにはどのようなことを書いたら良いのでしょうか。
僕が実践する中で重要だと感じたポイントを中心に説明します。
いつ書くのか
トレードオフを伴う意思決定を行う必要があるときに記述します。
遅延させることができない今必要な意思決定を、決定が迫られた状況を踏まえて説明します。
また検討メモではないため、トレードオフが伴わないなら書く必要もありません。
何のために書くのか
主に以下の目的があります。
- 意思決定の経緯・背景を正確に理解するため
- 意思決定の妥当性に自信を持つため
- 将来的にふりかえりより良い決定をするため
何を書くのか
特に以下の項目が重要です。
- 意思決定が必要になったコンテキスト
- 各選択肢のトレードオフ
- 意思決定において重視したポイント
フォーマット例
僕たちのチームでは以下のフォーマットでADRを記述しています。
- Context
- どのような状況で決定を迫られているか明確にし、中立的に事実を記述する
- Decision
- どのような決定を行ったか記述する
- Basis of the Decision
- 決定がなされた理由を理解するのに役立つよう、決定の根拠を記述する
- Consequences
- 決定による影響や、比較・検討した内容について記述する
- Compliance
- 決定が順守されていることを確認する方法を記述する
実践する中で見えてきたアンチパターン
フォーマットを見ると、「意思決定するならそれくらい考えてる、書ける」という気持ちでした。
しかし…実際ADRを書いてみると、思った以上に暗黙的な部分があり相手に伝わらず大苦戦。
実践する中で、いくつか典型的なアンチパターンが見えてきたので紹介します。
1. この意思決定が今必要な理由がわからない
コンテキストで今この意思決定が迫られている状況を説明したいのですが、これが意外と暗黙的になります。
複数ある選択肢を選ぶ際にはコンテキストが重要なので、冒頭のコンテキストをしっかり書けるかどうかで割と勝負が決まる感さえあります。
そのため「この部分ADRが必要だけど書きやすいから試しに書いてみて」と学習目的で他の人にADR作成を任せると、そもそもなぜこのADRを書く必要があるかという状況がうまく伝わっておらず、レビュー段階でそもそものスタート地点が違うなどという話になり得ます。
よほどうまく伝えないと、あとから「こういう話があるからそれは考慮しなくてよかったです、ごめんなさい！」という状況も…
2. この意思決定が適切だと考える理由がわからない
意思決定が適切である、妥当であることを伝えるためには
- 各案のトレードオフを比較し
- トレードオフを踏まえた上で決定理由、重視ポイントを説明する
という作業が必要です。
しかしトレードオフの比較をせず、カタログスペックのように各案の特徴やメリット、売り文句を並べるだけで、比較をせずに結論を出しており決定理由がわからないことが案外あります。
生成AIに周辺情報をほとんど与えずにADRを書かせると、プロダクトの事情などを全く踏まえずに結論を出し、このパターンになることが多いです。
3. 世の中で最も良い選択肢を生み出そうとしてしまう
ADRは「自分は（チームは）この時こう考えた」という、意思決定を記録するためのドキュメントです。
しかしトレードオフを比較し良い決定をしなければと考えると、「あの人ならもっといろんなことを考えて素晴らしい案を出すのでは…」などと考え始めてしまい、自分の能力を超えた選択肢を生み出さなければならないような気持ちになり手が止まってしまうことがありました。
自分が持ってない知識は無理をしようとないものは絞り出せないので、自分の考えを整理して記述し、あとはレビュー事に他のチームメンバーの力を借りると割り切りましょう。
重要なのは、レビューの時に自分の考えに対して説明責任を果たせることです。
…とはいえ生成AIが進化してきているので、生成AIの力を借りて調べられるレベルは前提にしないといけない状況にもなってきましたね。
生成AIの回答を鵜呑みにするのもいけないけど、使わないのも良くない、難しい。
例：飲み会の日程調整
アンチパターンを理解してもらうため、意思決定の例を使って考えてみましょう。
みなさん日々意思決定はしてるはずで、たとえば飲み会の日程調整だって立派な意思決定です！
今度の会社の飲み会、飲み会幹事を任されたAくんが日程調整のために参加できる日を聞いて回ったら、こんな感じになりました。
- 候補日1（金曜日）: 部長と主任が参加できない
- 候補日2（水曜日）: 主任と新人が参加できない
- 候補日3（月曜日）: 課長が参加できない
Aくんは結果を見て
「こういう日程調整の結果だったので、候補日3に開催します！」
とアナウンスしました。
しかしなんで候補日3になったんでしょうか？
- 参加できる人数が一番多いから候補日3？
- 役職が高い部課長が参加できる候補日2にするべきでは？
- お店がその日しか取れないから？
- 候補日1の方が金曜日だから良くない？
- 飲み会は実は新人歓迎会？
この日程調整が「全員参加は難しいから、参加できない人に納得してもらうための意思決定である」という状況だとすると、意思決定の理由は色々推測できるし、他の候補日じゃダメな理由がわかりませんね。
アンチパターン「2. この意思決定が適切だと考える理由がわからない」の典型例です。
もしここに「野球ファンが多い職場で、月曜日は野球中継がないから飲み会開催日として好まれる」というコンテキストが添えられていれば、意思決定の理由がわかるようになります。
実はこの例、アンチパターン「1. この意思決定が今必要な理由がわからない」も踏み抜いていたのです。
「野球チームが日曜日に優勝を決めたら、翌月曜日は寝不足で飲み会には向いてないかもしれない…」など、自分の能力外のことまで考え始め日程調整ができなくなったら、アンチパターン「3. 世の中で最も良い選択肢を生み出そうとしてしまう」ですね。
飲み会（と野球）を例に出しましたが、仕事における意思決定でも同じことが言えるんです。
ADRを書く時のTips
このような色んなアンチパターンを踏み抜き四苦八苦したADR実践・運用でしたが、おかげでADRを書く時のTipsも見えてきたので紹介します。
コンテキストを合わせてから書き始める
例からもわかる通り、意思決定において結論はその意思決定が必要に迫られた状況から導かれるものです。
コンテキストと意思決定は対応しているということです。
そのためコンテキストの認識が揃っていないと、そもそも意思決定の議論のスタート地点が違っており、せっかく書いたADRもちゃぶ台返しのようなレビューになってしまいます。
ADRは自然言語で書くドキュメントなので、書く方もレビューする方もコストが高くなります。
そのため事前にコンテキストを合わせてから書き始めるのが良いです。
せめてアウトラインくらいの段階で方向性が揃っているか確認するのが良いでしょう。
また体裁が整っていないと伝わるものも伝わらなくなるので、レビュー時はまず体裁を整える、意思決定の中身を議論するのはそのあとという順番が良いと感じます。
なおアウトラインをまとめた時に、意思決定に必要なコンテキストや決定理由がちゃんと書いてあれば、あとは生成AIにそれら食わせると、ADRの文章としてまとめる作業はだいぶ精度良くやってくれそうです。
違うなというもの含め各案に肩入れして考えてみる
複数案は確実にあるけれど、別にどれでもいいような気がするなーという気持ちになることがあります。
そういう時には、多分違うだろうというものも含めて各案に肩入れして考えてみることをお勧めします。
この選択肢を選ぶ人がいるとしたらどういう状況だろうかと、無理矢理にでも考えてみるのです。
そうすると暗黙的だったコンテキストが浮かび上がってくることがあります。
また見落としていた情報に気づいて、ADRを書く前は直感的にこれだろうと思っていた結論が変わることもあります。
本当にどれでもいいって状況ももちろんありますが、各案に肩入れして考えてみると思っていたより見落としが多いことに気づけるかもしれませんよ。
またこの部分は、世の中の広い知識を持っている生成AIが活用しやすいポイントだとも感じます。
各案それぞれについて、どのような強みがあるのか聞いてみると参考になる回答が出てくるかもしれません。
結論を批判的に考える
アンチパターン「2. この意思決定が適切だと考える理由がわからない」に効くTipsです。
「○○を重視しこの選択肢にします」と結論を出したあと、その決定理由だと他の選択肢でも良いと言えてしまわないか批判的に考えることをお勧めします。
案外、他の選択肢を選ぶ根拠にもできる決定理由になっていることがあります。
そうなってることに気づいたら、選んでいないものと選んだものとの間にある差を考えてみましょう。
暗黙的な何かが眠っていたり、もしかしたら別の選択肢でも問題ないのかもしれません。
トレードオフ分析の結果を表にまとめる
各案のトレードオフを分析した結果を、表としてまとめることをお勧めします。
表にすることで一覧性が上がり、あとから見返す時に理解しやすくなります。
また表にした時に、全ての比較項目で同じ分析結果になっている選択肢が複数あったら、何か検討漏れがある兆候です。
- 比較項目が不足してる
- 妥当じゃない選択肢が挙げられている
といった可能性が考えられるので、暗黙的な何かが隠れていないか考えてみるのが良いです。
ADRを実践・運用して実感した効果
最後にADRを実践・運用してみて実感した効果を紹介します。
いかに自分が手癖で設計していたかを痛感
意思決定理由を説明しようとした時に
- あの本がそう言ってるから…
- こういう設計原則があるから…
- これまでこうしてたから…
という説明しか出てこないことが多く、いかに自分が普段手癖で設計していたか気づき、正直ショックを受けました…
しかしADRと向き合うことで、ちゃんと説明のために必要な知識や語彙力は学習済みで、意思決定が必要な状況を分析しそれらの知識を上手く引き出せるようになったとも感じます。
技術書に書かれていることや、カンファレンスで紹介されるベストプラクティスは選択肢にはなるけれど、意思決定の理由ではない、意思決定理由はそれを迫られたコンテキストに眠っているのです。
書いてみると当たり前のことだと感じますが、「これはもはや常識」と疑わずにいる領域が予想以上に広かったことを理解しました。
過去の設計の意図が理解できた
コードベースを読む中で過去の設計の意図が気になった部分がADRで残されていたため、理解できた機会が何度かあります。
コードベースの理解の補助となり、オンボーディングが捗りました。
また設計を変更する際にも、ADRに考慮が必要な事情が残されていたため、デグレ・手戻りを防げたことがあります。
一方で全てうまくいっているわけでもなく、
「この部分はこういう意図ありそうだけどどうだろ？」
「確か当時こういう話をしたはずなんだけど…ADR残ってないですね」
というやりとりも何度かありADRを残すべきタイミングの見極めの難しさを感じ、より良いADR運用のため頭を悩ませています。
意思決定に必要な要素の理解が深まった
良い意思決定のためには何が必要なのか、ADRを通して向き合うことができたため、意思決定に必要な要素の理解が深まりました。
結果として、普段のレビューや検討をより効率的に行えるようになったとも感じています。
「要はバランス」を見極める力が高まる
コンテキストを分析し、最善の意思決定をする力が身についてきていると感じます。
これはつまり「要はバランス」と言われる部分に対して、自身のコンテキストを見極めバランスを取った決定をする力です。
結果まで出たものをあとからふりかえり、どのようなコンテキストだからその結果になったかを分析することは比較的容易です。
しかし今から行う意思決定がコンテキストに対して適切なのか、目の前に広がるコンテキストを最大限理解し、バランスを見極めることはとても困難です。
生成AIの進化によって具体的な知識を入手することの難易度が下がってきている時代においては、この「要はバランス」を見極める力が最も重要な技術力なのではないか、目指すべき技術的卓越なのではないかと感じます。
この力があれば生成AIに何を聞くべきかも明確になり、うまく利用できるようになったのではと感じます。
まとめ
ADRの実践を通じて意思決定の質が上がり、コンテキストを踏まえ最適な判断を下す力がつくことを実感しました。
これは生成AIの時代において必要な「要はバランス」を見極める力を高め技術的卓越につながると実感しているため、ADRと本気で向き合うことをお勧めしたいです。
コメント