2026.11.04

【インフラ設計×Claude #2】その設計、「なぜ」を残していますか？ ― 方針書とADRの分け方

AI AI駆動開発(AIDD)AWS Claude / GitHub Copilot y-sakakibara クラウドネイティブ生成AI活用

はじめに

前回のおさらい

前回は、IPAの非機能要求グレード238項目を、72項目の非機能要件へ整理した話を書きました。

【インフラ設計×Claude #1】非機能要件をClaudeと策定する

今回は、その非機能要件から、インフラ構成方針書とADR（Architecture Decision Record）をどう設計したかを書きます。連載全3回のうち、2回目です。

第1回：非機能要件をClaudeと策定する
第2回（本記事）：その設計、「なぜ」を残していますか？ ― 構成方針書とADRの分け方
第3回：同じ問いなのに、AIの結論が正反対になった ― Claudeと進めた設計の手戻り記録

構成方針書やADRをこれから書く方に向けた記事です。顧客を特定できる情報は伏せ、案件固有の内容は一般化しています。

成果物の全体像

最初に、成果物同士の関係を整理します。

検討項目一覧の意義

構成方針書とADRより先に作ったのが、検討項目一覧です。構成方針書もADRも、検討項目ごとに1ファイルで書くので、ファイルが増えると、全体を見渡しにくくなります。そこで、先に一覧を作り、これを土台にしました。

一覧には、2つの目的がありました。

一覧性を高める：1行が1つの検討項目で、構成方針書の項目ファイルとADRに対応する。
項目間の関連を把握しやすくする：項目を1つの一覧に並べておくことで、関連する項目を見つけやすくする。

方針書とADRを分ける理由

「今守ること」と「なぜそうしたか」

最初に決めたルールは、とてもシンプルです。

方針書＝今守ること
ADR＝なぜそうしたか

構成方針書もADRも、基本は関係者全員が参照する想定です。まずは、構成方針書だけで内容が完結するようにしました。そのため、選択肢の比較や、選ばなかった案の話は、構成方針書に持ち込みません。

ADRは、設計方針を変えるときのために作っています。以前の議論や、なぜこの構成にしたのかが分かるようにしておくためです。

ADRのテンプレート

ADRのテンプレートは次のとおりです。

# ADR-XXX-000: <決定内容を一文で>

| 項目 | 内容 |
|---|---|
| 最終更新日 | YYYY-MM-DD（書き換えたら更新） |
| 起票者 | <組織名> |
| 対象の検討項目 | <検討項目へのリンク> |
| 関連 | <関連ADR／文書> |

## 決めること
ログの保存先を1か所に集約するかどうかを決める。

## 背景・前提

## 判断の軸
（選択肢より先に定める）

## 選択肢
### 案A: 集約する
- 概要 / メリット / デメリット
### 案B: 各環境に置く
- 概要 / メリット / デメリット

## 決定
- 決め手:
- 選ばなかった案:

## 見直す条件

## 影響

## 備考

こだわったのは、「判断の軸」を選択肢より先に書くことです。軸を先に決めておくと、選択肢を比較するときに、後付けの理屈を入れにくくなります。

設計書は「Markdownで書き、実装工程でコーディングAIが参照できるようにする」方針で、リポジトリ管理にしました。

ADRの運用ルール

検討項目とADRは1対1。決定を覆すためだけに新しいADRは作らず、書き換えて、何を変えたかを「決定」に一文残す。
方針を変えるときは、ADRを先に起票し、承認後に方針書へ反映する。

非機能要件から構成方針書までの流れ

実際の作業は、次の5つの手順で進めました。

検討項目を定める：顧客が独自に策定していたクラウドデザインガイドを参考に、10カテゴリを定めました。
ADRにする項目を決める：各カテゴリから、構成の選択肢があるもの（たとえば、コンテナの実行基盤）と、今後構成が変わりうるものを選び、ADRとして残すことにしました。
構成を仮決めする：非機能要件、顧客のガイドライン、クラウド事業者のベストプラクティスに沿って、構成を仮決めしました。非機能要件との対応は、トレーサビリティマトリクスで確認しています。
顧客の承認を得て、本決定にする：仮決めした構成を顧客に提示し、承認されたら、本決定として構成方針書に記載しました。
決まらないものは、申し送り事項にする：現時点で決まらないものは、申し送り事項として残しました。

今回は、顧客が独自のクラウドデザインガイドを用意していたため、それを土台にしました。ガイドがない場合は、クラウド事業者が公開している設計指針を参考にできます。一例として、AWS Well-Architected Frameworkや、Google Cloud Well-Architected Frameworkがあります。

10個のカテゴリは、次のとおりです。