# ADR（Architecture Decision Records）

## 概要

ADR はプロジェクトにおける重要な意思決定を記録するドキュメントである。
「なぜその判断をしたか」「他にどんな選択肢があったか」「どんなトレードオフを受け入れたか」を
将来の開発者（自分自身を含む）が追跡できるようにする。

"Architecture" と名は付くが、記録対象はアーキテクチャに限らない。
**要求・要件・仕様・設計・実装のあらゆるレベル** で下された意思決定が ADR の対象である。

## ADR の位置づけ（独立ルート文書）

本スキルでは、ADR は **独立したルート文書（`parent: null`）** として管理される。
特定のドキュメントの子ではなく、トレーサビリティチェーンの外側に位置する。

```text
主チェーン: REQ → ARCH/SPEC → IMPL/TST

ADR（独立）──── 任意のアイテムにリンク可能
  ├── REQ001 へ（要求レベルの判断）
  ├── ARCH003 へ（設計レベルの判断）
  ├── SPEC012 へ（仕様レベルの判断）
  └── IMPL007 へ（実装レベルの判断）
```

- ADR は `parent: null` のため、`links` が空でもトレーサビリティ検証をパスする
- ADR の `links` は **関連する任意のアイテム** を指せる（REQ, ARCH, SPEC, IMPL 等）
- 逆に、他のアイテムも ADR にリンク（`--links ADR001`）して判断の根拠を参照できる

この設計により、意思決定は発生したレベルに紐付けられ、
「なぜ」の追跡が特定の階層に制限されない。

## ADR の対象レベルと例

| レベル | 判断の例 | links 先 |
|---|---|---|
| **要求** | 「分散キャッシュはスコープ外とする」 | REQ |
| **要件** | 「NFRの性能基準をp99 1msに設定する」 | REQ/NFR |
| **設計** | 「DI で全コンポーネントを差し替え可能にする」 | ARCH/HLD |
| **仕様** | 「sync/async 判定をデコレーション時に固定する」 | SPEC/LLD |
| **実装** | 「SQLite の書き込みをキューで直列化する」 | IMPL |
| **技術選定** | 「シリアライザに MessagePack を採用する」 | REQ/ARCH 等 |

## ADR を作成するタイミング

以下のいずれかに該当する意思決定があったとき：

| トリガー | 例 |
|---|---|
| **技術選定** | 「シリアライザに MessagePack を採用する」 |
| **アーキテクチャパターン** | 「DI で全コンポーネントを差し替え可能にする」 |
| **トレードオフの受入** | 「sync/async 判定をデコレーション時に固定する」 |
| **互換性を壊す変更** | 「v2.0 で `run()` メソッドを削除する」 |
| **スコープ判断** | 「分散キャッシュは対象外とする」 |
| **不採用の代替案** | 「Redis キャッシュは検討したが、スコープ外とする」 |

逆に、以下の場合は ADR を書く必要はない：
- 自明な実装判断（標準ライブラリの使用、命名規約の適用等）
- 一時的な回避策（ADR ではなく IMPL の TODO に記録する）

## ADR の属性（status）

ADRアイテムは `status` 属性を持ち、決定の状態を管理する。

- `accepted` (デフォルト): 採用され、有効な決定
- `proposed`: 提案中（レビュー前）
- `deprecated`: 廃止された決定（現在は無効）
- `superseded`: 別の新しい ADR によって上書きされた決定

## フローでの ADR の扱い

### [A] 新規開発フロー

どの段階でも、上記トリガーに該当する判断があれば ADR を作成する。

```bash
# 要求レベルの判断
doorstop_ops.py add -d ADR -t "..." --header "スコープ外判断" --links REQ005

# 設計レベルの判断
doorstop_ops.py add -d ADR -t "..." --header "シリアライザ選定" --links ARCH001

# 仕様レベルの判断
doorstop_ops.py add -d ADR -t "..." --header "sync/async判定タイミング" --links SPEC003
```

他のアイテムから ADR を参照する場合：
```bash
doorstop_ops.py link ARCH001 ADR001
```

### [B] 変更フロー

既存の意思決定を覆す変更の場合：
1. 既存の ADR の `status` を `superseded` または `deprecated` に更新する。
   `doorstop_ops.py update ADR001 --status superseded`
2. 必要に応じて新しい ADR を作成し、新しい決定の理由を記録する。

### [H] 意思決定記録フロー

ユーザーとの議論・検討・レビューの結果として意思決定が確定したとき、
判断の背景・代替案・トレードオフを ADR に記録する。
詳細な手順は `flows/decision_record.md` を参照。

## ADR アイテムの記述テンプレート

アイテムの書き方や詳細なフォーマットについては、`references/item_writing_guide.md` の「ADR（決定）」セクションを参照すること。
