adr-author

ADR 作成ガイド

将来の開発者が実際に読み、自動レビューシステムで適用できるアーキテクチャ決定記録の作成を支援します。Documenting Architecture Decisions に記載された Michael Nygard の形式に基づいています。

ADR の考え方

ADR は、ある時点での決定を記録するものです。何を決定したのか、その理由は何か、そしてその結果どうなるのかを示します。読者は、違和感のあるコードに遭遇し、その背景にある考え方を理解する必要がある将来の開発者（または AI レビュアー）です。

Decision セクションは ADR の要です。ここに記された内容が適用されます。その他のセクション（Context、Consequences）は、適用が恣意的ではなく妥当だと感じられるよう、その理由を示します。労力の大半を Decision セクションにかけ、チームが実際に必要とする適用可能性のレベルで記述してください。

ワークフロー

ステップ 1：既存の ADR を読む

何かを書く前に、プロジェクトに既存の ADR があるか探して読みます。通常は docs/adr/、doc/arch/、または decisions/ にあります。次の点を確認してください。

• 番号付けの方式（連番、日付の接頭辞など）
• セクションの構成（チームによっては「検討した代替案」や「参考資料」を追加しています）
• 文体と詳細度
• ステータスの慣例

既存の形式に合わせます。一貫性は、どのテンプレートよりも重要です。

ステップ 2：決定内容を把握する

ユーザーに質問します（コンテキストから明らかでない場合）。

1. 決定内容は何ですか？ どのようなアーキテクチャ上の選択を行いますか？
2. 問題は何ですか？ どのような要因や緊張関係が、この決定につながりましたか？
3. どのような代替案を検討しましたか？ 簡潔でも構いません。これらは Context に記載します。
4. どのように適用しますか？ これによって適用可能性のレベルが決まります。

4 つ目の質問は、このスキルが追加する重要な質問です。多くの ADR ガイドでは省略されていますが、ADR が生きた契約になるか、棚に置かれたままになるかを左右します。

ステップ 3：適用可能性のレベルを選ぶ

適用可能性は品質を表すものではありません。適用可能性が LOW の ADR でも、優れたものになり得ます。どのような検証が可能で、適切かを表します。

HIGH — 自動ツールで準拠状況を確認できます。ファイルパス、数値のしきい値、バージョン制約、厳密な形式など、具体的で測定可能な要件がある場合に使用します。Decision セクションには、検証可能な具体的パターンが 2 つ以上必要です。

MEDIUM — 明確な指針に基づいて、人間のレビュアーが準拠状況を確認できます。判断を要するアーキテクチャパターン、禁止事項、品質ガイドラインに使用します。Decision セクションには、2 人のレビュアーがコードの準拠状況について同じ判断をできるだけの具体性を備えた、明確なガイドラインが 1 つ以上必要です。

LOW — 参照と背景説明のみを目的とします。原則、歴史的な根拠、推奨事項に使用します。適用の仕組みは必要ありません。物事が現在の形になった理由を理解するうえで、こうした ADR は役立ちます。

ユーザーに希望するレベルを尋ねます。迷っている場合は、決定の性質を基に選べるよう支援してください。リンタールールやスクリプトで確認できるなら HIGH です。レビュアーが明確なはい／いいえで確認できるなら MEDIUM です。妥当な人でも異なる適用方法を選び得る指針なら LOW です。

ステップ 4：ADR を作成する

Michael Nygard の 4 つのセクションを使用します。文章と段落で記述してください。ADR は要件仕様書ではなく、将来の開発者との対話です。

# ADR [NUMBER]: [Short noun phrase]

## Status

[Proposed | Accepted | Deprecated | Superseded by ADR-XXX]

## Context

[Forces at play — technological, political, social, project-local.
Present tensions neutrally. Explain why a decision is needed now.]

## Decision

We will [decision in active voice].

[The enforceable substance goes here — see patterns below.]

## Consequences

[What becomes easier, what becomes harder, what new problems arise,
what trade-offs are we accepting. Be honest about downsides.]

書式ガイドライン（Nygard に準拠）：

• 全体で 1～2 ページ
• 箇条書きだけではなく、文章と段落で記述する
• Decision では能動態を使う（「私たちは～します」。「～と決定されました」ではありません）
• Context では中立的な語調を使い、意見は Decision に記載する
• 連番を付け、番号を再利用しない

