adr-drafting

adr-drafting

構造化された対話を通じて、ADR を共同で作成します。アーキテクトが目にするのは初稿ではなく、自己批評を経た改訂稿だけです。

入力

• 必須： 5 つすべての MUST が CONFIRMED になっている docs/architecture/discovery-brief.md。ファイルがない場合、または内容が不十分な場合、このスキルは処理を拒否し、adr-discovery に案内します。
• 任意： docs/architecture/open-questions.md。PARKED の MUST は、作成する ADR の Consequences に記載する必要があります。

基本動作ルール

1 回のメッセージで出す質問またはステップは 1 つまでです。 1 回のターンに ? が 2 つ含まれている、番号付きアクションが 2 つある、または短い段落を超える場合は、短くして最も重要な質問から尋ねてください。

スタイル

• 率直に。「いい質問ですね！」「素晴らしい指摘です！」「堅実なアプローチです！」などとは言いません。
• 説明調ではなく、箇条書きを中心にします。
• あいまいな名詞は使わず、具体的な技術、ファイル、コンポーネントを挙げます。
• 根拠の弱い推論には、アーキテクトの言葉を引用し、違反しているルールを明示して反論します。

用語（初出時に定義）

• コンポーネント — 実行またはデプロイ可能な単位（C4 の Container）であり、コードのクラスではありません。
• システム — 1 つの ADR で扱う、境界が定められた単一のプロダクトです。
• アーキテクチャ特性 — 負荷にさらされている非機能品質です。
• 緊張関係 — どちらかが他方に取って代わることなく、互いに矛盾する 2 つの ADR の関係です。隠さず、明記する必要があります。
• RFC — フィードバック期限を設け、レビューを必須とする ADR です。決定がまだ確定していない場合に使用します。
• 適合性関数 — 決定が引き続き有効であることを確認する自動チェック（lint ルール、アーキテクチャテスト、CI アサーション、ダッシュボードのしきい値）です。

7 つのフェーズ

フェーズ 1 — 理解

discovery-brief.md を読みます。記載されている内容を再度尋ねてはいけません。まだ確認されていない MUST についてのみ質問します。

MUST	デフォルトの質問
決定の目的	「1 文で：記録する決定は何ですか？」
負荷にさらされているアーキテクチャ特性	「どの品質がこの決定を迫っていますか？ レイテンシ、コスト、可用性、セキュリティ、保守性、その他のどれですか？ 数値または条件を挙げてください。」
影響を受けるコンポーネント	「この決定は、ブリーフに記載されたどのコンポーネントに影響しますか？（最大 5 つ）」
関連する既存 ADR	「既存の ADR を置き換える／修正する／関連付ける／緊張関係にありますか？」
決定者	「この決定に責任を負うのは誰ですか？ 人名を挙げてください。」

ゲート： 2 つ以上の MUST への回答が不十分（「チーム」「パフォーマンスのため」「将来の柔軟性」など）な場合は、そこで止めて adr-discovery に案内します。先に進んではいけません。

フェーズ 2 — コンテキスト

フェーズ 1 の「関連する既存 ADR」の質問で挙がった各 ADR を、1 つずつ確認します。それぞれについて、対話の中で分類します。

• supersedes — この決定がその ADR に取って代わる
• amends — 置き換えずに、その ADR を調整する
• relates-to — コンテキストを共有するが、独立している
• tension — どちらかが他方に取って代わることなく、互換性がない
• unrelated — 対象から外す

ADR ディレクトリを一度だけ glob し、アーキテクトが見落とした ADR がないか確認します。

フェーズ 3 — 選択肢

選択肢を挙げるのはアーキテクトです。エージェントではありません。 選択肢が 1 つだけ提示された場合は、「ほかに現実的な選択肢はありますか？」と尋ねます。

各選択肢について、4 回に分けて確認します。

1. 利点 — 「この選択肢を支持する最も強い根拠を 1 つ挙げると何ですか？」
2. 欠点 — 「この選択肢に反対する最も強い根拠を 1 つ挙げると何ですか？」
3. 工数 — 「実装にかかる時間は、おおよそ何時間、何日、何週間ですか？」
4. リスク — 「この選択肢が失敗した場合、どうすればそれに気づけますか？ また、影響はどの程度ですか？」

任意で、アーキテクトが挙げなかった選択肢を 1 つ追加できます（アーキテクトが考慮していない要因を挙げられる場合に限ります）。その後、最有力の選択肢に対する最も強い反論を提示して、相手の回答を待ちます。それについて相手が応答するまで、先に進んではいけません。

フェーズ 4 — 決定

4 回に分けてやり取りします。

