k2works/creating-adr

ADR 作成

アーキテクチャ決定記録（ADR）を作成・管理する。技術的意思決定のコンテキスト・決定内容・影響を構造化して記録する。

ADR の価値は「決定そのもの」ではなく「なぜその決定に至ったか」を残すこと。代替案と却下理由を含めることで、将来の見直し時に同じ検討を繰り返さずに済む。

ADR テンプレート

# ADR-NNN: タイトル

簡潔な説明（1 行で決定内容を要約）。

日付: YYYY-MM-DD

## ステータス

提案中 | 承認済み | 廃止 | 置換（ADR-XXX で置換）

## コンテキスト

この決定が必要になった背景・状況を説明。

- 現在の課題や制約
- 関連するシステムやサービス
- ビジネス要件

## 決定

**何を決定したか** を明確に記述。

### 変更箇所

具体的な実装変更がある場合は記載。

### 代替案

検討した代替案とその却下理由。

## 影響

### ポジティブ

- 良い影響

### ネガティブ

- 悪い影響や注意点

## コンプライアンス

決定が正しく実装されていることを確認する方法。

## 備考

- 著者: 担当者名
- 関連コミット: コミットハッシュ
- 関連 ADR: ADR-XXX

ステータスの種類

| ステータス | 説明 | |-----------|------| | 提案中 | レビュー待ちの ADR | | 承認済み | 採用された決定 | | 廃止 | 無効になった決定 | | 置換 | 別の ADR で置き換えられた |

作成の進め方

新規 ADR の作成

1. docs/adr/ ディレクトリ内の既存 ADR の最大番号を確認する
2. 次の連番でテンプレートに基づいて ADR を作成する
3. docs/index.md と mkdocs.yml を更新する

既存設計からの ADR 抽出

1. アーキテクチャ設計ドキュメントを読み込む
2. 主要な技術的意思決定を識別する
3. 各決定を ADR として記録する

途中から再開・更新

既存の ADR がある場合は docs/adr/ の内容を確認する。ステータス変更や新規 ADR の追記のみを行う。

Example:

ユーザー: 「フレームワークを変更する決定を記録したい」
回答: docs/adr/ の最大番号を確認し、次の連番で ADR を作成する。
      既存の関連 ADR があればステータスを「置換」に変更し、
      新しい ADR の「コンテキスト」に経緯を記載する。

注意事項

• 採番は 001 から連番。ファイル名は NNN-kebab-case-title.md 形式（例: 006-cache-strategy.md）
• 配置場所は必ず docs/adr/。新規作成時は docs/index.md と mkdocs.yml も更新する
• ユーザーの指示があるまでコミットしない
• コンテキストの明確化・代替案の記録・影響の両面記載・コンプライアンス項目を必ず含める

関連スキル

• analyzing-architecture — アーキテクチャ設計（ADR の主な発生源）
• analyzing-tech-stack — 技術スタック選定（ADR として記録すべき決定）
• git-commit — ADR 作成後のコミット