ステップ 5：対象レベルに合わせて Decision セクションを記述する

適用可能性のパターンが重要になるのはここです。自動ツールがスキャンし、レビュアーが PR と照合するのは Decision セクションです。

HIGH の強制可能性を備えた意思決定の記述

HIGH の意思決定は自然な文章でありながら、具体的で抽出可能な制約を含みます。読みやすい文章に、検証可能な事実を埋め込むものと考えてください。

自動化を可能にする6種類のパターン：

1. ファイルパス — バッククォートで囲んだ正確な場所

   すべての API ルートは src/api/v2/ に配置します。コンポーネントは src/components/{feature}/{ComponentName}.tsx に配置します。

2. 測定可能な制約 — 単位を伴う数値

   データベースクエリは30秒後にタイムアウトします。ページごとのバンドルサイズは 250kbを超えないようにします。

3. 設定値 — key:value または key=value のペア

   HTTP クライアントには timeout: 5000 を使用します。接続プールには maxConnections = 10 を使用します。

4. バージョン制約 — 特定のバージョン要件

   Node.js >= 20.0.0 を使用します。React の依存関係には ^18.0.0 を指定します。

5. 形式の仕様 — 正確な構造パターン

   エラーレスポンスは次の形式にします：{error: string, code: number, details?: object}。 コミットは次の形式にします：type(scope): description。

6. 具体的な対象を示す宣言文 — 「Y には X を使用する」

   新規ファイルにはすべて TypeScript を使用します。非同期処理には Promise チェーンではなく async/await を使用します。

これらのパターンのうち少なくとも2種類を含めてください。具体例を追加し、検証方法（CI チェック、リンタールール、コードレビューのチェックポイント）を示し、例外を明記してください。

HIGH の意思決定の例：

## Decision

We will standardize on Next.js App Router for all new pages.

All new routes will use the `app/` directory structure with files at
`app/{route}/page.tsx`. For example, product detail pages go in
`app/products/[id]/page.tsx`. Components will be Server Components by default —
only add `'use client'` when client-side interactivity is required (forms,
onClick handlers, browser APIs).

Bundle size increases will be limited to 10% per feature. Any use of 'use
client' must be justified in the PR description explaining why server rendering
is insufficient.

The existing `pages/` directory remains for maintenance. New features use `app/`
starting March 2024. Migration happens opportunistically during major updates.

Verification: CI checks that new routes are in `app/` not `pages/`. ESLint rule
flags `'use client'` files without a justification comment.

MEDIUM の強制可能性を備えた意思決定の記述

MEDIUM の意思決定では、レビュアーがはい／いいえで判断できるだけの明確な指針を示します。パターンは正確な値よりも、曖昧さのない意図を重視します。

レビュアーが確認できる意思決定の5種類のパターン：

1. 明確な禁止事項 — 行わないこと

   新しい React コードではクラスコンポーネントを使用しません。独自の認証は 禁止し、Auth0 を使用します。

2. 実装要件 — 従うべきパターン

   すべてのエンドポイントで入力検証を行います。サービスのインスタンス化には 依存性注入を使用します。

3. 品質／セキュリティのガイドライン — 適用範囲が明確な標準

   データベースクエリではパラメーター化クエリを使用し、SQL の文字列を 直接連結することは禁止します。すべての HTTP レスポンスにセキュリティ ヘッダーを設定します。

4. アーキテクチャパターン — 構造上の決定

   新しいサービスにはマイクロサービスアーキテクチャを採用し、それぞれが 独自のデータを管理して REST API を公開します。

5. 全体に適用される要件 — 「すべての X は Y すること」という記述

   すべての公開関数にユニットテストを設けます。すべての API 変更で OpenAPI 仕様を更新します。

レビュアーが確認すべき項目を正確に把握できるよう、レビューチェックリストを含めてください。

MEDIUM の意思決定の例：

## Decision

We will standardize error handling across all services.

All async operations will use try-catch blocks. Errors will be wrapped with
context using typed error classes (ValidationError, AuthenticationError,
ExternalServiceError) extending a base ApplicationError. User-facing errors
will not expose internal details — they follow the format:
{message: string, code: string, details?: object}.

All errors will be logged with correlation IDs for request tracing. Sensitive
data will be sanitized before logging.

