Agent Skills: ADR作成スキル

ADR作成スキル

Architecture Decision Record（ADR）を作成・更新するためのスキル。

実行フロー

1. 保存先の特定

以下の順で保存先を決定する:

1. プロジェクトルートから以下のディレクトリを探索:
   • docs/adr/, docs/adrs/, adr/, adrs/
2. 見つかればそのディレクトリを使用
3. 複数見つかればユーザーに確認
4. 見つからなければ保存先をユーザーに確認（デフォルト提案は docs/adr/）

2. フォーマットの決定

保存先に既存ADRがあるかで分岐する:

• 既存ADRが1件以上ある場合: 以下の2択をユーザーに確認
  • (a) 既存ADRのフォーマットを模倣する
  • (b) references/adr-template.md を使用する
• 既存ADRがない場合: references/adr-template.md を使用

3. 採番とファイル名

• ファイル名のデフォルト: ADR-NNNN-kebab-case-title.md（4桁ゼロ埋め）
• 既存ADRがある場合:
  • 採番方式（連番 / 日付 など）を既存に合わせる
  • 連番の場合、既存の最大番号+1。ゼロ埋め桁数も既存に揃える
  • プレフィクスの有無（ADR- 等）も既存に揃える
• タイトルは決定内容を端的に表す動詞句（例: use-dynamodb-for-primary-db）

4. 内容の整形

references/adr-template.md の各セクションを以下の優先順位で埋める:

1. ユーザーから提供された情報をそのまま使う
2. コードベースや会話履歴から推論できる内容は補完する
   • 例: 現在の変更差分、該当ファイルの既存実装、依存ライブラリ、git log など
3. 推論もできない内容はユーザーに質問する（セクションごとに分けて聞く）
   • 質問はオープンクエスチョンではなく、**意味のある選択肢の候補2〜5個 + 「その他（自由回答）」**の選択式で提案する
   • 候補は会話履歴・コードベース・一般的なベストプラクティスから具体的に導出する（「A案 / B案 / C案」のような空の記号ではなく、実体のある案を提示する）

各セクションの扱いは references/adr-conventions.md を参照。

5. ステータスと相互リンクの管理

新規ADRの初期ステータスは原則 Proposed。ユーザーが「決定済み」と明言した場合のみ Accepted とする。

既存ADRを置き換える場合は両側を更新する:

• 新規ADR: ## 🔗 関連ADR に Supersedes: ADR-NNNN <タイトル> を追記
• 既存ADR: ステータスを Superseded by ADR-MMMM に変更し、## 🔗 関連ADR に相互リンクを追記

ステータス遷移の詳細は references/adr-conventions.md を参照。

6. ユーザー確認と書き込み

ADR全文をユーザーに提示し、内容に問題ないか確認してからファイルを書き込む。supersedeがある場合は既存ADRの更新差分も併せて提示する。

注意事項

• ADRは決定の記録であり、設計提案書ではない。決定に至った事実を書く
• 💡 決定事項 > 決定に至った差別化要素 にはメリットだけでなくデメリット（トレードオフ）も存在する場合は必ず明記する
• 一度Acceptedになったら原則編集しない。変更したい場合は新しいADRでsupersedeする（誤字修正等は除く）