アーキテクチャ意思決定記録

アーキテクチャ意思決定記録 (ADR) は、重要なアーキテクチャ上の決定とその背景および結果を記録する軽量なドキュメントです。このスキルは、プロジェクト内でADRを作成・維持するためのテンプレート、例、ベストプラクティスを提供します。

概要

• データベース、フレームワーク、クラウドプロバイダーなどの重要な技術選択
• システムアーキテクチャまたはメジャーコンポーネントの設計
• チーム向けのパターンまたは規約の確立
• 複数のアプローチ間のトレードオフ評価
• 将来の開発に影響を与える決定の文書化

なぜADRが重要なのか

ADRはチームのアーキテクチャメモリとして機能します：

• コンテキストの保存: 何が決定されたかだけでなく、なぜそうなったのかをキャプチャします
• オンボーディング: 新しいチームメンバーがアーキテクチャの根拠を理解するのに役立ちます
• 再検討の回避: 確定した決定についての終わりのない議論を避けます
• 進化の追跡: アーキテクチャが時間とともにどのように進化したかを確認します
• 説明責任: 明確な所有権と決定のタイムラインを確立します

ADRフォーマット (Nygardテンプレート)

各ADRは以下の構造に従うべきです:

1. タイトル

フォーマット: ADR-####: [決定のタイトル] 例: ADR-0001: マイクロサービスアーキテクチャを採用する

2. ステータス

決定の現在の状態:

• Proposed: 検討中
• Accepted: 決定が承認され実装中
• Superseded: 後の決定に置き換わった (ADR番号を参照)
• Deprecated: 推奨されていないが、まだ置き換わっていない
• Rejected: 検討されたが採択されなかった (理由を文書化)

3. コンテキスト

含めるべき内容:

• 問題ステートメントまたは機会
• ビジネス/技術上の制約
• ステークホルダーの要件
• システムの現在の状態
• 関係する力 (相反する懸念)

4. 決定

含めるべき内容:

• 下された選択
• 従うべき主要な原則またはパターン
• その結果として何が変わるのか
• 実装の責任者

具体的かつ実行可能であること:

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

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など。 複数のプロジェクトでも単一のシーケンスを維持します。

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-scalability	高	スケーリング質問、データ量、成長予測
interrogation-reliability	高	データパターン、UX影響、一貫性検証
interrogation-security	高	アクセス制御、テナント分離、攻撃面

避けるべき一般的なピットフォール

❌ 技術的すぎる: 「これら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 管理元: AI Agent Hub Team

機能の詳細

adr-creation

キーワード: adr、アーキテクチャ意思決定、意思決定記録、決定を文書化 解決:

• アーキテクチャ決定を文書化するにはどうすればよいですか?
• ADRを作成する
• アーキテクチャ意思決定テンプレート

adr-best-practices

キーワード: いつADRを書くか、ADRライフサイクル、ADRワークフロー、ADRプロセス、ADRレビュー、影響を定量化 解決:

• いつADRを書くべきですか?
• ADRライフサイクルをどのように管理しますか?
• ADRレビュープロセスは何ですか?
• 決定の影響をどのように定量化しますか?
• 避けるべきADRのアンチパターン
• 関連するADRをリンク

tradeoff-analysis

キーワード: トレードオフ、メリット/デメリット、代替案、比較、オプションの評価 解決:

• トレードオフをどのように分析しますか?
• アーキテクチャオプションを比較
• 検討された代替案を文書化

consequences

キーワード: 結果、影響、リスク、利点、結果 解決:

• この決定の結果は何ですか?
• 決定の影響を文書化
• リスクと利点分析