create-adr

ADR 作成スキル

目的： 将来の開発者に背景情報を提供し、技術的な選択を行った理由に関する組織の知識を維持するため、アーキテクチャ上の決定を文書化します。

このスキルを使用するタイミング

次の場合に、このスキルを起動します。

• 重要なアーキテクチャ上の決定を行うとき
• 複数の技術やアプローチから選択するとき
• 新しいシステムコンポーネントや API を設計するとき
• システム構造を変更するリファクタリングを行うとき
• 設計上のトレードオフを伴う機能を実装した後

ADR の作成を省略する場合

• 小規模なバグ修正やリファクタリングのみの場合
• ドキュメントやテストのみの変更の場合
• アーキテクチャに影響しない設定の調整の場合
• 実装方法が明白な、些細な変更の場合

ワークフロー

1. 背景情報を収集する

実装を確認し、次の点を把握します。

• どのような技術的決定が行われたか
• なぜこのアプローチが選ばれたか
• どのような代替案があったか
• どのようなトレードオフを受け入れたか

既存のコードを確認する場合：

git diff main...HEAD
git log --oneline main..HEAD

2. さらに調査する

差分だけでは背景情報が十分でない場合は、次の作業を行います。

• 参照されているファイルや関数を読む
• 設定ファイルを確認する
• 関連するテストを確認する
• 追加された依存関係を調べる

3. ADR を作成する

場所： docs/adr/NNNN-descriptive-title.md

命名規則：

• 連番（0001、0002 など）
• 小文字とハイフンを使用
• 内容が分かる簡潔な名前

例：

• 0001-use-jwt-for-authentication.md
• 0002-adopt-event-sourcing-for-orders.md
• 0003-postgres-over-mysql.md

4. テンプレートを使用する

assets/adr-template.md のテンプレートを使用して文書を構成します。

記入する主なセクション：

• ステータス：提案、承認済み、非推奨、または置き換え済み
• 背景：決定のきっかけとなった問題や機会
• 決定：決定した内容と技術的なアプローチ
• 影響：利点、欠点、リスク
• 代替案：ほかに検討した案と、採用しなかった理由

品質ガイドライン

優れた ADR の特徴：

• 具体的な技術情報が記載されている（曖昧な説明ではない）
• 役立つ場合は、具体例やコードスニペットが含まれている
• トレードオフが率直に評価されている
• 関連するリソースや先行事例へのリンクがある

避けること：

• 曖昧な正当化（「こちらのほうがよい」など）
• 代替案のセクションがないこと
• 影響についての説明がないこと
• 実装の詳細が多すぎること（その内容はコードコメントに記載します）

例

ユーザー： 「キャッシュに Redis を使用する決定を文書化してください」

スキルの動作：

1. キャッシュの実装を確認する
2. 検討した代替案（Memcached、インメモリなど）を特定する
3. トレードオフ（複雑さとパフォーマンスなど）を文書化する
4. docs/adr/0005-redis-for-application-cache.md を作成する

統合

次の用途と相性がよいです：

• 主要な機能の実装
• システムのリファクタリング
• 技術の移行
• API の設計に関する決定