writing-adrs

ADR の作成

ADR は docs/adr/ に格納し、連番を使用します：0001-slug.md、0002-slug.md など。

最初の ADR が必要になるまで、docs/adr/ ディレクトリは作成しないでください。

テンプレート

# {Short title of the decision}

{1-3 sentences: what's the context, what did we decide, and why.}

以上です。ADR は1段落だけでも構いません。大切なのは、セクションを埋めることではなく、決定がなされたことと、その理由を記録することです。

利用できる場合は writing-prose スキルを使って作成・確認し、markdown を指定します。厳守事項：正確さと理解しやすさを損なわないこと。

任意のセクション

本当に価値がある場合にのみ含めてください。ほとんどの ADR では不要です。

• ステータスのフロントマター（proposed | accepted | deprecated | superseded by ADR-NNNN）— 決定を見直す際に役立ちます
• 検討した選択肢 — 却下した代替案を記録しておく価値がある場合に限ります
• 結果 — 一見して分からない後続への影響を明記する必要がある場合に限ります

採番

docs/adr/ を調べて、既存の最大番号に1を加えてください。

厳しい確認の必須条件

ADR には重要な決定を記録します。会話中に決定されたものの、厳しい確認（docs/glossary/grilling-session.md）を受けていない場合は、ユーザーに「決定について厳しい確認は行われていません。このまま記録しますか？」と尋ねてください。明示的な確認があった場合のみ進めます。ユーザーがすでに明示した決定を書き起こす場合、この条件は適用されません。

ADR を作成するタイミング

次の3つすべてに当てはまる必要があります。

1. 覆すのが難しい — 後から考えを変えるコストが無視できない
2. 背景がないと意外に思われる — 将来の読者がコードを見て「なぜわざわざこの方法にしたのだろう？」と思う
3. 実際のトレードオフの結果である — 現実的な代替案があり、具体的な理由からそのうちの1つを選んだ

簡単に覆せる決定なら、記録は不要です。どうせ後から覆すことになります。意外でなければ、誰も理由を疑問に思いません。現実的な代替案がなかったなら、「当然の方法を採用した」という以上に記録することはありません。

該当する決定

• アーキテクチャの形。「モノレポを採用する。」「書き込みモデルはイベントソーシングを採用し、読み取りモデルは Postgres に投影する。」
• コンテキスト間の統合パターン。「Ordering と Billing は、同期 HTTP ではなくドメインイベントを介して通信する。」
• **ロックインにつながる技術選択。**データベース、メッセージバス、認証プロバイダー、デプロイ先などです。すべてのライブラリではなく、置き換えに四半期かかるようなものだけを対象にします。
• 境界とスコープの決定。「顧客データは Customer コンテキストが所有し、他のコンテキストは ID のみを参照する。」明示的に「しない」としたことも、「する」としたことと同じくらい価値があります。
• 当然の方法から意図的に逸脱する決定。「X のため、ORM ではなく手書きの SQL を使う。」合理的な読者が反対の方法を想定するようなものが該当します。意図的な決定を次のエンジニアが「修正」してしまうのを防ぎます。
• コードからは分からない制約。「コンプライアンス要件により AWS は使えない。」「パートナー API の契約により、応答時間は200ms未満でなければならない。」
• **却下した理由が自明でない代替案。**GraphQL を検討したうえで微妙な理由から REST を選んだのであれば、記録してください。そうしないと、半年後に誰かがまた GraphQL を提案するでしょう。