ADR ジェネレータ

技術的な決定を明確なコンテキスト、根拠、結果、および代替案とともに文書化する、よく構造化されたアーキテクチャ決定記録(ADR)を作成します。

トリガー

トリガーフレーズ	操作
create an ADR	ADR 生成の全ワークフロー
generate ADR	ADR 生成の全ワークフロー
write an architecture decision record	ADR 生成の全ワークフロー
new ADR for	特定の決定に対する対象 ADR
document this architecture decision	ADR 生成の全ワークフロー

---

クイックスタート

# これらすべて機能します:
create an ADR for database selection
new ADR for authentication strategy
document this architecture decision about event sourcing
generate ADR for switching from REST to gRPC

---

使用時機

状況	このスキルを使用しますか?
新しいアーキテクチャの決定を文書化する必要がある	はい
既存のシステムまたはパターンを変更する	はい(先行事例調査を含みます)
既存の ADR をレビューまたは検証する	いいえ、adr-review スキルを使用します
軽微な実装の詳細、アーキテクチャ的ではない	いいえ

---

プロセス

フェーズ G1: 収集

ユーザーから必要な情報を収集します:

• 決定のタイトル: 明確で簡潔な名前
• コンテキスト: 問題の陳述、技術的制約、ビジネス要件
• 決定: 選択されたソリューションと根拠
• 代替案: 検討されたオプション(最低 2 つ以上)と却下理由
• ステークホルダー: 関係する人物またはチーム

必要な情報が不足している場合は、先に進む前にユーザーに確認してください。

重要性チェック: 先に進む前に、ASR テストを使用して、決定が ADR の価値があるかどうかを簡単に評価してください。決定が些細に可逆的で、ローカルのみで、ステークホルダーの懸念がない場合は、ADR をスキップすることを提案してください。

準備状態チェック: 決定がSTART 準備定義に合格することを確認します: ステークホルダーが明確である、時間(最も責任のある瞬間)が来ている、代替案が存在する、要件が理解されている、テンプレートは G2 で決定されます。

決定が既存のシステムを変更する場合、chestertons-fence スキルを使用して先行事例調査をトリガーするか、手動で収集します: 何が存在するのか、なぜそのように構築されたのか、なぜ今変更するのか。

フェーズ G2: 調査

ADR の宛先、命名規約、番号付け、およびテンプレートを探索することで発見します。

ステップ 1: ADR ディレクトリを特定

コードベースを探索して、ADR がどこに存在するかを見つけます。固定位置を想定しないでください。

1. 広く検索: glob/grep を使用して ADR パターンに一致するファイル(ADR-*.md、adr-*.md、0*-*.md を decisions、adr、architecture という名前のディレクトリにあるもの)を見つけます
2. よくある場所を確認: .agents/architecture/、docs/adr/、docs/architecture/、docs/decisions/、architecture/decisions/
3. ADR ツールの設定を確認: .adr-dir ファイル(adr-tools で使用)または README、CONTRIBUTING、またはプロジェクトドキュメントの ADR 参照を探します
4. ユーザーが場所を指定する場合: 他に何が存在するかに関わらず、その場所を使用します

注: .agents/architecture/ と docs/architecture/ は adr-review によって監視され、自動トリガーが行われます。他のディレクトリの ADR は手動で adr-review を呼び出す必要があります。

ステップ 2: 既存の ADR からテンプレートを検出

ディレクトリに既存の ADR が含まれている場合:

• 既存の ADR 2-3 個を読んで、使用中のテンプレート(セクション見出し、フロントマター形式、命名規約、大文字小文字の規約)を推測します
• ADR テンプレートカタログの既知テンプレートと照合します
• 検出されたテンプレート、命名規約(例: ADR-NNN-slug.md vs 0NNN-slug.md)、およびセクション構造を採用します
• 注: adr-review の自動トリガーは大文字の ADR-*.md パターンのみと一致します。既存の ADR が小文字を使用する場合、自動レビューがトリガーされないことをユーザーに警告してください
• 同じディレクトリまたは親ディレクトリのテンプレートファイル(例: ADR-TEMPLATE.md、template.md)を確認します

ステップ 3: 既存の ADR がない場合を処理

コードベース内のどこにも ADR またはテンプレートファイルが存在しない場合:

• カタログからテンプレートを選択するようにユーザーに促します
• プロジェクト標準テンプレート(.agents/architecture/ADR-TEMPLATE.md が存在する場合)をデフォルトとして提案するか、広く採用されている代替案として MADR を提案します
• ユーザーに宛先ディレクトリの確認または指定を求めます

