1. 導入：技術選定の「なぜ？」を未来に残す
開発現場で「なぜこのライブラリを採用したのか？」「なぜこの構成にしたのか？」と悩んだことはありませんか？時間が経つと、当時の議論や背景は忘れ去られてしまいます。ADR（Architecture Decision Records）は、技術的な意思決定の経緯を短いドキュメントとしてリポジトリに残す手法です。これにより、新メンバーへの共有がスムーズになり、過去の議論を蒸し返す無駄な時間を削減できます。
2. 基礎知識：ADRとは何か
ADRとは、アーキテクチャに関する重要な決定事項を、Markdown形式のファイルとしてプロジェクト内に記録するものです。
重要なポイントは「決定したこと」だけでなく、「なぜその選択肢を選び、他の選択肢を捨てたのか（トレードオフ）」という背景を残すことにあります。単なる仕様書ではなく、チームの「意思決定の履歴書」と考えると分かりやすいでしょう。
3. 実装/解決策：ADRの書き方
ADRを作成する際は、以下のフォーマットを基本にすると一貫性が保てます。
1. タイトル：決定事項を簡潔に。
2. ステータス：提案中、承認済み、非推奨などの状態。
3. コンテキスト：どんな課題を解決するために検討したか。
4. 決定内容：何を採用したか。
5. トレードオフ：採用したことによるデメリットや、捨てた選択肢。
4. サンプルプログラム：ADRのテンプレート例
以下のコードをコピーし、プロジェクトの「docs/adr/」ディレクトリ内に「0001-use-postgresql.md」などの名前で保存して活用してください。
0001-データベースにPostgreSQLを採用する
ステータス
承認済み
コンテキスト
現在のプロジェクトでは、複雑なリレーションを持つユーザーデータを扱う必要がある。SQLiteでは将来的な拡張性と同時書き込み性能に不安があるため、RDBMSの選定が必要。
決定内容
データベースとしてPostgreSQLを採用する。
トレードオフ
- メリット：高度なSQL機能、JSONBによる柔軟なデータ構造、豊富なエコシステム。
- デメリット：SQLiteと比較してセットアップが複雑。インフラ構築コストがわずかに増加する。
- 捨てた選択肢：MySQL（今回はJSONBの操作性と堅牢性を優先し、PostgreSQLを選択した）。
5. 応用・注意点：現場で長く続けるコツ
ADRを運用する際の最大の敵は「書くのが面倒になること」です。以下の点に注意してください。
・軽量に保つ：長文を書く必要はありません。箇条書きで十分です。
・コードと共に管理する：Wikiや外部ツールではなく、ソースコードと同じGitリポジトリ内に置くことで、「コードと決定経緯が常に同期」されます。
・完璧を目指さない：全ての小さな変更を記録するのではなく、チームの方向性に影響を与える「大きな変更」に絞って記録しましょう。
ADRを導入することで、チームの意思決定の透明性が高まり、自信を持って技術を選べるようになります。まずは小さな決定から記録を始めてみてください。
コメント