なぜあなたのコードは「腐敗」するのか？GitHubで設計の魂を残す「ADR」運用術
こんにちは。現場で日々、複雑なシステムのメンテナンスやデリバリーの最適化に奔走しているエンジニアです。
GitHubでコードを書き、PR（プルリクエスト）を重ねる日常。しかし、ふと立ち止まって「なぜこの設計にしたんだっけ？」と迷ったことはありませんか？あるいは、チームメンバーが増えた途端に、過去の苦労の末に決まった設計が、無知な変更によって崩されていく……そんな「リポジトリの腐敗」に頭を抱えたことはないでしょうか。
今日は、そんな悲劇を未然に防ぐ、「Architectural Decision Records (ADR)」という強力な武器を、GitHub上でいかにスマートに運用するかを伝授します。これをマスターすれば、あなたのリポジトリはただの「コード置き場」から「設計の歴史が宿る資産」へと進化します。
—
1. なぜ「コードレビュー」だけでは足りないのか
GitHubのPR機能は素晴らしいですが、「結果」の議論には強くても、「文脈」の保存には向いていません。
- 「なぜこのライブラリを採用したのか？」
- 「なぜあえてこの複雑なパターンを選んだのか？」
- 「検討した他の代替案は何か？」
これらはコードの中にコメントとして書くには重すぎますし、PRのコメント欄は時間の経過とともに埋もれてしまいます。結果、数ヶ月後に「なんだこの設計は、書き直そう！」という悲劇的なリファクタリングが繰り返されるのです。
ADR（Architectural Decision Records）は、この「設計の決定」を短いドキュメントとして記録する手法です。コードと一緒にバージョン管理することで、常に「今の設計の根拠」を参照可能にします。
—
2. ADRの「Hello World」：まずは準備を整える
難しいことはありません。GitHubリポジトリの中に `docs/adr/` というディレクトリを作るだけです。これがあなたのチームの「設計の聖域」になります。
ステップ1：テンプレートを用意する
まずは、誰もが同じ質で記録を残せるよう、`templates/adr-template.md` を作成しましょう。
ADR 001: [タイトル]
- 日付: 202X-XX-XX
- ステータス: [提案中 / 承認済み / 非推奨]
文脈 (Context)
なぜこの決定が必要なのか。どんな課題を解決したいのか。
検討した選択肢 (Options)
1. 選択肢A
2. 選択肢B
決定 (Decision)
どの選択肢を選んだか。なぜそれを選んだのか。
結果 (Consequences)
この決定によって生じるメリットと、受け入れなければならないトレードオフ。
ステップ2：最初のADRを書いてみる
例えば、「認証基盤にAuth0を採用する」という決定なら、`docs/adr/0001-use-auth0-for-authentication.md` のように保存します。
—
3. GitHubで「議論を完結させる」最強の運用ルール
ADRを書くだけでは意味がありません。GitHubの力を借りて、「決定プロセス」を可視化しましょう。
ルール1：ADRは必ずPRで提案する
ADRの変更は、必ず `docs/adr/` 配下のファイル編集としてPRを送ります。
- PRのタイトル: `ADR: [案] 認証基盤の選定について`
- 議論の場: このPRのコメント欄こそが、設計の議論の場です。コードの実装前に「方向性」を合意します。
ルール2：READMEからリンクを貼る
リポジトリのルートにある `README.md` に「Architecture Decisions」というセクションを作り、ADRの一覧へリンクを貼ってください。
これだけで、新しくチームに入ったメンバーが「このプロジェクトの設計思想」を3分で把握できるようになります。
ルール3：ステータスを更新する
もし後に「やっぱり別のライブラリに移行しよう」となったら、古いADRを削除してはいけません。
- 新しいADRを作成し、古いADRに「Deprecated（非推奨）」と追記し、新しいADRへのリンクを貼ります。
- 「なぜ過去の判断が間違っていたか」を記録することこそが、チームを強くする最大の知見なのです。
—
4. 最後に：設計は「生き物」である
ADRを導入すると、最初は少し「面倒だな」と感じるかもしれません。しかし、半年後に「あの時の判断は正しかったんだ」と自信を持って言える瞬間、あるいは「なるほど、このトレードオフがあったから今の形なのか」と納得できる瞬間、あなたはADRの真の価値を知ることになります。
GitHub上のPRはコードだけでなく、「あなたの知性」を保存する場所です。
明日から、小さな決定一つひとつを「ADR」として残してみてください。あなたのリポジトリから「腐敗」が消え、エンジニアたちが迷わず開発できる素晴らしい環境が育っていくはずです。
何か分からないことがあれば、いつでも聞いてくださいね。一緒に、最高の開発体験を作り上げていきましょう！