adr

Imported from being-ish/agent-skills (plugins/dev-docs/skills/adr/SKILL.md). Install upstream with npx skills add being-ish/agent-skills --skill adr. Copyright stays with the author.

ADR の生成と更新

ADR: Architecture Decision Record は方針決定、技術選定、設計判断の記録。

ドキュメント間の関係

各ドキュメントは、表で自分より上にあるドキュメントを前提として書く。

• 他のドキュメント種別に属する内容は書かない
• リンクは表で自分より上にあるドキュメントへだけ張る
  • 逆方向へは張らない
  • 同じ種別どうしのリンクは張ってよい

feature とは

Screaming Architecture における機能の凝集単位。 フロントエンドからバックエンドまでを横断する、機能で切った単位を指す。 システム横断のドキュメントは、特定の feature に閉じない内容を扱う。

出力先

• システム横断: /docs/adr/ 以下
• feature 固有: /docs/features/<feature-name>/adr/ 以下

/docs/features/ が存在しないリポジトリーでは、出力先をユーザーに確認する。

ファイル名は NNNN-kebab-case-title.md。 NNNN は 0001 からの連番。

テンプレート

• ${CLAUDE_SKILL_DIR}/references/adr.md

規則

• 1 ファイルに 1 つの決定を書く
  • 決定節の各文について、その文だけを別の ADR で廃止できるかを確かめる
  • 廃止できる文は別の ADR に分ける
  • 選んだ選択肢に付随する詳細は、決定節でなく選択肢の説明に書く
• 記述にあたって必要な情報以外は省く
  • 具体的な実現手段やコードなどはテーマそのものであるとき以外は書かない
• 情報が不足しているセクションは「TBD」と記載する
• 新規作成時のステータスは「有効」とする
• 一部の決定だけが廃止された ADR はステータスを「有効」のままとし、廃止された決定と廃止した ADR を箇条書きで付記する
• 関連ドキュメントは本文の該当語句にインラインリンクを張る
• 現在の実装状況を判断に使わない
• ドキュメントに実装状況を書かない
• その他はテンプレートのセクション構成と説明に従う

手順

1. 生成 / 更新対象の ADR がシステム横断か feature 固有かを判断する
   • 単一の feature に閉じる内容なら feature 固有、複数 feature やシステム基盤に関わるならシステム横断とする
   • /docs/features/ 以下のディレクトリー一覧を feature の候補として参照する
   • 不明ならユーザーに確認する
2. テンプレートを読み込む
3. 出力先ディレクトリの既存 ADR を確認し、次の連番を決定する
4. ユーザーの要求をもとに、規則に従って ADR を作成する
   • 「TBD」と記載したセクションはユーザーに確認する
   • 既存 ADR に全部または一部が廃止されるものがないかチェックし、該当があれば旧 ADR のステータスを更新する
5. PRD や design doc など関連ドキュメントが存在する場合、整合性をチェックし、矛盾があればユーザーに報告する
6. plan-tasks スキルで作成したタスクリスト Artifact が本作業に存在する場合、ADR の変更に伴う更新が必要かを確認し、必要であれば更新する
7. GitHub Issues を確認し、ADR の変更に伴い Issues の追加、変更、削除が必要であればユーザーに進言する
8. 出力先に ADR を書き出す
9. Task ツールで skill-adherence:skill-adherence-checker sub-agent を起動し、dev-docs:adr と書き出したファイルのパスを渡して Skill 違反を検査させる
   • この sub-agent が使えない環境ではこの手順を省く
   • 報告された違反を ADR に反映する