概要

生成AIコーディングにより、コード実装とドキュメント作成は飛躍的に効率化されました。
しかし同時に、「なぜこの実装を選んだのか」という意思決定の背景や、ハルシネーションによる誤った実装の採用といった新たな課題も生まれています。

ここでは、技術選択の意思決定コンテキストを確実に残すための手法として、
ADR（Architectural Decision Record）を活用した「ADR駆動開発」を説明します。

ここでの「ADR駆動開発」とは

生成AIを活用した開発において、調査段階からADR（Architectural Decision Record）を作成し、
技術選択の意思決定プロセスを透明化する開発手法を指します。

従来のADRが「決定後の記録」であるのに対し、ADR駆動開発では以下の観点を重視します。

調査段階から作成を開始
生成AIの提案内容と検証結果を記録
選ばなかった選択肢とその理由を明記
実装コードからADRを参照

これにより、「なぜこの実装にしたのか」というコンテキストをプロジェクトに確実に残すことができます。

ADR駆動開発のフロー

フローは非常にシンプルで、従来の開発フローの中で実装方法を調査していた結果とADRテンプレート（後述）を組み合わせるだけです。

調査フェーズ
- 人間またはClaude/Geminiなどの生成AIで初期調査
- 複数の選択肢を列挙
- 各選択肢の詳細を調査
- 問題なさそうな選択肢を実装・検証
ADR作成フェーズ
- 生成AIに調査フェーズの情報とテンプレートを指定し、ADRを生成
- Considered options（検討した選択肢）にはハルシネーションや誤情報も記録
実装フェーズ
- コードにADRへのリンクを記載
- ドキュメントから相互参照

実例：AWS AmplifyでのBasic認証実装

以下は、AWS AmplifyでBasic認証を実装しようとした際の事例です。

生成AIからの提案と検証結果

調査段階で、複数の生成AI（Claude、Gemini等）から以下の選択肢が提案されました：

Option A: AWS Amplify Access Control（環境変数）（✅採用）
Option B: AWS Amplify Access Control（CfnParameter）
Option C: Next.js Middleware による認証
Option D: CloudFront Functions による認証（❌ハルシネーション）
Option E: Amazon Cognito による認証

Option D: CloudFront Functions による認証は複数の生成AIから推奨されましたが、実際にはAmplifyが管理するCloudFrontディストリビューションはユーザーが直接操作できないため、実装不可能でした。

このような生成AIのハルシネーションも記録に残すことで、他のメンバーが同じ落とし穴にハマることを防げます。

この事例は以下の記事で解説しています：
https://qiita.com/watta10/items/b199d3448e17dcb62493

ADRテンプレート

生成AIにADRを作成させるため、プロジェクトのCLAUDE.mdなどに以下の情報を記載します。

「ADRを作成すべきケース」の条件
ADR作成時はADRテンプレートを利用する指示

以下がADRテンプレートです。ベースは AWSのADR です。

ADR-template.md

ADR (Architecture Decision Record) を作成する際は、以下のフォーマットを使用してください。

## ファイル命名規則

- **ファイル名**: `ADR-XXX-[決定事項のタイトル].md`
- **番号**: 001から開始の3桁連番（例：ADR-001、ADR-002）
- **タイトル**: kebab-case（ハイフン区切り）で記載

例：
- `ADR-001-database-selection.md`
- `ADR-002-authentication-method.md`
- `ADR-003-frontend-framework.md`

## ADR更新時の注意事項

**重要**: 既存のADRファイルは編集せず、新しいADRファイルを作成してください。

### 既存ADRとの関係性の表現
- `Supersedes ADR-001`: ADR-001を完全に置き換える
- `Amends ADR-003`: ADR-003を部分的に修正・拡張する
- `Deprecates ADR-005`: ADR-005を廃止する

## フォーマット

```markdown
# ADR-XXX: [決定事項のタイトル]

**Status:** [Proposed | Accepted | Deprecated | Superseded by ADR-XXX]
**Date:** YYYY-MM-DD

## Problem statement: 解決する問題

## Decision drivers: 決定要因
* 制約条件1（例：複数プロジェクトでの再利用性）
* 要件1（例：新メンバーのオンボーディング時間短縮）
* リスク1（例：メンテナンスコスト）

## Considered options: 検討した選択肢
* Option A: [選択肢A]
* Option B: [選択肢B]
* Option C: [選択肢C]

## Decision outcome: 決定内容
**Chosen option:** "Option A"
**Reasoning:** 選択した理由を2-3行で

### Trade-offs: トレードオフ
* ✅ メリット1
* ✅ メリット2
* ❌ デメリット・制約1
* ❌ デメリット・制約2

## Option B の不採用理由: [選択肢B]

## Option C の不採用理由: [選択肢C]

## Links: 参考リンク
* [参考リンク1](URL)
* [参考リンク2](URL)
```

## 使用方法

1. ADR番号（ADR-XXX）は連番で管理
2. Statusは決定のライフサイクルを示す
3. 各セクションは具体的で実行可能な内容を記載
4. トレードオフは明確にメリット・デメリットを分けて記載

## 参考リンク

- [AWS Prescriptive Guidance - ADR FAQ](https://docs.aws.amazon.com/ja_jp/prescriptive-guidance/latest/architectural-decision-records/faq.html)
- [ADR GitHub - 既存テンプレート集](https://adr.github.io/#existing-adr-templates)

まとめ

生成AIは便利ですが、ハルシネーションやカットオフの問題があり提案が必ずしも最新・正確ではありません。
また、「できないこと」は公式ドキュメントに書かれていないことがほとんどです。
せっかく実装のために調査した結果がドキュメントとして残らない問題をADRにより解決します。

ADR駆動開発により、調査の試行錯誤をプロジェクトの資産として残すことができます。

テンプレートを用意しておけば、生成AIによるADRの生成が容易になり、持続可能な開発プロセスとして運用できます。