はじめに
こんにちは、ログラスでエンジニアをしております、田中です（@kakke18_perry）。
開発組織では日々重要な技術的意思決定が行われますが、その背景や理由は時間とともに失われがちです。ログラスでもADR（Architecture Decision Record）導入前は、特定のライブラリ選定理由がドキュメントに記載されていなかったり、ドキュメントがチームごとに分散し、過去の意思決定を参照しづらい状態になっていました。
本記事では、この課題を解決するためにログラスが1年間運用してきたADRについて紹介します。
ADR導入以前のログラスが抱えていた課題
ADR導入以前、技術的なドキュメントや設計標準はNotionで管理されていました。しかし、いくつかの問題がありました。
- 意思決定理由の抜け落ち：特定のライブラリの選定理由など、「なぜそれを選んだのか」という重要な背景情報が、設計標準などのドキュメントに記載できていないことがありました。
- ドキュメントの分散：ADRに似たようなドキュメントがチームごとに分散されてしまい、プロダクトやチームを横断して過去の意思決定を参照することが困難な状態でした。
- 参照の困難さ：結果として、過去の技術的な意思決定を参照しづらい状態にあり、これは新しいメンバーが加わった際の説明コストの増加や、既存メンバーによる過去の経緯の再調査を発生させていました。
これらの状態は、個々の開発者が持つ「組織知」がブラックボックス化し、チーム間で共有されにくい状況を生み出していました。
ADR導入の「狙い」と、初期の設計方針
ログラスがADRを導入した狙いは、「どこに何の情報があるか分からない」という状態を解消し、中長期を見据えた開発を可能にすることにあります。
この目的のため、以下の2点に注力しました。
1. ADRを「意思決定の共通言語」にする
ADRの概念や運用ルールを浸透させる啓蒙活動を実施し、ADRを開発プロセスの一部として定着させました。また、分散していたドキュメントを一箇所に集約し、知識の分散や不明確さを防ぐことを目指しました。
2. ADRの「質」を高めるためのテンプレート設計
ADRの価値を高めるため、テンプレートの項目を工夫しました。テンプレートは『ソフトウェアアーキテクチャの基礎』に記載のものをベースに採用し、運用に合わせて変更を加えています。このテンプレート設計こそが、ADRを組織の技術的な知恵へと昇華させる鍵です。
ADRを「記録」から「組織知」に変えるテンプレート設計の工夫
ADRを「組織的な知恵」として機能させるため、テンプレートに意思決定の質を高める項目を組み込みました。
ログラスでは、『ソフトウェアアーキテクチャの基礎』に記載のものをベースにしつつ、以下の2点に注力してテンプレートを工夫しました。
1. 意思決定の「Why」を明確にする項目の必須化
書籍で「コンテキスト」として表現されるセクションにおいて、意思決定のプロセスを明確化するため、以下の項目を必須としました。
- 背景: 決定したい技術的な意思決定に関連する情報
- 課題: 技術的な意思決定が行われる前の現状の課題
- 対策案: 課題に対する案を複数提示
- 評価基準: 対策案からどの基準で決定をするか
この工夫により、「なぜそれを選んだか」という背景情報の抜け落ちを解決し、参照性が大幅に向上しました。
2. Notionプロパティを活用した横断検索性の向上
ADRの参照の困難さを解決するため、Notionのプロパティ（タグ付け機能）を積極的に活用しました。
タグ付けの活用: ステータス、著作、関連プロダクトなどの情報をNotionのプロパティで表現し、プロダクトやチームを跨いだ横断的な検索が容易になるように設計しています。
1年運用して見えた効果：チーム・プロダクトを跨ぐ横断的な「Why」の共有
ADRの導入とテンプレートの工夫を経て、ログラスでは以下の具体的な効果が得られました。
1. 意思決定の質の向上
ADRテンプレートの整備により、背景やその技術的な意思決定に何を求めているか、そして代替案との比較事項が適切に記載されるようになりました。これにより、意思決定のプロセスが明確化し、その質が向上しました。
2. 組織知の共有と参照性の向上
過去の意思決定について、プロダクトやチームを跨いで参照しやすくなりました。導入以前の課題であったドキュメントの分散による参照の困難さが解消され、「なぜこの技術を選んだか」という疑問に、誰でも即座に答えることができる状態が実現しています。
3. 議論への参画機会の拡大
以前はチーム内に閉じていたドキュメントや議論が、全体に公開されるようになったことで、チームを超えて誰もが意思決定の議論に参画できるようになりました。これにより、多様な視点からのフィードバックが得られやすくなり、より良い意思決定につながっています。
ADRを「生きたコンテキスト」に：AIとの連携で意思決定の速度を上げる
ログラスは開発においてAIを積極的に活用しています。詳細についてはAI活用に関する記事・登壇資料をまとめてますので、ご覧ください。
現状、開発で使っているAIツールからNotionのADRを直接参照することはほぼありませんが、今後AIが開発プロセスに深く関わるにつれて、過去のADRの情報が重要になると考えます。
AI連携への期待
ADRをAIに連携させることで、以下の点で意思決定や開発をサポートできると期待しています。
- 設計提案の質の向上: AIが新しい設計案を行う際、既存のADR（特に「要求事項」や「評価基準」）を参照します。これにより、過去の決定を踏まえた、より文脈に合った適切な設計の提案が可能になります。
- コード生成の最適化: 過去のライブラリ選定理由に関するADRを参照することで、単にコードを生成するだけでなく、組織の標準に沿ったコードの生成や設計提案が行えるようになります。
まとめ
本記事では、ログラスが1年間運用してきたADR（Architecture Decision Record）の取り組みを解説しました。
かつてあった「ドキュメントの分散」や「意思決定の理由の抜け落ち」といった課題は、以下の工夫によって解消されました。
- テンプレートによる質の向上: ADRテンプレートに背景、課題、対策案、そして評価基準といった項目を必須で組み込み、意思決定の「Why」を明確化。
- 横断検索性の確保: Notionプロパティを活用し、プロダクトやチームを跨いで過去の意思決定を容易に参照できる環境を整備。
このADR運用によって、意思決定のプロセスが明確化され、組織知の参照性が向上しています。
技術的な意思決定をADRでしっかりと記録しておくことは、未来の自分たちを助け、中長期的な開発の質を支える上で不可欠です。今後は、このADRをAIの知識ベースとして連携させ、意思決定の質と速度をさらに向上させることを目指します。
Discussion