adr について
ADRは、アーキテクチャ上の決定を永続的に記録すべきか判断し、Architecture Decision Recordの作成、編集、レビューを行うスキルです。根拠、トレードオフ、不確実性、履歴を保ちながら、記録を簡潔にまとめます。
主な機能
- 01決定を永続記録する必要性の判定
- 02リポジトリの文書規約の確認
- 03簡潔な決定記録の作成
- 04意味と置き換え履歴の保持
- 05ADRの読み取り専用レビュー
活用シーン
- 01重要なアーキテクチャ選択の記録
- 02根拠が既存文書にあるかの確認
- 03既存ADRの更新
- 04ADRの品質と履歴のレビュー
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/インストール後、Claude Code で/adrを入力して読み込まれたか確認します。
同梱ファイルagents/openai.yamltemplates/adr.md
詳細
ADR
重要なアーキテクチャ上の決定がなぜ存在するのかを記録します。最小限で長期的に維持できる記録を作成するか、既存の成果物、別の文書形式、または文書を作成しないことが適切かを判断します。
依頼の振り分け
- 明示的な作成依頼： 決定が対象となるかを確認し、根拠とリポジトリの規約を調べてから、ADRを作成して検証します。依頼によって、正当な記録を作成する権限が与えられています。作成のための追加条件は設けないでください。
- 不足の検出： すでに確定している決定で、その根拠がほかの場所に残らない場合に限り検討します。安全であれば進行中の作業を完了し、不足している具体的な理由を示してADRを提案したうえで、作成前にユーザーの返答を待ちます。
- 既存ADRの編集： 記録とその履歴を調べます。編集上の変更は直接適用し、意味に関わる変更は以下のライフサイクルに沿って保持します。
- 既存ADRのレビュー： 対象かどうか、内容、履歴、検証に関する確認を読み取り専用で行い、指摘事項を報告します。
1. 長期的に残す根拠が必要かを確認する
決定、関連するコードとテスト、維持されているドキュメント、一時的な設計資料、既存のADR、履歴を調べてから、調査可能な情報について質問します。以下のすべてに当てはまる場合、ADRを作成する価値があります。
- その決定がアーキテクチャ、運用、互換性、セキュリティに重大な影響を及ぼし、覆すコストが実質的に高い。
- 背景情報がなければ、将来の貢献者がその選択に疑問を抱くと考えられる。
- 根拠に実際のトレードオフ、または重要な外部制約がある。
- 一時的な設計資料が廃止された後、コードや維持されているドキュメントに重要な理由が残らない。
一時的なアーキテクチャ概要は根拠であり、長期的に保持する場所ではありません。一方で、維持されている設計書、ポリシー、仕様、またはその他の長期的な成果物ですでに管理されている根拠を重複して記録しないでください。実装計画、ドメイン定義、運用手順、現在の動作の説明は、それぞれに適した成果物に記載してください。
確認できた事実、裏付けのある推論、仮説、不明点を区別します。コードだけから意図を推測したり、不確かなことを確定事項のように記述したりしてはいけません。
完了条件：決定的な根拠と不確実性を明示したうえで、記録が必要な問題を「ADR」「別の長期的な記録先」「記録不要」のいずれかに分類します。
2. リポジトリの規約に合わせる
既存ADRの保存場所、命名規則、テンプレート、言語、ステータスの表記、履歴を確認します。適切な既存の規約があればそれに従い、移行や拡張は行わないでください。規約がない場合は、保存場所を docs/adr/ とし、決定の内容が分かるタイトルを付けた、単調増加する4桁の識別子を使用します。プロジェクトのドキュメント言語に従い、ステータスには Proposed、Accepted、Rejected、Superseded を使用します。新しい記録は Accepted として作成します。記録を含む変更がマージされることで、人間がその決定を受け入れたことになります。
ユーザーから別途依頼がない限り、インデックス、初期化用の記録、ディレクトリ階層、ツールを作成しないでください。識別子を再利用してはいけません。
完了条件：書き込みを始める前に、保存先、識別子、ステータス、言語、文書の形式が決まっていることを確認します。
3. 必要最小限の記録を書く
プロジェクトにより適切なテンプレートがない場合は、templates/adr.md から始めます。次のセクションを残してください。
- Context: 決定が必要になった要因となる状況、制約、不確実性、対立。
- Decision: 何を選択したか、またその理由を明確に記述します。
- Consequences: 選択によって生じる主な利点、コスト、リスク、責任、失われる柔軟性。
将来の読者が再検討する可能性がある、本当に検討に値する代替案に限り、Alternatives considered を追加します。References は、長期的に参照できる補足的な証拠としてのみ追加し、決定の主な根拠は ADR に記載してください。
クラス、スキーマ、コマンド、ファイルごとの変更、タスクの分解、検証計画、その他の実現方法の詳細は含めないでください。それらは一時的な設計・実装成果物に記載します。将来の貢献者が決定、その根拠、結果を理解する助けにならない記述は、すべて簡潔にしてください。
完了基準：この記録が、実装上の契約にならずに、1つの決定とその理由を残していること。
4. 履歴を保ち、検証する
意味を変えない修正は、直接適用します。決定、根拠、または重要な結果を変更する場合は、通常、新しい ADR を作成し、古い記録に Superseded と記して、両方の記録を相互にリンクします。却下された記録や置き換えられた記録も保持してください。直接的な意味の変更に正当な利点がある場合は、履歴への影響を説明し、事前に人間から明示的な選択を得てください。
識別情報、日付、ステータス、保存場所、不確実性、長期的に参照できる資料、相互の置き換えリンク、最終差分を検証してください。作成、変更、またはレビューしたパス、記録した決定、残る不確実性、関連するステータス変更を報告してください。
完了基準：長期的な記録が最小限かつ明瞭で、履歴に偽りがなく、変更されたすべての成果物が把握されていること。