コードは語らない。ADRが「沈黙するアーキテクチャ」を救う
コードレビューで「なぜこの実装になったのか？」を問い、数ヶ月前の自分や同僚が「……さあ、当時の状況は覚えていないが、とにかくこれで動いたんだ」と答える。この瞬間、君のプロジェクトの「腐敗」は加速している。
コードは「How（どう書いたか）」しか語らない。しかし、アーキテクチャの真髄は「Why（なぜそうしたのか）」にある。この「Why」をリポジトリ内に封じ込め、GitHubというプラットフォームを最大限にハックして、設計の意思決定プロセスをコード化する。それが Architectural Decision Records (ADR) を極めるということだ。
—
1. なぜコードレビューだけでは「腐敗」を止められないのか
コードレビューは、あくまで「現在のコードの状態」に対する検閲である。しかし、アーキテクチャの変更は、コードの行数ではなく「構造的な決断」として発生する。
- コンテキストの蒸発: PRのコメントは数ヶ月後にはGitHubの検索の海に沈む。
- 暗黙の制約: 「なぜこのライブラリを導入したのか」「なぜこのパターンを避けたのか」という制約が共有されないと、次の開発者は無意識にその制約を破り、技術的負債を積み上げる。
- 意思決定の非可視化: 誰が、どのようなトレードオフを検討したのかが残らない。
ADRは、この「設計のコンテキスト」をコードと共にGit管理することで、数年後の自分自身を救うための「タイムカプセル」となる。
—
2. ADR運用の最適解：GitHubを「設計のプラットフォーム」にする
ADRを運用する際、単なるMarkdownファイルを置くだけでは足りない。GitHubの強力なCI/CDパイプラインと、GitHub Actions、そしてAPIを駆使して「設計の議論」を自動化する。
A. Templateによる「意思決定の型」の強制
`docs/adr/templates/decision-template.md` を作成し、GitHubの `ISSUE_TEMPLATE` や `PULL_REQUEST_TEMPLATE` と連携させる。
ADR-XXX: [タイトル]
Status
Proposed/Accepted/Superseded
Context
なぜこの決断が必要だったのか。背後にあるビジネス上の制約や技術的課題。
Decision
何を採用したのか。
Consequences
- 利点（Positive）
- 欠点（Negative）
- 今後のリスク
B. GitHub ActionsによるADRの守護神化
ただ書くだけでは意味がない。ADRが更新されたら、必ず関係者に通知し、承認プロセスを強制する。以下のGitHub Actionsスクリプトは、ADRが変更された場合にのみ発火する「レビュー強要ロジック」の一例だ。
.github/workflows/adr-enforcer.yml
name: ADR Enforcer
on:
pull_request:
paths:
- ‘docs/adr/’ # ADRディレクトリへの変更のみ検知
jobs:
validate-adr:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: ADR Integrity Check
run: |
# ADRのフォーマットとメタデータをチェックするカスタムスクリプト
# ステータスが “Proposed” のまま放置されていないか等を検査
python3 scripts/adr_validator.py –path docs/adr/
—
3. 極限のハック：ADRを「動くドキュメント」にする
上級エンジニアであれば、ADRをただの読み物にしておくのは怠慢だ。GitHub APIを叩き、ADRのステータスを自動的にリポジトリの状態と同期させる。
APIによるステータス同期スクリプト
例えば、ADR内で「特定ライブラリの採用」を決定した場合、`github-script` を活用して、そのADRの状態が `Accepted` になった瞬間に、リポジトリの設定（`CODEOWNERS` や `branch protection rules`）を自動更新する仕組みを作る。
// GitHub Actions内での活用例
const { data: adrContent } = await github.rest.repos.getContent({
owner: context.repo.owner,
repo: context.repo.repo,
path: ‘docs/adr/001-use-rust-for-core.md’
});
// ADRのステータスをパースし、AcceptedならCI設定を厳格化するAPIを叩く
if (adrContent.includes(“Status: Accepted”)) {
await github.rest.repos.updateBranchProtection({
// …ブランチ保護ルールをより厳格なものへ更新するロジック
});
}
—
4. 伝説のアーキテクトからの提言：ADR管理の心得
1. 「記録」ではなく「議論」をGitに残せ:
PRのBodyにはADRのMarkdownを貼り付け、議論そのものをGitHub上で完結させろ。そのPR自体が、将来的に「なぜそのADRが採択されたのか」を知るための最強のバックログとなる。
2. Supersededを恐れるな:
古くなったADRを修正してはいけない。常に新しいADRを切り、「001-XXXを廃止する」というADRを発行せよ。この「履歴の積み上げ」こそが、チームの知性の結晶である。
3. 自動化のやりすぎに注意せよ:
ADRの管理ツール（例: `adr-tools`）を導入するのは良いが、最終的な決定はCLIではなく「人間」が行う。自動化は「忘却を防ぐための強制力」としてのみ使え。
—
結論
GitHubは単なるソースコードの保管庫ではない。「組織がいかにして技術的な決断を下したか」という歴史を刻むためのデータベースである。
君のチームがコードレビューで疲弊し、設計の迷宮に迷い込んでいるなら、今すぐADRを導入せよ。そして、その運用をGitHub Actionsで自動化し、設計の意思決定までもが「CI/CDパイプラインの一部」として機能する高次元の開発環境を構築するのだ。
それが、現代のDevOpsにおける「腐敗」に対する唯一にして最強の対抗策である。