ステップ 4: 次の番号を決定

• 宛先ディレクトリの検出した命名パターンに一致するファイルをスキャンします
• 次のシーケンス番号を決定します(既存の規約に合わせてゼロパディング)
• そのディレクトリの既存ファイルとの衝突がないことを確認します

フェーズ G3: 生成

検出されたテンプレートに収集したコンテンツを入力します:

• 正確で曖昧でない言語を使用します
• 肯定的と否定的の両方の結果を含めます
• すべての代替案を長所/短所表とともに文書化し、明確な却下根拠を含めます
• 既存のシステムを変更する際は先行事例調査セクションを含めます
• マシン解析と人間参照の両方のために構造化します
• 宛先の既存 ADR のスタイルと規約に一致させます

フェーズ G4: 検証

保存する前に品質チェックリストに対して自己チェックを実施します。すべての構造チェックとコンテンツチェックは合格する必要があります。

フェーズ G5: 保存

ファイルをフェーズ G2 で決定した宛先ディレクトリに書き込みます:

ルール	例
既存の命名規約に一致させます	ADR-053-authentication-strategy.md または 0053-authentication-strategy.md
既存パターンに一致するようゼロパディングの番号を付けます	ADR-001、0001 など
小文字のケバブケーススラッグ(3-5 語)	database-selection、event-sourcing-pattern
ステータスは常に Proposed に設定	adr-review のディベート後にのみ変更

保存後、ユーザーに adr-review スキルを呼び出してマルチエージェント検証を行うことを推奨します。

---

アンチパターン

ADR を作成する際にこれらを避けてください。11 以上の作成および 7 つのレビューアンチパターンを含む完全なカタログはAD 品質フレームワークにあります。

避ける	理由	代わりに
代替案セクションをスキップする	代替案のない決定は厳密性に欠ける	長所/短所を含む最低 2 つの代替案を文書化します
ステータスを Accepted に設定する	ADR はレビューが必要です	常に Proposed を使用し、adr-review が変更するのを待ちます
既存の ADR を複製する	ガバナンスの混乱を引き起こす	G2 で既存の ADR をスキャンし、必要に応じて置き換えます
ソリューションを説明するコンテキスト	コンテキストは問題を説明する必要があります	コンテキストを強制と制約に焦点を当てます
否定的な結果を省略する	不正直なトレードオフ分析(「フリーランチクーポン」)	最低 1 つの否定的な結果を含めます
システム変更時に先行事例をスキップ	理解せずに構造を削除するリスク	chestertons-fence スキルを使用します
セールスピッチ言語	マーケティング言語は信頼を損なう	正確で定量化可能な言語を使用します
ダミー代替案	優先選択肢を輝かせるための偽のオプション	誠実な長所/短所を備えた本物の代替案を提示します
宛先のテンプレートを無視する	ADR ログの不整合	フェーズ G2 で既存の ADR からテンプレートを検出します

---

スタイル

• 追従的な表現、AI フィラー句、またはヘッジ言語なし
• アクティブボイス、直接的な表現
• 形容詞をデータに置き換える(影響を定量化する)
• 短い文(15-20 語)、高校 9 年生の読解レベル

---

検証

配信する前に、品質チェックリストのすべての項目が合格することを確認してください:

• すべての必須セクションが存在する
• ADR 番号はユニークである
• ステータスは Proposed である
• コンテキストは問題を説明し、ソリューションではない
• 長所/短所を含む最低 2 つの代替案
• 最低 1 つの否定的な結果が文書化されている
• ファイルがフェーズ G2 で決定した宛先ディレクトリに保存されている

---

関連スキル

スキル	責任
adr-generator	作成します。新しい ADR をスクラッチから作成(フェーズ G1-G5)
adr-review	検証します。6 エージェントディベートで既存の ADR を検証
chestertons-fence	調査します。既存のシステムを変更する前に履歴コンテキストを調査

---

リファレンス

• ADR テンプレート — このプロジェクトの標準 ADR ドキュメント構造
• ADR テンプレートカタログ — Nygard、MADR、Alexandrian、Tyree & Akerman、その他の形式の比較
• AD 品質フレームワーク — ASR テスト、START(準備定義)、ecADR(完了定義)、アンチパターン、レビューチェックリスト(Zimmermann)
• ADR ベストプラクティス — 執筆ガイダンス、ライフサイクル、命名規約、チームワークアドバイス
• 品質チェックリスト — フェーズ G4 の検証チェックリスト