Review checklist:
- Async operations have try-catch with context
- Appropriate error class is used
- User-facing errors are sanitized
- Errors are logged before handling/re-throwing

LOW の強制可能性を備えた意思決定の記述

LOW の意思決定では、根拠と原則を記録します。どのようにを規定せずに、なぜを理解するうえで役立ちます。

## Decision

We chose PostgreSQL over MongoDB for our primary datastore. Our data model is
heavily relational with complex joins across orders, inventory, and customer
records. PostgreSQL's ACID transactions and mature tooling ecosystem align with
our reliability requirements.

We considered MongoDB for its schema flexibility, which would benefit our
rapidly changing product catalog. However, the transactional integrity
requirements for financial data outweigh the flexibility benefits.

Future iterations may introduce a document store for the product catalog if
schema changes become a bottleneck.

ステップ6：レビューと改善

草案が目標レベルに合っているか確認します。

HIGH の場合 — 各要件を検証するスクリプトやリンタールールを作成できますか？できない場合、まだ HIGH ではありません。曖昧な表現（「適切な」「クリーンな」「良い」など）を探し、具体的な表現に置き換えてください。

MEDIUM の場合 — 独立した2人のレビュアーが、コードが要件に準拠しているかについて同じ判断を下せますか？合理的な人同士で意見が分かれるほど要件が曖昧な場合は、より具体的にする（HIGH に引き上げる）か、指針としての記述であることを認める（LOW に引き下げる）かしてください。

LOW の場合 — 5年後の開発者にも理由が理解できるほど、なぜを明確に説明していますか？それが基準です。

よくある改善方法：

曖昧 → 具体的（LOW → HIGH）：

Before: "Use good error handling"
After:  "All async functions will use try-catch with structured logging:
         {level: string, message: string, stack?: string}"

抽象的 → 具体的（LOW → MEDIUM）：

Before: "Consider security"
After:  "All user inputs will be validated against SQL injection and XSS
         using the sanitization library"

厳格すぎる → 実用的（HIGH → MEDIUM）：

Before: "All components must be exactly 50 lines or less"
After:  "Components should stay under 100 lines; split when they handle
         multiple concerns"

ステップ 7：結果を正直に記述する

結果セクションは信頼を築きます。メリットしか挙げていないと、売り込みのように見え、今後の開発者から信頼されなくなります。以下を含めてください。

• 何が容易になるか（メリット）
• 何が難しくなるか（コスト）
• どのような新たな問題が生じる可能性があるか（リスク）
• どのようなトレードオフを受け入れるか（意識的な選択）

よくあるアンチパターン

曖昧な指示：「クリーンなコードを書くこと」→「.eslintrc.js の ESLint ルールに警告ゼロで合格すること」

強制できない絶対条件：「すべてのコードは完璧でなければならない」→「すべての公開関数に、ブランチカバレッジ 80% 超のテストを用意すること」

制約のない技術指定：「フロントエンドには React を使用する」→「新しいコンポーネントには、TypeScript の strict モードで React >= 18.0.0 を使用すること」

例の欠如：「適切な命名規則に従う」→「関数には camelCase（getUserData）、コンポーネントには PascalCase（UserProfile）、定数には UPPER_SNAKE_CASE（MAX_RETRY_COUNT）を使用すること」

強制可能性の混在：同じ「決定」セクションで、「ファイルは src/ に置くこと」（高）と「適切なアーキテクチャを採用すること」（低）を組み合わせないでください。具体性のレベルを揃えるか、異なるレベルの要件を番号付きで分けてください。

参考ファイル

包括的なパターン集やすぐに使えるテンプレートについて詳しく知りたい場合は、以下を参照してください。

• references/enforceability-patterns.md — 自然な文章と指示的なスタイルの両方の例、パターン認識のキーワード、検証方法、レベル間の改善手順を含む、すべてのパターンタイプを網羅したカタログです。特定のパターンを見分ける必要がある場合や、ユーザーがあるレベルから別のレベルへ改善するのを支援する場合に参照してください。

• references/templates.md — 高・中・低の強制可能性を持つ ADR のコピー＆ペースト用テンプレートで、それぞれに完全な記入例が付いています。ユーザーが記入用のテンプレートを求めている場合に参照してください。