アーキテクチャ決定レコードの概要

Last reviewed 2024-08-16 UTC

インフラストラクチャまたはアプリケーション チームが特定の設計上の選択を行う理由を説明するために、アーキテクチャ決定レコード（ADR）を使用できます。このドキュメントでは、Google Cloud でアプリケーションをビルドして実行する際に ADR を使用するタイミングと方法について説明します。

ADR は、使用可能な主要なオプション、決定を推進する主な要件、設計上の決定事項をキャプチャします。ADR は、その決定に関連するコードベースの近くの Markdown ファイルに保存することがよくあります。リージョンの Google Kubernetes Engine（GKE）クラスタを使用する理由など、特定のアーキテクチャ決定の背景を理解する必要がある場合は、ADR を参照して関連するコードを確認できます。

ADR は、より信頼性の高いアプリケーションとサービスの実行にも役立ちます。問題が発生した際に、現在の状態の把握と、トラブルシューティングを容易にします。また、ADR は、将来の意思決定の選択とデプロイをサポートする一連のエンジニアリング上の決定も作成します。

ADR の用途

ADR を使用して、デプロイに重要と思われる主な領域を追跡します。ADR には次のカテゴリが含まれます。

  • 具体的なプロダクトの選択（Pub/Sub と Cloud Tasks の選択など）。
  • 特定のプロダクト オプションと構成（高可用性アプリケーション用のマルチクラスタ Ingress でリージョン GKE クラスタを使用するなど）。
  • Dockerfile マニフェストのベスト プラクティスなど、一般的なアーキテクチャ ガイダンス。

ADR の作成を求める可能性のある具体的な例は、次の選択肢のいずれかです。

  • Cloud SQL インスタンスの高可用性（HA）を設定する方法と理由。
  • GKE クラスタの稼働時間へのアプローチ方法。リージョン クラスタを使用しているかどうか。カナリア リリースを使用しているかどうか。その理由は何ですか。

ADR は、使用するプロダクトを評価する際、各決定の説明に役立ちます。チームが進化し、スタックについてさらに学習し、追加の決定や調整を行うときに、ADR を再検討できます。調整を行う場合は、前回の決定と変更の理由を含めてください。この履歴には、ビジネスニーズの進化に合わせてアーキテクチャがどのように変更されたか、または新しい技術要件や利用可能なソリューションがどこにあったかが記録されます。

ADR を作成するタイミングを知るには、次のヒントが役立ちます。

  • 技術的課題や技術的問題があり、推奨ソリューション、標準運用手順、ブループリント、コードベースなどの意思決定の根拠がない場合。
  • 自分またはチームが、チームがアクセスできる場所に文書化されていないソリューションを提供する場合。
  • 複数のエンジニアリング オプションがあり、選択の背後にある思考と理由を文書化する場合。

ADR を作成するときは、想定読者を意識することをおすすめします。主な読者は、ADR の対象となる技術に携わるチームのメンバーです。ADR の想定読者には、アーキテクチャやセキュリティ チームなど、意思決定を理解したいと考える隣のチームが含まれることもあります。

また、アプリケーションによってオーナーが変わることや、新しいチームメンバーが含まれる可能性があることも考慮する必要があります。ADR は、エンジニアリング上の選択の背景を理解するために役立ちます。ADR では、将来の変更を計画することも容易になります。

ADR の形式

通常、ADR は、複数の章から構成されます。ADR は、アプリケーションと組織にとって重要と思われることを捉える助けになる必要があります。ADR には、1 ページの長さのものもあれば、より長い説明を必要とするものもあります。

次の ADR 概要の例は、お客様の環境で重要な情報を含む ADR をどのようにフォーマットするかを示しています。

  • 著者とチーム
  • 解決するコンテキストと問題
  • 対応したい機能面と機能面以外の要件
  • 意思決定が影響する可能性があるクリティカル ユーザー ジャーニー（CUJ）
  • 主なオプションの概要
  • お客様の判断とその理由

決定を記録するために、選択が行われた日時を示す各決定のタイムスタンプを含めることができます。

ADR の仕組み

エンジニア、デベロッパー、アプリケーション オーナーが、ADR に含まれる情報に簡単にアクセスできる際に、ADR は最も効果的に機能します。なんらかの方法で特定の処理が行われた理由について質問がある場合は、ADR を調べてその答えを見つけることができます。

ADR にアクセスできるようにするために、一部のチームはソース管理リポジトリではなく、ビジネス オーナーもアクセスできる中央の Wiki で ADR をホストしています。特定のエンジニアリング上の決定に関して疑問が生じた場合に ADR が回答を提供します。

ADR は次のシナリオで適切に機能します。

  • オンボーディング: 新しいチームメンバーはプロジェクトを簡単に把握でき、新しいコードベースの学習中に疑問がある場合には ADR を確認できます。
  • アーキテクチャの進化: チーム間で技術スタックを移行する場合に、新しいオーナーは過去の決定事項を確認して現状を把握できます。新しいテクノロジーが利用可能になったときに、チームは過去の決定事項を確認することもできます。ADR は、同じ論点の繰り返しを回避することや、チームがトピックを再検討する際に歴史的な背景を提供することに役立ちます。
  • ベスト プラクティスの共有: チームは、ADR が特定の決定を行い、別の案が却下された理由の詳細について、組織全体のベスト プラクティスに配置できます。

ADR は通常、軽量かつテキストベースを維持するために Markdown で記述されます。Markdown ファイルは、アプリケーション コードと一緒にソース管理リポジトリに含めることができます。

ADR は、アプリケーション コードの近く（理想的には同じバージョン管理システム内）に保存します。ADR に変更を加える際、必要に応じてソース管理の以前のバージョンを確認できます。

共有 Google ドキュメントや内部 Wiki など、別のメディアを使用することもできます。 これらの代替の場所は、ADR のチームメンバーではないユーザーがよりアクセスしやすい場合があります。もう 1 つの方法は、ソース管理リポジトリで ADR を作成し、重要な決定をよりアクセスしやすい Wiki にミラーリングすることです。

次のステップ