ADR README 中見出し要約
What is an architecture decision record?
- ADRは重要な設計判断とその文脈・結果を残す文書。
- 関連概念としてAD・ADL・ASR・AKMが定義されている。
- 本ドキュメントはADRの概要と作成法、参考先を素早く示すことを目的とする。
How to start using ADRs
- チームで決定の識別・意思決定・実行と浸透・共有・文書化の観点を話し合う。
- 決定ToDoリストや対話マッピング等の手法、コードレビューとの連携を推奨。
- 手順はWikipediaのArchitectural Decision項目に基づいている。
- ツールは自由に選んでよい（Google Docs、git、Jira、Wiki等）。
- チームの好みに合わせ、既存ワークフローに組み込むのがよい。
- 特定ツールを強制せず柔軟性を重視する。
How to start using ADRs with git
adrディレクトリを作成し、ADRごとにテキストファイルを追加してコミットする。- 内容は本リポジトリのテンプレートを参考に自由に記述する。
- バージョン管理と相性が良いシンプルな運用法。
File name conventions for ADRs
- 現在形命令の動詞句を使う（例: choose-database.md）。
- 小文字とダッシュ、Markdown拡張子を推奨。
- 可読性とコミットメッセージ形式との整合が狙い。
Suggestions for writing good ADRs
- 良いADRの特徴は根拠明示・単一議題・日付記録・不変性。
- Contextには組織状況・優先度・チーム特性を含める。
- Consequencesには影響・派生ADR・事後レビューを記述する。
ADR example templates
- Nygard版（簡潔）、Tyree/Akerman版（詳細）、Alexandrianパターン版など多様。
- ビジネスケース向け、MADR、Planguageベースなど目的別に選べる。
- リポジトリ内に各テンプレートへのリンクを収録。
Teamwork advice for ADRs
- 「何を書くか」より「なぜ書くか」を語りチームを導く。
- “Decisions”と呼ぶと記入範囲が自然に広がる傾向がある。
- 理論上は不変が理想だが、日付付き追記での「生きた文書」運用が実務的に有効。
Teamwork questions for ADRs
- 作成者・起票基準・非起票基準・ライフサイクル・承認基準を明確化する。
- 役割責任・ガバナンス・原則（bias for action等）も合意しておく。
- 各問いに対し例示回答を提示している。
Next step concepts for ADRs
- Arc42は文書化の「何を・どのように」に実用的に答えるフレーム。
- C4モデルは階層的な図（Context/Container/Component/Code）で構造を表現。
- ADRの発展学習先として紹介されている。
Architecture diagrams & views & viewpoints
- 図=view、viewの雛形=viewpoint、viewpointは特定の関心事と読者を持つ。
- ビジネス能力、C4、ERD、BPMN、IAM/RBAC/ABAC等の例を列挙。
- ユースケース図・配置図・データフロー図なども関連図として挙げる。
Fitness functions for decisions as code
- Fitness functionは決定遵守を自動検証する客観的チェック。
- 品質保証・規制対応・ガバナンスに有効で、AI LLMを活用可能。
- ArchUnit/ArchUnitTSでJava・TS/JSの構造ルールを検査できる。
Decision guardrails for pull requests
- Decision Guardianが該当コード修正時に関連決定記録をPR上へ自動提示。
- アーキ・データ・コンプラ・医療・セキュリティ等あらゆる決定に対応。
- 主要CIやpre-commitで動作するOSS（MIT）。
- 入門・テンプレ・深掘り記事、ツール、企業別ガイド、書籍、動画、Podcastを網羅。
- REMAP・DRL・IBIS・QOC等の関連手法も参照先として挙げる。
- DRF（Decision Reasoning Format）はADRを補完する構造化推論フォーマット。