adr-writer

ADR ライター

コンテキスト、根拠、代替案、結果を保持する、軽量で構造化された形式でアーキテクチャ上の決定を記録します。適切なステータスライフサイクルを備えた番号付きの ADR ドキュメントを作成し、数か月後に決定を見直した際に「なぜこの方法にしたのか？」という問題が起きないようにします。

参照ファイル

ファイル	内容	読み込むタイミング
references/adr-template.md	フィールドの説明と例を含む標準 ADR テンプレート	常に
references/status-lifecycle.md	ステータスの遷移、置き換えのルール、非推奨化のプロセス	ADR が既存の決定を参照する場合
references/context-capture.md	決定のコンテキストを引き出して文書化する手法	複雑な決定、または複数のステークホルダーが関わる決定
references/alternatives-analysis.md	却下した代替案を評価して文書化するためのフレームワーク	複数の選択肢を検討している場合

前提条件

• 決定事項を格納するディレクトリ（通常は docs/adr/ または docs/decisions/）
• 行う決定の理解（明確化のための質問が必要な場合があります）

ワークフロー

フェーズ 1：決定を特定する

1. どのような選択をしましたか？ — アーキテクチャ上の中心的な決定を抽出します。ユーザーが問題を説明した場合は、その問題を解決する決定を明確にできるよう支援します。
2. ADR に記録する価値のある決定ですか？ — ADR は、次のような決定に使用します。
   • システム構造（コンポーネントの境界、データフロー、API 設計）に影響する
   • 元に戻すのが難しい（技術の選択、データベーススキーマ、プロトコル）
   • 明白ではないトレードオフがある（実行可能な代替案が複数ある）
   • 後から疑問視される（「なぜそうしたのか」が忘れられる）
3. この決定のきっかけは何ですか？ — 新しい要件、パフォーマンスの問題、スケーリングに関する懸念、セキュリティ監査での指摘、技術的負債、チームの拡大など。

フェーズ 2：コンテキストを記録する

この決定に影響を与えた要因を記録します。

1. 要件 — どのような機能要件または非機能要件が、この決定を促していますか？
2. 制約 — どのような要因が解決策の範囲を限定しますか？（予算、スケジュール、チームの専門知識、既存のインフラストラクチャ、規制要件）
3. 現状 — 現在何がありますか？どのような問題がありますか？
4. ステークホルダー — この決定の影響を受けるのは誰ですか？誰の合意が必要ですか？

フェーズ 3：代替案を列挙する

検討した各代替案について、次の項目を記載します。

1. 明確な名前を付ける — 「オプション A」ではなく「PostgreSQL」
2. 具体的な利点を挙げる — 具体的で測定可能なメリット
3. 具体的な欠点を挙げる — 具体的で測定可能なデメリット
4. 却下した理由を記載する — この代替案を選ばなかった理由を具体的に説明します。「遅すぎる」ではなく、「必要なスループットである 10K ops/sec をサポートしていない」とします。

フェーズ 4：決定を文書化する

コンテキストと制約を踏まえて、選択した選択肢とその理由を記載します。決定は、コンテキストと代替案の分析から論理的に導かれる必要があります。

フェーズ 5：結果を予測する

この決定によって何が容易になり、何が難しくなるかを記録します。

1. 肯定的な結果 — 何が改善されますか？
2. 否定的な結果 — どのようなトレードオフを受け入れますか？どのような技術的負債が生じますか？
3. 中立的な結果 — 良くも悪くもない副次的な影響。

フェーズ 6：メタデータを割り当てる

1. 番号 — 連番を使用します。ADR-001、ADR-002 など。次の番号を決めるため、既存の ADR を確認します。
2. ステータス — 初期ステータスは通常「Proposed」または「Accepted」です。
3. 日付 — ADR を作成した日付
4. 作成者 — この ADR の作成者
5. 置き換える／置き換えられる ADR — 以前の決定を置き換える場合は、関連する ADR へのリンク

