なぜ「コード」だけではシステムは腐敗するのか？：GitHubで完結させるADR運用術
エンジニアリングの現場において、最も恐ろしいのは「なぜこの設計になったのか」という「文脈の喪失」だ。
コードレビューでLGTMを出し合う日々。しかし、半年後に見返したコードの複雑な依存関係や、奇妙な例外処理を見て「誰が、何の意図でこれを書いた？」と頭を抱えた経験はないだろうか？
コードは「How（どう実装するか）」しか語らない。「Why（なぜその設計を選んだのか）」をコード以外の場所に追い出している限り、リポジトリは必ず腐敗する。今日から君たちが導入すべきは、ADR (Architectural Decision Records) をGitHubリポジトリの一部として組み込む運用だ。
—
1. ADRが「最強のドキュメント」である理由
ADRとは、重大な設計判断を記録する軽量なテキストファイルだ。WikiやConfluenceに書くのではない。コードと同じリポジトリの `/docs/adr` 配下に置くのだ。
- コンテキストの共有: 開発者がコードを見たとき、隣のファイルに「意思決定のログ」があれば、即座に背景を理解できる。
- PRとの不可分性: 設計変更の議論をPull Request（PR）で行い、その結論をADRとしてコミットする。これにより「コードの変更」と「意思決定の記録」が完全に同期される。
2. GitHubを活用したADR爆速運用フロー
ただADRを書くだけでは定着しない。以下の「仕組み」をチームにインストールせよ。
① `.github/ISSUE_TEMPLATE/adr-proposal.md` の活用
まずはテンプレートを作る。GitHubの `ISSUE_TEMPLATE` を使えば、新しい設計議論を始めるハードルが劇的に下がる。
ADR提案: [タイトル]
文脈
- なぜこの変更が必要か？
- 現在のアーキテクチャのどこがボトルネックか？
選択肢
- 選択肢A: …
- 選択肢B: …
決定事項
- なぜその選択肢を選んだか（トレードオフの明示）
② PR駆動のADR確定フロー
1. Issueで議論: 上記テンプレートでIssueを立て、議論を収束させる。
2. ADRのコミット: 結論が出たら、`/docs/adr/` にマークダウン形式でファイルを作成し、PRを出す。
3. リンクの貼付: 関連するコード変更のPR内に、「詳細はADR-00Xを参照」とリンクを貼る。
—
3. テックリードが教える「現場で震える」効率化ハック
ここからは、GitHubを極限まで使い倒すためのプロのテクニックだ。
神キーボードショートカット (GitHub UI)
- `t` キー: ファイル検索モードへ即移行。「ADR」と打てば設計判断へ即ジャンプ。
- `g` → `c`: コミット履歴へ。ここから設計がどう変遷したか追跡せよ。
- `Shift + ?`: 隠された全ショートカットを表示。これを使わないのは武器を持たずに戦場に行くのと同じだ。
必須ブラウザ拡張機能
- [GitHub File Icons](https://github.com/moshfeu/github-file-icons): ファイル形式をアイコンで見分ける。ADRファイルが一目で分かるようになる。
- [Refined GitHub](https://github.com/refined-github/refined-github): GitHubの標準機能を劇的に改善する。PRのレビュー負荷を減らす機能が満載。
設定の共有化：`.editorconfig` を制する
チーム間でインデントや改行コードが違う？論外だ。リポジトリのルートに `.editorconfig` を置き、全員の環境を強制的に統一せよ。
.editorconfig: チームの生産性を奪う「些細な修正」を撲滅する
root = true
[]
indent_style = space
indent_size = 2
end_of_line = lf
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true
ADR用フォルダはMarkdownのルールを厳格化
[docs/adr/.md]
max_line_length = 80
—
4. まとめ：コードは消えるが、意思決定は残る
優れた設計は、書かれた時点ではなく、「後から修正が必要になったとき」にその真価を発揮する。
ADRをリポジトリ内に置くことは、未来の自分や、まだ見ぬチームメイトへの最高の手紙だ。「なぜここをこう書いたのか」というナレッジをコードの隣に封じ込めろ。それが、腐敗知らずの強靭なリポジトリを築くための、唯一無二のエンジニアリングだ。
さあ、今すぐ `mkdir docs/adr` を実行し、直近の設計判断を書き出すことから始めよう。それが君のチームの「技術的負債」を「資産」に変える最初の一歩だ。