adr-drafting

ADR の作成

重要なアーキテクチャ上の選択について、チームが重要な技術的決定を行った理由を明確に記録できるよう、新しいアーキテクチャ決定記録（ADR）を作成します。

概要

このスキルでは、情報収集から最終的な Markdown ファイルの作成まで、新しい ADR の作成を支援します。決定の詳細を確認し、リポジトリに既存の ADR の規約がないか調べたうえで、標準セクションの Title、Status、Context、Decision、Consequences を含む新しい ADR の草案を作成します。

リポジトリに ADR の規約がまだない場合は、ADR の保存先として docs/architecture/adr をデフォルトで使用し、0001-use-postgresql-for-primary-database.md のようにゼロ埋めしたファイル名を使用します。

デフォルトの ADR テンプレートについては references/template.md を、ADR の例と命名パターンについては references/examples.md を参照してください。

使用する場面

ユーザーまたはエージェントが意味のあるアーキテクチャ変更を決定し、その根拠、選択した方針、トレードオフを新しいアーキテクチャ決定記録に残す必要がある場合に、このスキルを使用します。ADR の作成、アーキテクチャ上の決定の文書化、決定記録の作成、重要な技術的選択の背景にあるプロジェクトの履歴の保存などの依頼に適しています。

手順

フェーズ 1：ADR の入力情報を確認する

新しい ADR の草案作成に必要な最低限の情報をユーザーに確認します。

1. 決定のタイトル
2. 決定のステータス（まだ確定していない場合は、デフォルトで Proposed）
3. コンテキスト：決定の要因となった問題、制約、または要素
4. 決定：選択した方針
5. 影響：容易になること、難しくなること、リスクが高まること、または費用が増すこと
6. この依頼が既存の ADR の編集ではなく、新しい ADR の作成であることを確認
7. 文書の言語が不明な場合は、希望するリポジトリの言語を確認
8. 既存の ADR の命名規約を維持する必要があるかを確認

ユーザーが実際には既存の ADR の更新、古い ADR のステータス変更、または上書き関係のリンク管理を希望している場合は、このスキルでは新しい ADR 文書の草案作成のみを行うことを説明し、代わりに新しい記録を作成するかどうかを確認します。

フェーズ 2：リポジトリ内の ADR の規約を調べる

草案を作成する前に、リポジトリを調査します。

1. 次のような ADR の保存先候補を検索します。
   • docs/architecture/adr
   • docs/adr
   • adr
   • architecture/adr
2. ADR ファイルがすでに存在する場合は、1～3 件の例を読み、次の項目を把握します。
   • 番号の形式
   • ファイル名のパターン
   • タイトルの形式
   • 言語と文体
3. ADR ディレクトリが存在しない場合は、docs/architecture/adr を推奨します。
4. 可能であれば、既存ファイルから次の ADR 番号を特定します。
5. 既存の ADR がない場合は、0001 から始めます。

既存の規約がない場合に推奨するデフォルトの命名方法：

• ディレクトリ：docs/architecture/adr
• ファイル名：NNNN-short-kebab-title.md
• タイトル：# ADR-NNNN: <Decision Title>

フェーズ 3：ADR の草案を作成する

標準的な構成を使用して草案を作成します。

# ADR-NNNN: Decision Title

## Status
Proposed

## Context
What problem, constraints, or trade-offs led to this decision?

## Decision
What architectural choice was made?

## Consequences
What becomes easier, harder, riskier, or more expensive because of this decision?

草案作成のルール：

• タイトルは具体的で、決定内容がわかるものにします。
• 決定が必要になった理由を説明できるだけのコンテキストを記載します。
• 選択した方針を明確かつ簡潔に記録します。
• 判明している場合は、肯定的な影響と否定的な影響の両方を記載します。
• ユーザーが提示していない根拠、制約、結果を作り出さないでください。
• 重要な情報が不足している場合は、簡潔なプレースホルダーを挿入するか、確定前に追加の質問をしてください。

フェーズ 4：ユーザーと草案を確認する

ファイルに書き込む前に、次の内容を提示します。

• 提案するファイルパス
• 提案するタイトル
• ADR のステータス
• 草案の各セクションの簡潔なプレビュー

ファイルを作成する前に承認を求めます。ユーザーが修正を希望する場合は、まず草案を修正してください。

フェーズ 5：ADR ファイルを作成する

承認を得た後：

1. ADR ディレクトリが存在しない場合は作成します
2. リポジトリに既存の規約があれば、それに沿って ADR の Markdown ファイルを作成します
3. ドキュメントを簡潔に保ちつつ、決定理由についてはできる限りユーザーの表現を維持します
4. 最終的なファイルパスを報告し、作成した内容を要約します
5. このスキルが単一の新しい決定記録に集中できるよう、新しい ADR ファイルの作成後は作業を終了します

例

例 1：新しいデータベースに関する決定

ユーザーのリクエスト：「SQLite から PostgreSQL への移行について ADR を作成してください」

想定される流れ：

1. タイトル、ステータス、変更の理由、想定される結果を確認します
2. リポジトリに ADR ファイルがすでにあるか確認します
3. 既存の規約に沿って新しい ADR を作成するか、規約がなければ docs/architecture/adr/0001-move-to-postgresql.md を使用します
4. ファイルを書き込む前に承認を求めます

例 2：新しいサービス境界

ユーザーのリクエスト：「請求処理を専用サービスに分割する決定を文書化してください」

想定される流れ：

1. アーキテクチャ上の背景と、現在の設計では不十分な理由を尋ねます
2. 選択した境界と運用上の影響を確認します
3. 標準的なセクションを含む新しい ADR の草稿を作成します
4. ユーザーの承認後にのみファイルを作成します

より詳しい ADR の例については、references/examples.md を参照してください。

ベストプラクティス

• 各 ADR は、1 つのアーキテクチャ上の決定に焦点を絞ります
• ADR がすでにある場合は、リポジトリの命名規則、番号付け、文体に合わせます
• 長い説明より簡潔な説明を優先します
• 欠点や新たなリスクも含め、トレードオフを正直に記録します
• ユーザーが別の状態を確認しない限り、ステータスは Proposed にします
• リポジトリで推奨されるドキュメントの言語が明らかな場合は、それに従います

制約と警告

• このスキルは新しい ADR の作成のみを対象とします
• 既存の ADR ファイル、ステータス履歴、後継関係の連鎖は更新しません
• 不明な決定理由や結果を捏造しません
• リポジトリで別の ADR の保存先が使われている場合、docs/architecture/adr を強制しません
• 責任を持って文書化するには決定、背景、結果が曖昧すぎる場合は、必ず確認の質問をします