1. 失敗モード — 「本番環境でこの決定が失敗する方法を 2～3 個挙げてください。」アーキテクトがそれらを挙げるまで、先へ進むことを拒否します。
2. 台本に沿った異議申し立て — references/pushback-patterns.md から有力な選択肢に合う異議申し立てを 1 つ選び、そのまま伝えて待ちます。
3. 確信度 — 「決定者の確信度は 1～5 の尺度でどの程度ですか？何があれば 5 になりますか？」
4. 見直し日 — 「この決定を見直すべき日付またはきっかけは何ですか？」

RFC の振り分け： 確信度が low の場合、アーキテクトが特定の個人 1 名ではない場合、または決定が 5 個を超えるコンポーネントに関わる場合は、accepted ではなく、rfc-deadline（デフォルト：2 週間）を設定した status: proposed を提案します。RFC として機能する ADR も、実際の ADR です。ただし、確定するまでの期限が設定されているだけです。チームが数値スコアも必要とする場合は、confidence-score に格納し、confidence は high、medium、low のいずれかにします。

フェーズ 5 — 下書き作成

セクションごとに作成し、次へ進む前に各セクションを確認します。Frontmatter は最後ではなく、最初に作成するセクションであり、必須です。以下の「拒否動作」を参照してください。以下の上限を厳守します。

セクション	上限	備考
Frontmatter	--- で囲まれた YAML	必須。title、status、date、deciders は必須です。フェーズ 2 で関連する ADR が見つかった場合は、supersedes / amends / relates-to に必ず値を設定します
タイトル	1 行、命令形の動詞句	0017. Use Postgres for primary store
Context	3 文以内	原動力となる要因を記述します。経緯ではありません
Decision	3 文以内	能動態、現在形にします
Consequences	箇条書きのみ	良い点：…／悪い点：…
Compliance	1～3 文	Fitness function のスニペットを含めてもかまいません
Alternatives	代替案ごとに 1 段落の箇条書き	代替案ごとに短所を 1 つ挙げれば十分です
More Information	サブセクションは任意。frontmatter に関連付けがある場合は ### Relationships が必須	references/template-fields.md に記載されたリンク接頭辞の語彙（Supersedes、Superseded by、Amends、Amended by、Related to）を使って、frontmatter の supersedes / amends / relates-to を反映します。frontmatter ではなく本文のリンクをスキャンするパーサーは、このセクションに依存します。
Notes	任意	保留中の未解決事項は、ここに記載します。上記の Relationships の反映の代わりにはなりません。

本文のデフォルト構成： プロジェクトの既存の決定ログで別の規約（Nygard plain、Y-statement、arc42、Tyree-Akerman）が使われていない限り、デフォルトでは MADR（現在は 4.0.0） を使用します。構成は ## Context（または ## Context and Problem Statement）→ ## Decision（または ## Decision Outcome）→ ## Consequences → ## Compliance → ## Alternatives Considered → ## More Information（関連付けがある場合は ### Relationships を含む）です。プロジェクトに既存のテンプレートがある場合は、それに従います。上流の MADR テンプレート：adr.github.io/madr/、ソースリポジトリ：github.com/adr/madr。

フェーズ 6 — 自己批評

アーキテクトには、まだフェーズ 5 の出力を見せません。 まず ../_shared/adr-is-not.md に照らして自己批評し、以下のテンプレートを使って違反を 1 つずつ指摘します。

Original: <verbatim line>
Violates: <which rule from adr-is-not.md>
Rewrite:  <shorter, stricter replacement>
Apply?    (yes / no / adjust)

1 回のメッセージで指摘する違反は 1 つです。次の違反を指摘する前に、アーキテクトの返答を待ちます。

違反がすべて解消または了承された場合に限り、最終稿の全文を表示します。

フェーズ 7 — 保存

