adr

アーキテクチャ決定記録

Olaf Zimmermann の研究と MADR（Markdown Architectural Decision Records）手法に基づき、アーキテクチャ決定記録（ADR）の作成と管理に関する専門的なガイダンスを提供します。

このスキルの仕組み

このスキルを呼び出すと、ADR のライフサイクル全体を通してガイドします。

1. 準備状況の評価 — 決定を記録する準備が整っているかを評価します（START 基準）
2. 作成 — MADR テンプレートを使用し、アンチパターンを回避しながら、適切に構成された ADR を作成します
3. 品質評価 — ECADR の「完了の定義」基準を使用して、完全性を確認します
4. ライフサイクル管理 — ADR ログを維持し、古くなった記録を置き換え、決定のステータスを追跡します

基本理念

「決定を早く下しすぎないでください。柔軟性が損なわれます。遅すぎるのもいけません。」

ADR は決定の記録であり、設計図やポリシーではありません。アーキテクチャ上重要な選択の根拠を記録します。具体的には、問題の背景、検討した代替案、適用した基準、受け入れた結果です。優れた ADR は、あらかじめ決められた結論を売り込むものではなく、トレードオフのバランスを取ったエグゼクティブサマリーです。

このスキルを使用する場面

• アーキテクチャ上の決定について、新しい ADR を作成する
• 決定を記録する準備が整っているかを評価する
• 既存の ADR の完全性と品質をレビューする
• プロジェクト用の MADR テンプレートを作成またはカスタマイズする
• 要件がアーキテクチャ上重要かどうかを評価する
• ADR ログを管理する（決定の置き換え、非推奨化、関連付け）
• ADR のベストプラクティスについてチームをトレーニングする

コマンドモード

引数	アクション
create	対話形式で新しい ADR を作成します
review	品質基準に照らして既存の ADR を評価します
check-ready	START 基準を使用して、決定の準備状況を評価します
check-done	ECADR 基準を使用して、ADR の完全性を評価します
template	記入できる空の MADR テンプレートを出力します
list	ADR ログの整理と維持を支援します
(no args)	コンテキストに基づいて一般的な ADR ガイダンスを提供します

MADR テンプレート（クイックリファレンス）

# ADR-NNNN: [Short Title Describing Decision]

## Status
[proposed | accepted | deprecated | superseded by ADR-XXXX]

## Date
YYYY-MM-DD

## Decision Makers
[Who made or approved this decision]

## Context and Problem Statement
[1-3 paragraphs: What is the issue? Why does it matter?
Frame as a question when possible.]

## Decision Drivers
- [Driver 1: quality attribute, business constraint, or technical concern]
- [Driver 2]
- [Driver 3]

## Considered Options
1. [Option A — the chosen option]
2. [Option B]
3. [Option C]

## Decision Outcome
Chosen option: "[Option A]", because [justification referencing decision drivers].

### Consequences
- Good, because [positive consequence]
- Good, because [another benefit]
- Bad, because [accepted tradeoff]
- Bad, because [known limitation]

## Pros and Cons of Options

### Option A
- Good, because [advantage]
- Bad, because [disadvantage]

### Option B
- Good, because [advantage]
- Bad, because [disadvantage]

### Option C
- Good, because [advantage]
- Bad, because [disadvantage]

## Validation
[How will we verify this decision works? Code review, design review,
architectural fitness function, spike, etc.]

## More Information
[Links to related ADRs, RFCs, spikes, or external references.
Note confidence level and planned review date.]

主なフレームワーク

START — 準備完了の定義

ADR を作成する前に、以下の 5 つの基準すべてを確認します。

• S 関係者が特定され、参加可能である
• T タイミングが最も責任ある時点である
• A 代替案が特定されている（最低 2 つ）
• R 要件と背景が文書化されている
• T テンプレートが選択され、適用されている

ECADR — 完了の定義

ADR を承認済みとして扱う前に、以下の 5 つの基準すべてを確認します。

• E 設計が機能することを示す証拠がある
• C 少なくとも 2 つの代替案を比較するための基準が適用されている
• A 関連する関係者の合意がある
• D 文書化され、共有されている
• R 実現とレビューの計画が予定されている

ASR テスト — アーキテクチャ上の重要性

以下の基準に該当する要件については、ADR が必要です。

• ビジネスへの影響またはリスクが大きい
• 重要な関係者の懸念がある
• 現在のアーキテクチャからサービス品質が逸脱する
• 予測不可能または制御不可能な外部依存関係がある
• 複数のコンポーネントに影響する横断的な懸念がある
• チームにとって初めての実装である
• 過去に問題を引き起こした実績がある

このスキルが提供するもの

1. START 基準とチェックリストを使用した準備状況の評価
2. MADR テンプレートの生成（完全版と最小版）
3. ADR の草案にあるアンチパターンの検出（既知のアンチパターン 11 種）
4. ECADR の完了の定義を使用した品質評価
5. 決定の優先順位付けに向けたアーキテクチャ上の重要性の評価
6. ADR ログを長期にわたって維持するためのライフサイクルガイダンス