出力形式

# ADR-{NNN}: {Descriptive Title}

**Status:** {Proposed | Accepted | Deprecated | Superseded by ADR-XXX}
**Date:** {YYYY-MM-DD}
**Author:** {name}
**Supersedes:** {ADR-XXX (if applicable)}

## Context

{What situation requires a decision? What constraints exist? What forces are at play?
Write in present tense — describe the situation as it exists at decision time.}

## Decision

{State the decision clearly and concisely. "We will use X for Y because Z."
One to three sentences. The reader should understand the decision without reading
the rest of the document.}

## Alternatives Considered

### {Alternative 1 Name}
- **Pros:** {specific benefits}
- **Cons:** {specific drawbacks}
- **Rejected because:** {concrete, specific reason tied to context}

### {Alternative 2 Name}
- **Pros:** {specific benefits}
- **Cons:** {specific drawbacks}
- **Rejected because:** {concrete, specific reason tied to context}

## Consequences

### Positive
- {Concrete benefit 1}
- {Concrete benefit 2}

### Negative
- {Concrete tradeoff 1 — acknowledged and accepted}
- {Technical debt incurred — with plan to address if applicable}

### Neutral
- {Side effect that is neither positive nor negative}

## References

- {Link to related issue, discussion, document, or prior ADR}

キャリブレーションルール

1. コンテキストが最重要です。 コンテキストのセクションが最も重要です。コンテキストのない判断は、単なる主張にすぎません。将来の読者には、WHAT だけでなく WHY も理解してもらう必要があります。
2. 却下理由は具体的にします。 「適していない」は却下理由になりません。「注文処理に必要な、パーティションをまたぐトランザクションをサポートしていない」なら、理由になります。
3. 結果を正直に記述します。 すべての判断にはデメリットがあります。Negative セクションが空の場合、分析は不完全です。トレードオフを明確にするようユーザーに促してください。
4. コンテキストは現在形で記述します。 Context セクションは現在形で書きます。これは、判断を下した時点での状況を記録するものです。
5. ADR 1 件につき判断は 1 つにします。 複数の判断が相互に関連している場合は、別々の ADR を作成し、相互に参照します。無関係な判断をまとめないでください。
6. 承認後は変更しません。 承認された ADR は編集しません。判断が変わった場合は、古い ADR に取って代わる新しい ADR を作成します。これにより、履歴が保たれます。

エラー処理

問題	解決策
ユーザーが代替案を明確にできない	次のように質問して、案を出すのを手伝います。「他に何ができたでしょうか？どのような選択肢を検討し、却下しましたか？」
判断が些細である（実質的な代替案がない）	ADR は不要だと提案します。ADR はトレードオフを伴う、明白ではない判断のためのものです。
判断はすでに下されているが、コンテキストが思い出せない	コード、PR、コミット履歴からコンテキストを再構成します。再構成したコンテキストには「入手可能な最善の情報」と記載します。
既存の ADR の採番方式が不明	docs/adr/ または docs/decisions/ を確認します。ディレクトリが存在しない場合は、作成して 001 から始めることを提案します。
判断の範囲が広すぎる	複数の焦点を絞った ADR に分割します。データベースの選択用、キャッシュ戦略用などに分けます。

ADR を作成しない場合

次の場合は、別の方法を提案してください。

• 判断が簡単に変更できる場合（ライブラリのバージョン、コードのフォーマット規則など）— 代わりにコメントまたは設定を使います
• 判断が代替案のない標準的な慣行である場合（HTTPS の使用、入力の検証など）— ADR に記録するほどの判断ではありません
• ユーザーが実装の詳細を記録しようとしている場合 — ADR は実装の HOW ではなく、判断の WHY を記録するものです
• 判断がすでに別の判断に置き換えられている場合 — 古い ADR ではなく、新しい ADR を作成します