adr-writing

ADR の作成

概要

MAD​​R テンプレートに従って、体系的な完全性チェックを行いながらアーキテクチャ決定記録（ADR）を作成します。

クイックリファレンス

┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│  SEQUENCE   │ ──▶ │   EXPLORE    │ ──▶ │    FILL     │
│  (get next  │     │  (context,   │     │  (template  │
│   number)   │     │   ADRs)      │     │   sections) │
└─────────────┘     └──────────────┘     └─────────────┘
       │                                        │
       │                                        ▼
       │                                 ┌─────────────┐
       │                                 │   VERIFY    │
       │                                 │  (DoD       │
       └─────────────────────────────────│   checklist)│
                                         └─────────────┘

使用するタイミング

• 抽出した要件に基づくアーキテクチャ上の決定を文書化するとき
• 会議メモや議論を正式な ADR にまとめるとき
• PR の議論での技術的な選択を記録するとき
• 設計ドキュメントから決定記録を作成するとき

ワークフロー

ゲート（客観的な合格条件）

合格条件を満たした場合にのみ、次のステップに進んでください。「調査した」「確認した」という曖昧な表現を、確認可能な成果物に置き換えます。

ステップの後	合格条件
ステップ 2	合格： 関連する ADR／置き換えられた ADR について、確認した docs/adrs/ 配下のパスを0 件以上、箇条書きで記載したリスト（草稿の前文、作業メモ、または ADR 本文内）を用意します。または、確認した結果 docs/adrs/ が存在しないか空であることを明記します。さらに、関連コードのリポジトリ内パスを1 件以上列挙するか、1 行の理由を添えて N/A と記載します。
ステップ 5	合格： references/definition-of-done.md の E、C、A、D、R それぞれについて、草稿が該当するチェックリストを満たすか、該当する不足箇所を対象とする [INVESTIGATE: …] マーカーが含まれています。
ステップ 7	合格： ADR ファイルが docs/adrs/NNNN-slugified-title.md に存在し、ファイルを読んで 1 行目が --- であること、およびフロントマターが YAML として解析できることを確認します。

ステップ 1：シーケンス番号を取得する

番号が事前に割り当てられている場合（並列書き込みで /beagle:write-adr から呼び出された場合など）：

• 事前に割り当てられた番号をそのまま使用します
• スクリプトは呼び出さないでください。並列実行時の番号重複を防ぐためです

番号が事前に割り当てられていない場合（単独で使用する場合）：

python scripts/next_adr_number.py

これにより、次に利用できる ADR 番号（例：0003）が出力されます。

並列割り当ての場合（親コマンドで使用）：

python scripts/next_adr_number.py --count 3
# Outputs: 0003, 0004, 0005 (one per line)

ステップ 2：コンテキストを調査する

作成前に、追加のコンテキストを収集します。

1. 関連コード - この決定によって影響を受ける実装を見つけます
2. 既存の ADR - docs/adrs/ を確認し、関連する決定や置き換えられた決定を探します
3. 議論の情報源 - 決定で参照されている PR、issue、ドキュメントを確認します

ゲート： ステップ 3 に進む前に、**ゲート（客観的な合格条件）**のステップ 2 の行を満たしてください。

ステップ 3：テンプレートを読み込む

正式な MADR 構成を確認するため、references/madr-template.md を読み込みます。

ステップ 4：セクションを記入する

決定に関するデータを使って各セクションを記入します。

セクション	情報源
タイトル	決定の要約（命令形）
ステータス	最初は常に draft
コンテキスト	問題の説明、制約
決定の判断基準	優先順位付けされた要件
検討した選択肢	実行可能なすべての代替案
決定の結果	根拠を添えた選択肢
影響	良い影響、悪い影響、中立的な影響

ステップ 5：完了の定義を適用する

references/definition-of-done.md を読み込み、E.C.A.D.R. の基準を確認します。

• E：問題を明確に記述している
• C：選択肢を包括的に分析している
• A：実行可能な決定である
• D：影響を文書化している
• R：ステークホルダーがレビューできる

ゲート： ステップ 6 に進む前に、**ゲート（客観的な合格条件）**のステップ 5 の行を満たしてください（情報が不足している場合は [INVESTIGATE: …] を使用します）。

ステップ 6：不足箇所に印を付ける

入手可能なデータでは記入できないセクションに、調査を促すマーカーを挿入します。

* [INVESTIGATE: Review PR #42 discussion for additional drivers]
* [INVESTIGATE: Confirm with security team on compliance requirements]
* [INVESTIGATE: Benchmark performance of Option 2 vs Option 3]

これらのマーカーは、後で追加の確認が必要な未完成のセクションを示します。

ステップ 7：ファイルを書き込む

重要：すべての ADR は YAML フロントマターから始める必要があります。

フロントマターブロックは必須であり、最低限、次の内容を含める必要があります。

---
status: draft
date: YYYY-MM-DD
---

フロントマターの完全なテンプレート：

---
status: draft
date: 2024-01-15
decision-makers: [alice, bob]
consulted: []
informed: []
---

検証： ファイルを書き込む前に、内容が --- と有効な YAML フロントマターで始まっていることを確認してください。フロントマターがない場合は、書き込む前に追加してください。

ゲート： 書き込み後、**ゲート（客観的な合格条件）**のステップ 7 の行を満たしてください（ファイルがディスク上に存在し、YAML フロントマターがあること）。

次の場所に保存します：docs/adrs/NNNN-slugified-title.md

docs/adrs/0003-use-postgresql-for-user-data.md
docs/adrs/0004-adopt-event-sourcing-pattern.md
docs/adrs/0005-migrate-to-kubernetes.md

ステップ 8：フロントマターを確認する

書き込み後、ファイルが次の条件を満たしていることを確認します。

1. 1 行目が --- で始まっている
2. status: draft（または有効な別のステータス）が含まれている
3. 実際の日付を指定した date: YYYY-MM-DD が含まれている
4. タイトルの前に --- でフロントマターが終了している

ファイル名の規則

形式：NNNN-slugified-title.md

要素	規則
NNNN	スクリプトが割り当てる、ゼロ埋めされた連番
-	区切り文字
slugified-title	小文字、ハイフンを使用し、特殊文字は使用しない
.md	Markdown 拡張子

参照ファイル

• references/madr-template.md - MADR 公式テンプレートの構成
• references/definition-of-done.md - E.C.A.D.R. 品質基準

出力例

---
status: draft
date: 2024-01-15
decision-makers: [alice, bob]
---

# Use PostgreSQL for User Data Storage

## Context and Problem Statement

We need a database for user account data...

## Decision Drivers

* Data integrity requirements
* Query flexibility needs
* [INVESTIGATE: Confirm scaling projections with infrastructure team]

## Considered Options

* PostgreSQL
* MongoDB
* CockroachDB

## Decision Outcome

Chosen option: PostgreSQL, because...

## Consequences

### Good

* ACID compliance ensures data integrity

### Bad

* Requires more upfront schema design

### Neutral

* Team has moderate PostgreSQL experience