mcpField
D
develop-adr

develop-adr

github.com/product-on-purpose開発769798 回インストール4 日前に更新
リポジトリ

develop-adr について

軽量なアーキテクチャ決定記録（ADR）形式で、重要な技術的決定を文書化するスキルです。決定の背景、理由、結果を記録し、後から読むエンジニアが経緯を把握できるようにします。

主な機能

  1. 01ADRの番号とタイトルの設定
  2. 02ステータス、背景、決定の記録
  3. 03利点と欠点の記述
  4. 04代替案と参考資料の列挙
  5. 05該当する場合のモデル選択のトレードオフ記録

活用シーン

  1. 01技術選定の記録
  2. 02今後の開発で使うアーキテクチャパターンの記録
  3. 03技術的制約の決定理由の保存

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/product-on-purpose/pm-skills --skill develop-adr

インストール後、Claude Code で/develop-adrを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

HISTORY.md
evals/
trigger-fixtures.json
evals/output-scenarios/
event-streaming.md
search-datastore.md
references/
EXAMPLE.md
TEMPLATE.md

詳細

アーキテクチャ決定記録（ADR）

アーキテクチャ決定記録は、重要な技術的決定とその背景および結果を記録するものです。ADR は、アーキテクチャ上の選択の「なぜ」を記録することで、将来のチームメンバーがその理由を理解できるようにします。特に、なぜその方法が選ばれたのか疑問に思ったときに役立ちます。このスキルでは、Michael Nygard の軽量 ADR 形式を採用しています。

使用する場面

  • システムアーキテクチャに影響する重要な技術的決定を行うとき
  • 技術の選択肢（フレームワーク、データベース、サービス）から選ぶとき
  • 今後の開発で従うべきパターンを確立するとき
  • 制約や、直感的ではないアプローチの根拠を記録するとき
  • 過去の決定に関する組織の知識を保存するとき

使用しない場面

  • 決定がアーキテクチャや技術ではなく、プロダクトや UX の設計上の選択である場合 → develop-design-rationale を使用します
  • アプローチの実現可能性をまだ検討中の場合 → 検討期間を区切り、まず develop-spike-summary で記録します
  • ステークホルダーに解決策を提案する必要がある場合 → develop-solution-brief を使用します。ADR は決定を記録するものであり、解決策を売り込むものではありません
  • 実際には何も決定されていない場合（現状が変わらない場合） → 決定のない ADR は雑音になります。決定が行われるまで待ちます

手順

ADR の作成を依頼された場合は、次の手順に従います。

  1. 番号とタイトルを付ける 参照しやすいよう、ADR には連番を付けます（ADR-001、ADR-002 など）。タイトルには、「注文データに PostgreSQL を使用する」や「フロントエンドに React を採用する」のように、決定を表す短い名詞句を付けます。

  2. ステータスを設定する 新しい ADR のステータスは「提案」です。チームでのレビュー後、「承認済み」「非推奨」、または「ADR-XXX により置き換え」に変更します。ステータスの変更は追跡します。

  3. 背景を説明する この決定に至った状況を説明します。どのような問題を解決しようとしているのでしょうか。どのような要因（技術的制約、チームの専門知識、スケジュール、コスト）が影響しているのでしょうか。このセクションでは、その場にいなかった読者が、なぜこの決定が必要だったのかを理解できるようにします。

  4. 決定を明記する 何を決定したのかを明確に述べます。「決定されました」ではなく、「私たちは……を使用します」のように能動態を使います。決定に含まれるものと含まれないものを具体的に示します。

  5. 結果を記録する この決定による結果を、肯定的、否定的、中立的なものに分けて列挙します。優れた ADR は、トレードオフを正直に記録します。何が容易になり、何が難しくなるのでしょうか。新たにどのような制約や選択肢が生まれるのでしょうか。

  6. モデル選択による結果を記録する (モデルを選択する、またはシステムを特定のモデルに依存させる決定の場合のみ) それ以外の場合は、この手順を丸ごと省略します。これは Consequences 内の小見出しであり、7 つ目の見出しではありません。モデルの選択は、通常の依存関係の選択とは、ADR に関わる重要な点で異なります。評価対象は、多くの場合、この決定が有効な間に置き換えられることになります。そのため、どの選択肢が勝ったかだけでなく、その選択を取り消すためにかかるコストも記録します。モデルを構築するのか、購入するのか、それとも汎用モデルにプロンプトを与えるのか、また他の 2 つの選択肢を退けた理由を明記します。プロンプト、評価セット、出力スキーマ、レイテンシの予算など、選択に何が結び付いたのかを記録します。受け入れる運用コストと、それが許容できなくなる利用量を明らかにします。その結び付きによって実際にどれほどの取り消しコストが生じるのか、そしてこの ADR を再検討するきっかけとなる観測事項を記録します。これはレビュー日ではなく、再検討のトリガーです。

出力形式

references/TEMPLATE.md のテンプレートを使用して、出力を構成します。完成した ADR では、テンプレートのすべてのセクション（Status、Context、Decision、Consequences、Alternatives Considered、References）を記入します。

品質チェックリスト

最終版にする前に、次の点を確認してください。

  • タイトルが簡潔で内容を表す名詞句になっている
  • ステータスが明確に示されている（Proposed／Accepted／Deprecated／Superseded）
  • この決定が必要になった理由がコンテキストで説明されている
  • 決定が能動態で明確に述べられている
  • 影響に、肯定的な結果と否定的な結果の両方が含まれている
  • ADRが他のドキュメントを参照しなくても単独で理解できる
  • 決定でモデルを選択、または採用する場合、結合度、運用コスト、撤回コスト、そして決定を再検討するきっかけとなる状況がすべて記録されている

例

完成例については、references/EXAMPLE.mdを参照してください。

コメント

Markdown 対応