mcpField
A
architecture-decision-record

architecture-decision-record

github.com/yonatangross開発2991.5k 回インストール今日更新
リポジトリ

architecture-decision-record について

Architecture Decision Recordsは、重要なソフトウェアアーキテクチャの選択を記録するチーム向けスキルです。ADRの構成、ライフサイクル、テンプレート、生成スクリプトにより、背景や代替案、結果を整理できます。

主な機能

  1. 01構造化されたADRの項目とテンプレート
  2. 02意思決定のライフサイクル案内
  3. 03代替案と結果の分析
  4. 04スクリプトによるADR生成

活用シーン

  1. 01技術選定の記録
  2. 02アーキテクチャ案の比較
  3. 03オンボーディング向けの判断根拠保存

インストール

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

$npx skills add https://github.com/yonatangross/orchestkit --skill architecture-decision-record

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

同梱ファイル

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

test-cases.json
assets/
adr-template.md
checklists/
adr-review-checklist.md
examples/
adr-0001-adopt-microservices.md
adr-0002-choose-postgresql.md
adr-0003-api-versioning-strategy.md
references/
adr-best-practices.md
rules/
_sections.md
_template.md
interrogation-reliability.md
interrogation-scalability.md
interrogation-security.md
scripts/
adr-frontmatter.yaml
adr-manager.py
create-adr.md
list-adrs.py

詳細

アーキテクチャ決定記録

アーキテクチャ決定記録（ADR）は、重要なアーキテクチャ上の決定を、その背景や結果とともに記録する軽量なドキュメントです。このスキルでは、プロジェクトで ADR を作成、管理するためのテンプレート、例、ベストプラクティスを紹介します。

概要

  • データベース、フレームワーク、クラウドプロバイダーなど、重要な技術を選択する
  • システムアーキテクチャや主要コンポーネントを設計する
  • チームのパターンや規約を確立する
  • 複数のアプローチのトレードオフを評価する
  • 今後の開発に影響する決定を文書化する

ADR が重要な理由

ADR はチームのアーキテクチャ上の記憶として機能します。

  • 背景の保存：何を決めたかだけでなく、なぜ決めたかを記録します
  • オンボーディング：新しいチームメンバーがアーキテクチャ上の判断理由を理解できるようにします
  • 議論の再発防止：決着した決定について、終わりのない議論が繰り返されるのを防ぎます
  • 変遷の追跡：アーキテクチャが時間とともにどのように変化したかを確認できます
  • 説明責任：担当者と決定のタイムラインを明確にします

ADR の形式（Nygard テンプレート）

各 ADR は次の構成に従います。

1. タイトル

形式：ADR-####: [Decision Title] 例：ADR-0001: Adopt Microservices Architecture

2. ステータス

決定の現在の状態です。

  • 提案済み：検討中
  • 承認済み：決定が承認され、実装中
  • 置き換え済み：後続の決定に置き換えられた（ADR 番号を記載）
  • 非推奨：推奨されなくなったが、まだ置き換えられていない
  • 却下：検討したが採用されなかった（理由を記録）
3. 背景

含める内容：

  • 問題の説明または機会
  • ビジネス上／技術上の制約
  • ステークホルダーの要件
  • システムの現状
  • 影響する要因（相反する懸念事項）
4. 決定

含める内容：

  • 決定する選択肢
  • 従うべき重要な原則やパターン
  • その結果として何が変わるか
  • 実装の担当者

具体的で実行可能な内容にします。

  • ✅ 「Express を使用した Node.js によるマイクロサービスアーキテクチャを採用します」
  • ❌ 「マイクロサービスの使用を検討します」
5. 結果

含める内容：

  • 良い結果（メリット）
  • 悪い結果（コスト、リスク、トレードオフ）
  • 中立的な結果（変化はあるものの、明確に良くも悪くもないこと）
6. 検討した代替案

少なくとも 2 つの代替案を記録します。

各代替案について、次の内容を説明します。

  • どのような案だったか
  • なぜ検討したか
  • なぜ採用しなかったか
7. 参考資料（任意）

関連リソースへのリンク：

  • 会議の議事録やディスカッションスレッド
  • 関連する ADR
  • 外部の調査資料や記事
  • 概念実証の実装

ADR のライフサイクル

Proposed → Accepted → [Implemented] → (Eventually) Superseded/Deprecated
          ↓
      Rejected

ベストプラクティス

1. ADR を変更不可にする

承認後は ADR を編集せず、古い ADR に取って代わる新しい ADR を作成します。

  • ✅ ADR-0003 に取って代わる ADR-0015 を作成する
  • ❌ 新しい決定を ADR-0003 に追記する
2. 現在形で書く

ADR は、決定を今まさに行っているかのように記述する履歴記録です。

  • ✅ 「マイクロサービスを採用します」
  • ❌ 「マイクロサービスを採用しました」
3. 「方法」ではなく「理由」に焦点を当てる

ADR には決定を記録し、実装の詳細は記載しません。

  • ✅ 「リレーショナルデータの一貫性を保つため、PostgreSQL を選択します」
  • ❌ 「PostgreSQL を次の具体的な設定で構成します……」
