目次
テンプレートは、どこに文章を書くかをAIに示します。アーキテクチャ決定記録(ADR)を読みやすく保つには、何を記載し、何を別の場所に置くかを定義し、執筆者とレビュアーが同じルールを使う必要があります。
要点#
- ADRには長く有効な決定を残し、タスクの進捗、移行スケジュール、通常の実装詳細は別の場所に移す。
- 過去の議論をたどり直さなくても決定を理解できるよう、プロジェクトが実際に抱える問題を説明する。
- 繰り返されるレビューコメントから執筆ルールを作り、ルールIDと例で修正内容を具体化する。
- AIの執筆者とレビュアーには、別々の指示ではなく、共通のガイドラインを与える。
テンプレートの限界#
TOKIUMのプロダクトチームには、すでに「背景」「決定」「結果」、任意の「検討した代替案」を備え、メタデータにステータスと日付を記載するADRテンプレートがありました。AIは各セクションを埋めましたが、できあがった記録はレビューしづらいことが少なくありませんでした。
あるADRには、移行の依存関係図と23行のタスク表が含まれていました。別のADRでは、通常の設定をシークレットと一緒に保存する仮定上のリスクを説明しながら、プロジェクトですでにそうしている事実が書かれていませんでした。メールの安全性に関するADRでは、長く有効な方針に、メソッド名、環境変数の構文、アドレス照合の詳細が混在していました。
これらの文書には有用な情報が含まれていました。問題は置き場所です。読者は、一時的な作業や実装手順から決定を切り分け、不足する背景を補う必要がありました。見出しを増やしても解決しません。
決定の境界を引く#
ADRは、問題、選んだ対応、その結果を説明するものです。実装が変わり、移行が終わった後も役立つ必要があります。
草稿をレビューするときは、次の4つの境界を使います。
| ADRに残すもの | 別の場所に置くもの | |---|---| | 移行中に満たすべき条件 | タスクの担当、期限、進捗 | | 許可されていない宛先へのメール送信を防ぐ要件 | 環境変数名と解析の構文 | | プロジェクトの現在の設定上の問題 | 実際の状況に触れない一般的な警告 | | 受け入れたトレードオフとその根拠 | 詳細な実装手順 |
たとえば、「ステージング環境のメールは承認済みの宛先にのみ送信し、設定がない場合は送信を禁止する」は、長く有効な要件を表します。カンマ区切りの設定や小文字への正規化は、通常、仕様書や実装記録に記載すべき内容です。
この決定が有効なまま、実装だけが変わることはあるか? と問いかけます。そうであれば、その実装に依存する詳細は、おそらく別の場所に置くべきです。ただし、判断は必要です。特定の技術やプロトコルを選ぶこと自体が、アーキテクチャ上の決定になる場合もあります。抽象化しても、その選択は残すべきであり、消してはいけません。
レビューコメントをルールにする#
TOKIUMは、ADRを変更した34件のPRと830件のレビューコメントを調べ、32のルールを抽出しました。理想の文書を想像するのではなく、レビューで繰り返し起きる問題を出発点にする、有用な方法です。
自分たちのリポジトリでも、最近のADRレビューコメントを集め、繰り返される修正を分類します。各ルールには、固定のID、要求レベル、短い例を付けます。MUSTは受け入れの必須条件に限定し、例外を正当化できるものにはSHOULDを使います。
最初は、次のような少数のルールから始められます。
- C-1、MUST: 事実に関する記述を、コードまたは一次資料で確認する。
- C-3、MUST: ADR内で問題と決定を理解できるようにする。
- D-1、MUST: 移行の進捗とタスク表はADRの外に置く。
- D-4、SHOULD: 実装の選択自体が決定でない限り、実装の自由度を保つ。
判断を要するルールには、実用的な問いを添えます。D-1なら、その文章はタスクが完了すると不要になるかを問います。ガイドラインに古いプロジェクトの決定を誤って残さないよう、良い例と悪い例は架空のものにします。
ルールの参照元を一本化する#
ガイドラインをADRテンプレートと同じ場所に置き、執筆開始前に両方を参照できるようにします。レビュープロンプトに隠されたルールでは遅すぎます。執筆者がその存在を知るのは、文書を提出した後だからです。
ADRの執筆フローとAIレビューのフローに、同じガイドラインを組み込みます。ツールがディレクトリごとの指示に対応しているなら、ADRファイルの編集中にガイドラインを読み込む短い参照指示を使います。複数のプロンプトにルール全文をコピーすると内容がずれるため、避けます。
レビューの指摘には、該当ルール、問題のある箇所、必要な修正を明記させます。「D-1:この進捗表を移行計画に移す」なら、執筆者は何をすべきか分かります。「読みやすくする」では分かりません。
根拠と責任の所在を確認する#
体裁の整ったADRでも、誰も検証できない根拠に依存していることがあります。TOKIUMは、対面の会議だけを根拠とする決定や、リポジトリに存在しないテスト計画への委任を、AIレビューが指摘したと報告しています。
ADRを受け入れる前に、根拠を参照できること、委任した作業に実在する文書への参照か明確な担当者があることを確認します。未解決の決定は、確定事項として扱わず、未解決だと分かる形で残します。
報告された例は、共通ルールによってレビューコメントをより具体的にできることを示しています。ただし、レビュー時間の短縮を実測した結果でも、AIがアーキテクチャの品質を判断できる証明でもありません。その決定が問題を解決するか、コストを受け入れられるかは、引き続き人間が評価する必要があります。
次の一歩#
直近5件のADRのPRを見直し、最も多かった修正を、ID、要求レベル、架空の修正前後の例を備えた共通ルールにしてください。
出典: https://zenn.dev/tokium_dev/articles/adr-authoring-guideline
目次