1. まず ADR Explorer と互換性のあるディレクトリを Glob で検索します：docs/adr/、docs/decisions/、docs/architecture/decisions/、**/adr/*.md。また、レガシーの architecture/decisions/ も確認しますが、ADR Explorer のルートをカスタム設定する必要がある可能性があることを警告してください。最初に見つかったディレクトリを使用します。なければ docs/adr/ を作成します。
2. 自動採番：既存の ADR を読み込み、max+1 を取得して、4 桁のゼロ埋めにします。
3. ファイル名：NNNN-kebab-imperative-title.md（数値 ID で始める必要があります）。
4. ファイルを書き込みます。
5. ディレクトリの README.md にあるインデックスを更新します（なければ作成します）。
6. supersedes／amends／relates-to のクロスリンク手順を示し、アーキテクトが別の作業でリンク先の ADR を更新できるようにします。ADR グラフツールには 2 つの系統があることを伝えてください：
   • Gray-matter 形式のパーサー（例：ADR Explorer）は、フロントマターのみを読み取ります。supersedes、amends、relates-to のキーがエッジを生成します。本文の文章（古い ADR の superseded-by の記述、Related ADRs: の行、インデックスハブのリンク）は認識されません。
   • 本文スキャン型のパーサー（例：ADR Manager）は、描画された Markdown を走査し、MADR 形式のセクション内にある ADR 間リンクを探します（当初は ## Links、現在はコミュニティの慣例により ## More Information 内の ### Relationships サブセクション）。フロントマターは認識されません。 保存した ADR には、フェーズ 5 でミラーリングが必須となっているため、すでに両方の形式が含まれています。アーキテクトが別の作業で更新するリンク先の ADR も、ミラーリング規約に従う必要があります。安定した表示のため、フロントマターのリストでは 4 桁のゼロ埋め ID 文字列（"0008"）を使用してください。ただし、整数のままでも解析できます。このリポジトリで Accepted ADR が不変の場合は、メタデータのみの関係リンクの保守（フロントマターと本文の Relationships ミラー）が許可されるか、明示的なガバナンス上の例外が必要かを確認してください。

テンプレート（標準フィールド）

YAML フロントマターは必須で、先頭に置きます。本文ではデフォルトで MADR（現在は 4.0.0）を使用し、すべてのフロントマターの関係を ## More Information 内の ### Relationships ブロックにミラーリングします。これにより、フロントマターを読む gray-matter 形式のパーサーと、MADR 形式のセクション内の本文リンクをスキャンするパーサーの両方で、ADR のエッジが描画されます。

---
title: "<imperative verb phrase>"
status: proposed | accepted | superseded | deprecated
date: 2026-05-20
deciders:
  - <named human>
supersedes: []  # ADR ids (zero-padded 4-digit strings) this decision replaces
amends: []      # ADR ids this decision adjusts without replacing
relates-to:     # the only three keys that create graph edges in frontmatter-scanning parsers
  - id: "0000"
    reason: "one-line reason"
tags: []
review-by: 2026-11-20  # or trigger e.g. "100k DAU"
expires: 2027-05-20    # optional; only when expiry is real
confidence: high | medium | low
confidence-score: 4    # optional numeric score
rfc-deadline: 2026-06-03  # only when status == proposed and acting as RFC
---

# NNNN. <Title>

## Context
≤ 3 sentences. The forces.

## Decision
≤ 3 sentences. Active voice.

## Consequences
- Good, because …
- Bad, because …

## Compliance
1-3 sentences. Fitness-function snippet if appropriate.

## Alternatives Considered
- Option B -- one paragraph, single strongest con.
- Option C -- one paragraph, single strongest con.

## More Information

### Relationships

Mirror every frontmatter relationship here using the link-prefix vocabulary. Required when frontmatter `supersedes` / `amends` / `relates-to` is non-empty.

- Supersedes [ADR-0004](0004-old-decision.md) -- replaced because <reason>.
- Related to [ADR-0011](0011-tenancy.md) -- shares the tenancy model.

### Notes
Optional. PARKED open questions cited here.

両方の面をミラーリングしてください。 フロントマターは gray-matter パーサー（ADR Explorer）に読み取られ、## More Information 内の本文 ### Relationships は本文スキャン型パーサー（ADR Manager）に読み取られます。どちらか一方だけでは ADR の描画が不完全になります。両者の内容を一致させる必要があります。詳細な根拠、フィールドの意味、リンク接頭辞の語彙については references/template-fields.md を参照してください。

拒否の動作

このスキルは、次の場合にドラフトの作成を拒否します：

• discovery-brief.md に CONFIRMED ではない MUST がある
• アーキテクトが決定者として人間ではなく「チーム」を指定している
• 失敗モードが明確にされていない（フェーズ 4、手順 1）
• 対象範囲に含まれるコンポーネントが 5 個を超えている（決定を分割するよう案内します）

このスキルは、次の場合に保存を拒否します：

• 自己批評で指摘された未解決事項が残っている（フェーズ 6 が完了していない）
• 採番すると既存の ADR と衝突する
• ファイルが、最低限 title、status、date、deciders を含む --- YAML フロントマターのブロックで始まっていない（また、フェーズ 2 で関連する ADR が見つかった場合は supersedes／amends／relates-to も必要です）。
• フロントマターに supersedes、amends、relates-to のいずれかが設定されているのに、本文に ## More Information → ### Relationships のミラーがない、またはその逆の場合。どちらか一方だけでは、ツールの半数から ADR が認識されません。両者の内容を一致させる必要があります。

参考資料

• references/template-fields.md — すべてのフロントマターフィールドとセクションの完全な意味
• references/pushback-patterns.md — フェーズ 4 で使う、スクリプト化された異議申し立て
• references/rfc-routing.md — ADR を期限付きの RFC ステータスにすべき場合
• ../_shared/adr-is-not.md — フェーズ 6 で使用する「ADR ではないもの」の標準チェックリスト
• 上流のコンテキスト収集には adr-discovery スキル
• ADR と併せた図の作成には c4-model スキル
• このフローで作成されていないレガシー／外部 ADR の監査には adr-critique スキル