4. チームで ADR をレビューする

承認する前に、関係するステークホルダーから意見を集めます。

  • アーキテクト：技術的な実現可能性
  • 開発者：実装の実現可能性
  • プロダクト担当：ビジネスとの整合性
  • DevOps：運用上の懸念事項
5. 連番を付ける

4 桁のゼロ埋め番号を使用します：ADR-0001、ADR-0002 など。 複数のプロジェクトがあっても、番号は 1 つの連番で管理します。

6. Git に保存する

コードとともに、ADR をバージョン管理下に置きます。

  • 場所：/docs/adr/ または /architecture/decisions/
  • 形式：読みやすい Markdown
  • ブランチ：実装と同じブランチ

クイックスタートのチェックリスト

オプション 1：スクリプト拡張ジェネレーターを使用する（推奨）
  • /create-adr [number] [title] を実行して、コンテキストが自動入力された ADR を生成します
  • ADR 番号、日付、作成者が自動入力されます
  • 決定の詳細を確認し、記入します
  • ステータスを「Proposed」に設定し、チームでレビューします
オプション 2：静的テンプレートを使用する
  • assets/adr-template.md から ADR テンプレートをコピーします
  • 次の連番を割り当てます（既存の ADR を確認してください）
  • コンテキストを記入します：問題、制約、要件
  • 決定を文書化します：何を、なぜ、どのように、誰が
  • 結果を列挙します：肯定的、否定的、中立的
  • 代替案を少なくとも 2 つ説明します：内容、長所と短所、選ばなかった理由
  • 参考情報を追加します：議論、調査、関連する ADR
  • ステータスを「Proposed」に設定します
  • チームでレビューします
  • 承認後、ステータスを「Accepted」に更新します
  • 実装 PR に ADR へのリンクを記載します
  • デプロイ後、ステータスを「Implemented」に更新します

利用可能なスクリプト

  • scripts/create-adr.md - コンテキストを自動入力する動的 ADR ジェネレーター

    • 自動入力項目：ADR 番号、日付、作成者、ADR の総数
    • 使用方法：/create-adr [number] [title]
    • $ARGUMENTS と !command を使用して動的なコンテキストを取得します

  • assets/adr-template.md - 手動で使用する静的テンプレート

ルールのクイックリファレンス

ルール影響度対象
interrogation-scalabilityHIGHスケーリングに関する質問、データ量、成長予測
interrogation-reliabilityHIGHデータパターン、UX への影響、一貫性の検証
interrogation-securityHIGHアクセス制御、テナント分離、攻撃対象領域

避けるべきよくある落とし穴

❌ 技術的すぎる：「これら 50 個の YAML 設定を使って Kubernetes を導入します……」 ✅ 適切なレベル：「コンテナーオーケストレーションに Kubernetes を使用します。なぜなら……」

❌ 曖昧すぎる：「より優れたデータベースを使います」 ✅ 具体的：「トランザクションデータには PostgreSQL 15+ を使用します。なぜなら……」

❌ 代替案がない：選択したソリューションだけを文書化する ✅ 比較する：代替案を選ばなかった理由を文書化する

❌ 結果が不足している：メリットだけを列挙する ✅ バランスを取る：コストとトレードオフについて率直に記述する

❌ コンテキストがない：「Redis を使うことにしました」 ✅ コンテキストを示す：「100 万人以上の同時ユーザーと 50ms 未満のレイテンシ要件を踏まえ……」

関連スキル

  • ork:api-design：ADR で参照する API を設計する場合に使用します
  • ork:database-patterns：ADR でデータベースの選択を扱う場合に使用します
  • security-checklist：ADR にセキュリティ上の影響がある場合に参照します

スキルのバージョン：2.0.0 最終更新日：2026-01-08 メンテナンス担当：OrchestKit

機能の詳細

adr-creation

キーワード： adr, アーキテクチャ決定, 決定記録, 決定の文書化 解決できる課題：

  • アーキテクチャ上の決定を文書化するにはどうすればよいですか？
  • ADR を作成する
  • アーキテクチャ決定のテンプレート
adr-best-practices

キーワード： ADR を作成するタイミング, ADR のライフサイクル, ADR ワークフロー, ADR プロセス, ADR レビュー, 影響の定量化 解決できる課題：

  • ADR はいつ作成すべきですか？
  • ADR のライフサイクルを管理するにはどうすればよいですか？
  • ADR のレビュープロセスはどのようなものですか？
  • 決定の影響を定量化するにはどうすればよいですか？
  • 避けるべき ADR のアンチパターン
  • 関連する ADR をリンクする
tradeoff-analysis

キーワード： トレードオフ, 長所と短所, 代替案, 比較, 選択肢の評価 解決できる課題：

  • トレードオフを分析するにはどうすればよいですか？
  • アーキテクチャの選択肢を比較する
  • 検討した代替案を文書化する
consequences

キーワード： 結果, 影響, リスク, メリット, 成果 解決できる課題：

  • この決定によってどのような結果が生じますか？
  • 決定の影響を文書化する
  • リスクとメリットを分析する

コメント

Markdown 対応