recording-decisions

決定の記録

必須の背景: technical スキル(ハードルール、スタイル)。

概要

重みに応じて2つのフォーマットを使い分けます。アーキテクチャレベルの影響を伴う決定には完全な ADR を、より小さな選択が連続する流れには決定ログのエントリを書きます。どちらも追記専用です。承認された決定は不変であり、新しい文脈はそれを上書きする新しいエントリになります。

呼び出すべきとき、そうでないとき

選択がすでになされ、それを記録する必要があるとき、誰かが「なぜこうしたのか書き残しておいて」と依頼したとき、あるいは既存の決定が上書きされるときに呼び出します。まだ議論中の決定には呼び出さないでください(それは writing-design-docs の役割です。その Why & What ボックスが、承認されると ADR になります)。

記録されていない決定が通り過ぎていくときのシグナルでも呼び出します。「Y ではなく X に決めた」「とりあえずこれでいこう」、PR のコメントやチャットスレッドで解決されたトレードオフ、あるいは誰かがすでに2度説明した根拠などです。いずれも耐久性のない場所に存在する決定です。記録することを提案してください。

決定を引用する前に記録してください。チャットセッションは耐久性のある情報源ではありません。日付入りの実質的な内容をログに書き、文言が重要な場合は決定者を引用し、エントリをコミットしてから引用します。記録するのは最小限の完全な決定であり、文字起こしではありません。

ADR

Nygard フォーマット。1つの ADR につき1つの決定。

# ADR-[number]: [short title of the decision]

| | |
|---|---|
| **Status** | Proposed / Accepted / Superseded by ADR-XXX |
| **Date** | YYYY-MM-DD |
| **Deciders** | [who took part] |

## Context
[The forces at play: technical, organizational, political. What must be solved.
Factual, without giving away the decision.]

## Decision
[What was decided. Active voice: "We release on tags", not "it was decided that".]

## Consequences
**Positive:** [what gets easier]
**Negative:** [what gets harder, which trade we accept]
**Neutral:** [what changes without being better or worse]

## Alternatives considered
**[Alternative]** - For: [...] Against: [...] Why not chosen: [...]

## References
[Evidence, related decisions, measurements]

ネガティブは必須であり、空にしてはいけません。 各代替案には、それを支持する最強の論拠を添えます。それが欠けた棄却はストローマン論法です。

承認された ADR に対して許可される唯一の編集は、そのステータス行に「Superseded by ADR-XXX」を追加することです。提起されたが決して回答されなかった異議は、名前を挙げた担当者を伴うネガティブな結果として、そのままの強さで記載します。書き手は反論を捏造してはならず、担当者が宣言した決定を伏せてもいけません。執筆時点で不明な名前は、提出前に記入としてマークします。提出された記録には実在の人物が載るからです。

決定ログ(軽量)

完全な ADR では維持が難しすぎる継続的なログ向けです。維持するのに十分な手軽さ:

## YYYY-MM-DD

### [Decision stated as an imperative sentence]
[One paragraph: the rule.]
Why:
- [reason]
- [reason]
Instead of: [rejected option] - [why not]

ルール

• 追記専用。誤ったエントリには、それを上書きする新しい日付入りのエントリを追加し、決して編集しません。相対的な日付は絶対的な日付に変換します。
• what だけでなく why を記録します。
• 書かれたルールと出荷された現実が乖離した場合、チームがどちらを意図していたかを記録します。あらゆるドクトリン文書は、自分が何を所有し、何を他に委ねるかを明示します。
• 兄弟ファイルと重複する可能性がある場合は、冒頭にスコープのガードを置きます。「製品アイデアは ROADMAP.md にあります。このファイルはエンジニアリング上の決定のためのものです。」
• ネガティブな結果と不明点を明示的に記録します。「4つの仮説、4つとも反証、原因は見つからず」は結果です。何も返さなかった検索も結果です。