AI駆動型ソフトウェア開発における意思決定記録
意図をコードに近づけよ。
意思決定記録は、AI支援ソフトウェア開発における欠けていた記憶層です。それらは何が開発されたかだけでなく、なぜ開発されたかを捉えます。そしてその区別は、AIツールがコードを書く際には決定的に重要になります。
意思決定記録は欠けていた記憶層です
AI駆動型プログラミングは、コードを生成するコストを低くし、リファクタリングを容易にし、廃棄を速くすることで、ソフトウェア開発の経済性を根本から変えます。これは有用です。しかし同時に危険でもあります。なぜなら、コードの生成が容易になることで、希少資源はもはやタイピングではなく「判断」になるからです。
チームはなぜDynamoDBではなくPostgreSQLを選択したのでしょうか？ なぜ製品はAI生成メールを送信する前に人間のレビューを必要とするのでしょうか？ なぜインターフェースは提案をサイドパネルに表示し、直接適用しないのでしょうか？ なぜよりシンプルなアプローチは6ヶ月前に拒否されたのでしょうか？ コードは存在しているものを示しますが、それが存在する理由を説明することは稀です。
意思決定記録は、重要な選択とその背景にある文脈、検討された代替案、チームが受容した結果を捉えた短く、バージョン管理されたドキュメントを提供することで、この問題を解決します。AI支援コードベースにおいて、これらの記録は単なるドキュメント以上のものになります。それらは、将来の変更を行う前に人間もAIコーディングエージェントも読むことができる、堅牢なプロジェクトの記憶になります。実用的な運用ルールはシンプルです：意思決定記録をリポジトリ内のMarkdownファイルとして保持し、コードのようにレビューし、将来の変更を提案または実装する前にAIツールがこれらを読めるようにします。
意思決定記録とは何ですか？
意思決定記録は、意味のある決定の書面による記録であり、4つの基本的な質問に答えるように構造化されています：何を決めたか、なぜそれを決めたか、どのような代替案を検討したか、どのような結果を受容したかです。最も一般的な形態は、Architecture Decision Record（アーキテクチャ意思決定記録）で、略してADRです。ADRは技術的な決定を文書化するために広く使用されており、同じパターンはアーキテクチャを超えて製品やデザイン作業にも拡張できます。
AI駆動型プログラミングにおいて、特に有用な3つのタイプがあります：
| 記録タイプ | 捕捉するもの | 例 |
|---|---|---|
| ADR | アーキテクチャおよび技術的な決定 | 主要データベースとしてPostgreSQLを使用する |
| PDR | 製品の動作および範囲に関する決定 | AI生成メールは下書きのままにする必要がある |
| DDR | デザインおよびインタラクションに関する決定 | AIの提案をサイドパネルに表示する |
ADR、PDR、DDRを組み合わせることで、システムの構造だけでなく、製品の意図やユーザー体験の背後にある理屈も記述できます。この組み合わせは重要です。なぜなら、AIエージェントはコードを読むことができますが、コードだけでは良い決定を行うための十分なコンテキストが含まれていないからです。意思決定記録は、AIシステムに、レビュー済み、堅牢、人間が承認したプロジェクトの意図のソースを提供します。
アーキテクチャ意思決定記録（ADR）
アーキテクチャ意思決定記録は、技術的および構造的な決定を捕捉します。システムのかたち（境界、依存関係、運用モデル、または長期的な保守性）に影響を与える決定がある場合に、ADRを使用します。
ADRとして記録する価値のある決定の例には以下が含まれます：
- 主要データベースとしてPostgreSQLを選択すること
- バックグラウンド処理のためにイベント駆動型アーキテクチャを使用すること
- アプリケーションをモジュラーモノリシック（モジュール化された単一構成）に保つこと
- メッセージキューの導入
- GraphQLではなくRESTを選択すること
- Webアプリケーションにサーバーサイドレンダリングを使用すること
- すべてのバックグラウンドジョブが冪等であることを要求すること
- 特定の認証および認可モデルを採用すること
ADRは完全なアーキテクチャドキュメントではありません。それは意図的に小さく、特定の時点で1つの重要な決定を記録するものです。良いADRは「アーキテクチャの健忘症」を防ぎます：それなしでは、将来の貢献者は同じトレードオフを再発見したり、古い議論を再開したり、重要な制約を偶然取り消したりする可能性があります。
AI駆動型プログラミングにおいて、ADRはさらに重量を持ちます。AIツールは局所的な最適化に長けていることが多く、より大きなアーキテクチャ制約に違反するが技術的には妥当な変更を提案する可能性があります。ADRはAIに明確な境界を与えます：「このシステムはこのようなかたちであるべきだ」というものです。
製品意思決定記録（PDR）
製品意思決定記録は、製品の動作、範囲、ユーザーに提示する意図を捕捉します。これはADRほど一般的ではありませんが、しばしば同等の価値があります。製品に関する決定は、チケット、ロードマップツール、チャットスレッド、会議ノート、および人々の記憶に散らばっており、人間が忘れるには容易く、AIツールが信頼して推論するにはほぼ不可能な状態になりがちです。
製品が何を行うか、誰を対象とするか、意図的に範囲外とするもの、またはユーザー向け機能がどのように動作すべきかが影響を受ける決定がある場合に、PDRを使用します。例には以下が含まれます：
- AI生成メッセージは、人間によってレビューされるまで下書きのままにする必要がある
- フリートレアーのユーザーは最大3つのプロジェクトを作成できる
- 削除されたワークスペースは30日間復元可能である
- チーム課金バージョン1では範囲外である
- ユーザーはサポートに連絡せずにデータをエクスポートできる
- 低信頼度のAI要約は隠すのではなく警告を表示する
PDRは、製品の選択がコードから見て任意的に見えるときに特に有用です。コードにはフリーユーザーのプロジェクト数が3という制限が含まれているかもしれません。PDRがなければ、AIツールはその数値をマジックナンバーとして扱い、変更を提案する可能性があります。PDRがあれば、AIはその制限が価格戦略、オンボーディングコスト、またはサポート負荷と結びついていることを、そしてそれを変更するにはクイックな編集ではなく意図的な製品決定が必要であることを理解できます。
デザイン意思決定記録（DDR）
デザイン意思決定記録は、ユーザー体験、インタラクション、ビジュアル、およびコンテンツデザインの決定を捕捉します。ユーザーが製品とどのようにインタラクションするか、情報がどのように提示されるか、またはデザイン原則が将来の作業にどのように適用されるかが影響を受ける決定がある場合に、DDRを使用します。
記録する価値のあるデザインの決定の例には以下が含まれます：
- サブミット時のみではなく、インライン検証を使用すること
- エディタ内ではなく、サイドパネルにAI提案を配置すること
- 高度な設定にプログレッシブディスクロージャー（段階的開示）を使用すること
- 破壊的なアクションの前に確認を求めること
- 「無効」と「有効」ではなく、「下書き」と「公開済み」を使用すること
- モバイル画面でも主要アクションを表示しておくこと
デザインの意図は実装中に失われやすいものです。開発者がフローを簡素化したり、AIエージェントが技術的には機能するが意図されたインタラクションモデルを壊すコンポーネントを生成したりする可能性があります。例えば、DDRは以下のように記録するかもしれません：「ユーザーが変更を受け入れる前に生成されたテキストと自分の下書きを比較する必要があるため、AIの書き込み提案はドキュメント内ではなく横に表示します。」この記録は、将来の貢献者にコピーすべきレイアウトだけでなく、守るべき原則を提供します。
AIに伴い、なぜ意思決定記録が重要になるのか
AIコーディングツールは強力ですが、しばしばステートレス（状態を持たない）か、プロジェクトの歴史に部分的にしか気づいていません。それらはファイルを検査し、パターンを推論し、変更を生成できますが、どの決定が意図的であり、どの決定が偶然であり、どの決定がすでに議論されて解決されたかを自動的に知ることはできません。これにより、いくつかの明確なリスクが生じます。
AIは解決済みの議論を再開する可能性があります
チームがすでにモジュラーモノリシックを使用すると決定している場合でも、AIエージェントは独立して見るとクリーンに見えるため、サービスの抽出を提案する可能性があります。ADRがなければ、AIはチームがその経路を検討し、拒否したことを知る堅牢な方法を持たず、その結果、努力の無駄やシステムの一貫性の微妙な回帰が生じます。
AIは局所的に最適化し、全球的に損なう可能性があります
生成されたリファクタリングは、1つのファイルをきれいにする一方で、システム境界に違反する可能性があります。UI変更はコンポーネントの複雑さを減らす一方で、意図されたユーザー体験を弱める可能性があります。プロダクト変更は実装を簡素化する一方で、価格設定やコンプライアンスの前提を壊す可能性があります。意思決定記録は、AIが狭い範囲のシグナルに基づいて行動する前に、より大きな参照枠を提供します。
AIはコードを保持するが、意図を失う可能性があります
モデルはコードベース内の既存のパターンに従うことができますが、パターンは原則と同じではありません。既存のコードは妥協であることがあります。移行期のものであることもあります。ファイル内では見えない外部の制約のために存在することもあります。意思決定記録は、「これがどのように動作するか」と「なぜこのように構築されたか」の違いを説明します。
AIは妥当だが誤った理屈を生成する可能性があります
AIは意思決定記録の下書きを作成できますが、実際の決定と一致しない、自信に満ちた説明を捏造することもできます。これが人間のレビューが不可欠な理由です。AIは記録の下書きを生成できますが、記録がマージされる前に、人間はそれが実際の決定、代替案、結果を正確に記述していることを検証する必要があります。
より広範なメソロジーの一部としての意思決定記録
意思決定記録は単なるドキュメントではありません。それらは、軽量なアーキテクチャガバナンス、ドキュメント・アズ・コード、AI拡張型ナレッジ管理ワークフロー、プロダクトディスカバリー、デザイン理屈、AIガバナンス、およびコードレビューの交差点にある、より広範な作業方法の一部です。このより大きなプロセスを記述するための有用な方法は、Decision-Oriented Development（意思決定指向型開発）です。
ほとんどのAI駆動型プログラミングワークフローは、生成-レビュー-コミットのループに狭く焦点を当てています：
このサイクルは、本格的なシステム作業には薄すぎます。より強力なワークフローは、リポジトリをコードと意図の両方のストアとして扱います。ここでの図は、Markdownの意思決定記録内でもよく機能する軽量なフォーマットであるMermaidを使用しています：
このプロセスは、リポジトリを単なるコードストア以上のものにします。それは実装、意図、および理屈の真の源となり、行われる決定ごとに価値を蓄積する堅牢なアーティファクトになります。
意思決定記録とドキュメント・アズ・コード
意思決定記録は、ドキュメント・アズ・コードの原則に従うときに最も効果的に機能します。これは、それらがコードと同じリポジトリに保存され、プレーンなMarkdownで書かれ、プルリクエストでレビューされ、Gitでバージョン管理され、関連する課題やプルリクエストにリンクされ、人間とAIツール双方で検索可能であるべきであることを意味します。これは、重要な決定をチャット、Wikiページ、スライドデッキ、または会議ノートに保存するよりもはるかに信頼性が高いです。それらのツールは議論にはまだ有用かもしれませんが、承認された決定は常にコードの近くに存在すべきです。
よく整理された意思決定記録のリポジトリ構造は以下のようになるかもしれません：
docs/
decisions/
architecture/
0001-use-postgresql-for-primary-storage.md
0002-keep-billing-inside-the-core-app.md
product/
0001-ai-generated-email-requires-human-review.md
0002-free-tier-project-limit.md
design/
0001-use-inline-validation.md
0002-place-ai-suggestions-in-side-panel.md
小規模なプロジェクトでは、フラットな構造でも同様に機能します。正確なフォルダ構成よりも一貫性が重要です。記録は容易に見つけられ、容易にレビューでき、コードベースに作用する前にAIツールがコンテキストとして読み込みやすいものでなければなりません。Goチームの場合、このdocs/decisions/構造は、Goプロジェクト構造：プラクティス＆パターンで説明されているcmd/、internal/、api/レイアウトの隣に自然に収まります。このパターンは、アーキテクチャ決定やAPIリファレンスのホームとしてdocs/を推奨しています。
実用的な意思決定記録テンプレート
実用的な意思決定記録テンプレートは、実際に使用されるほど短くあるべきです。以下は、オプションだが価値のあるAIガイダンスセクションを含む実用的なMarkdownテンプレートです：
# Decision: Short title
Status: Proposed | Accepted | Superseded | Deprecated
Date: YYYY-MM-DD
Type: Architecture | Product | Design
Owners: Team or names
## Context
Describe the problem, constraints, goals, user needs, technical facts,
and business factors that led to this decision.
## Decision
State the decision clearly.
## Alternatives considered
### Option 1
Pros:
- ...
Cons:
- ...
## Consequences
Describe what becomes easier, what becomes harder, and what risks
or follow-up work this creates.
## AI guidance
When an AI assistant works in this area, it should:
- Preserve ...
- Avoid ...
- Prefer ...
- Ask for review when ...
## Links
- Related issues:
- Related pull requests:
- Related files:
- Supersedes:
- Superseded by:
「AIガイダンス」セクションはオプションですが、AI駆動型プログラミングにおいて極めて価値があります。それは意思決定記録を、同じコードベース領域で作業する将来のエージェントに対する堅牢な指示に変えます。
意思決定記録に何が属するべきか？
すべての選択が記録を値するわけではありません。すべての小さな実装詳細が意思決定記録になれば、プロセスはノイズに崩壊します。選択が意味があり、後で重要になる可能性が高い場合に意思決定記録を作成します。
良い候補は以下の決定です：
- システムの複数の部分に影響を与える
- 製品の約束をエンコードする
- 実際の議論を解決する
- 長期的なトレードオフを導入する
- ビジネス、コンプライアンス、または運用制約に依存する
- 後に再発見するのに費用がかかる
- 将来のAIツールが誤って扱う可能性がある
- 将来の貢献者が気軽に逆転する可能性がある
悪い候補には、小さなリファクタリングの選択、明らかなバグ修正、一時的な実験、ローカルな命名決定、永続的な結果のない実装詳細が含まれます。良い経験則はシンプルです：決定を逆転するのに議論が必要であれば、その決定を記録します。
ステータス値とライフサイクル
意思決定記録は、その現在の位置づけを示すためにライフサイクルを持つべきです。最もシンプルなステータス値で十分です。
Proposed（提案中） — 決定は検討中ですが、まだ承認されていません。チームがコミットする前に、プルリクエストで決定を議論したい場合に使用します。
Accepted（承認済み） — 決定は有効であり、将来の作業をガイドするべきです。最も有用な意思決定記録は、その寿命の大部分をこの状態で過ごすでしょう。
Superseded（代替済み） — 決定は新しい記録に置き換えられました。古い記録を削除しないでください。歴史のために保持し、思考の進化が可視化されるように新しい決定にリンクします。
Deprecated（非推奨） — 決定はもはや推奨されませんが、システムの一部をまだ記述している可能性があります。これは、新しいアプローチと並行して古いパターンがコードベースに存在する移行時に特に有用です。
重要な原則は、意思決定記録は付加的（append-friendly）であるべきだということです。チームが方向性を変更したとき、過去をよりクリーンに見せるために歴史を書き換えるのではなく、新しい記録を作成し、古い記録にリンクします。
AIが意思決定記録を生成する方法
AIは意思決定記録の作成を支援できます。これはソフトウェア開発におけるAIのより良い用途の一つです。それはコンテキストから構造化されたドキュメントを下書きする際に高速です。議論、アーキテクチャレビュー、またはプルリクエストの後、AIアシスタントに記録の下書きを依頼できます：
Draft an Architecture Decision Record for the decision in this pull request.
Include context, alternatives, consequences, and AI guidance.
Save it as Markdown under docs/decisions/architecture.
製品作業の場合：
Draft a Product Decision Record explaining why AI-generated messages
must remain drafts until reviewed by the user.
Include user impact, out-of-scope behavior, tradeoffs, and AI guidance.
しかし、AI生成の記録は自動的に信頼すべきではありません。人間のレビューは、文脈が正確であること、AIが理屈を捏造していないこと、リストされた代替案が実在すること、結果が誠実であること、AIガイダンスがチームの実際の意図と一致していることを検証すべきです。AIは下書きの補助者です。決定の所有者ではありません。
AIが意思決定記録を読む方法
実践のもう半分は、AIに行動する前に記録を読むよう指示することです。AIアシスタントに変更の実装を依頼する前に、このような指示を含めます：
Before modifying this feature, read docs/decisions.
Identify any Architecture, Product, or Design Decision Records that apply.
Follow accepted decisions. If your proposed change conflicts with a decision
record, explain the conflict before changing code.
より大きなタスクの場合、記録をプロジェクトの記憶としての役割を強化します：
Use the decision records as project memory.
Do not reverse accepted decisions without proposing a new superseding decision.
When you generate code, explain which decision records influenced the implementation.
これにより、AIの役割が「妥当なコードを予測する」ことから「文書化された制約システム内で動作する」ものに変更されます。これは、複雑または長寿命なプロジェクトの信頼性において大幅な改善です。
プルリクエストにおける意思決定記録
意思決定記録は、別個のプロセスではなく、通常のプルリクエストレビューの一部であるべきです。シンプルなPRチェックリスト項目が、その習慣を可視化します：
## Decision record checklist
- [ ] This PR does not introduce a significant architecture, product, or design decision.
- [ ] This PR introduces a significant decision and includes a new decision record.
- [ ] This PR changes a previous decision and includes a superseding record.
- [ ] Relevant existing decision records were considered.
- [ ] AI-generated code follows the accepted decision records.
- [ ] AI-generated decision records were reviewed by a human.
このチェックリストはシンプルですが、コードがプルリクエストにおいて重要である唯一のアーティファクトではないことをチームに思い出させることで、行動を変化させます。また、AI生成の変更が静かに以前の決定に違反している場合に、それを自然に捕捉しやすくします。
意思決定記録とアーキテクチャガバナンス
従来のアーキテクチャガバナンスは、重すぎ、遅すぎ、実装から切り離されすぎているためにしばしば失敗します。中央承認ボード、大規模な初期ドキュメント、そしてガイドするのではなくブロックするゲートキーピングプロセスです。意思決定記録は、開発ワークフローに直接統合される、より軽量な代替案を提供します。
それらはすべての変更に対して中央アーキテクチャボードを必要とせず、チームが学習し適応することからもブロックしません。代わりに、それらは時間をかけてレビュー、参照、構築できる決定の痕跡を作成します。これは進化的アーキテクチャをサポートします：アーキテクチャは変更できますが、記憶なしではなく、記憶を持って変更されます。チームは、なぜそれらが行われたかを再発見する必要なく、古い決定を再検討できます。これはより健康的で、より誠実なガバナンスの形態です：
- 巨大なドキュメントの代わりに、小さな記録
- 別個の承認劇の代わりに、コード近くのレビュー
- 部族的知識の代わりに、歴史的文脈
- 隠れた前提の代わりに、明示的なトレードオフ
意思決定記録とプロダクトマネジメント
プロダクト作業もまた決定記憶を必要とし、これは意思決定記録の価値がしばしば過小評価される領域です。ロードマップは何が起きる可能性があるかを示します。チケットは次に何を構築するかを示します。アナリティクスはユーザーが何をしていたかを示します。それらのどれも、製品動作が存在する理由を完全に説明しません。
プロダクト意思決定記録はその隙間を埋め、価格設定およびパッケージングの決定、権限モデル、制限およびクォータ、AI安全性およびレビューフロー、オンボーディング選択、ユーザーロール定義、コラボレーションルール、データ保持ポリシー、および機能範囲の境界において特に有用です。一度実装されると、製品決定はコード内で目に見えなくなります。後になって、誰かがコードしか見えず、「なぜこのように動作するのですか？」と尋ねます。PDRは、人間とAIツール双方が見つけ使用できる形で答えを提供します。
意思決定記録とデザインシステム
デザインシステムはしばしばコンポーネント、トークン、および使用ルールを文書化しますが、なぜそのシステムがそのように動作するかを文書化することは稀です。デザイン意思決定記録はこの隙間を埋めます。コンポーネントライブラリは「破壊的なアクションには確認ダイアログを使用せよ」と言うかもしれませんが、DDRは理屈を説明します：「私たちは破壊的なアクションに対して確認を要求します。なぜなら、ユーザーはしばしば共有チームデータと作業し、誤って削除された場合の復元コストが高いためです。」
その理屈は、特定のコンポーネントを超えて重要です。それは将来のデザイナー、開発者、およびAIツールが、新しい状況で原則を正しく適用するのを助けます。DDRがなければ、AIエージェントはより効率的に見えるため、確認をスキップするより速いインタラクションを生成するかもしれません。DDRがあれば、エージェントは安全性プロパティの保持が意図的かつ非交渉的であることを認識できます。
意思決定記録が仕様駆動型開発を支援する方法
仕様駆動型開発は、システムが何を行うべきかを説明します。意思決定記録は、チームがなぜその方向性を選んだかを説明します。そしてその区別は、AI支援作業において大きく異なります。
機能仕様は、AI生成メールは下書きとして保存されるべきだと述べるかもしれません。プロダクト意思決定記録は、なぜ自動送信が拒否され、どのようなリスクが検討され、どの将来の変更が新しい決定を必要とするかを説明します。デザイン仕様はサイドパネルインタラクションを記述するかもしれませんが、対応するDDRは、なぜインラインAI編集が明示的に拒否され、なぜユーザー制御の保持がワークフロー速度よりも重く考慮されたかを説明します。アーキテクチャ仕様はサービス境界を定義するかもしれませんが、そのADRは、チームがなぜよりシンプルまたはより分散された代替案よりもその境界を選んだかを説明します。
仕様は実装をガイドします。意思決定記録は判断を保持します。両方合わせると、AIコーディングエージェントは指示と文脈の両方、「何」と「なぜ」を与えられます。これが、複雑で長寿命なシステムにおいてこの組み合わせを非常に効果的にする理由です。
意思決定記録は仕様ではありません
意思決定記録は仕様に関連していますが、それらは異なる目的を果たします。仕様は「システムはXを行うべき」と言いますが、意思決定記録は「これらの制約とトレードオフのために、XをYの代わりに選んだ」と言います。その「Yの代わりに」が価値ある部分です。AIツールはしばしば、要求された結果への妥当な経路を見つけて解決策を生成しますが、意思決定記録は、すでに探索、評価、拒否された妥当な経路をそれらに伝えます。これにより、チャーン（不要な変更）を減らし、AI支援作業の品質を向上させます。
意思決定記録はテストの代替ではありません
テストは動作を検証します。意思決定記録は意図を説明します。両方必要であり、それらは一緒に機能します。テストは、AI生成メールが下書きとして保存される必要があることを強制できます。一方、プロダクト意思決定記録は、ユーザーがシステムから通信が離れる前にAI生成通信をレビューする必要があるため、これが必須であることを説明します。テストは動作を保護します。意思決定記録は意味を保護します。両方合わせると、将来の変更はより安全で予測可能になります。
意思決定記録はコードコメントの代替ではありません
コードコメントはローカルな実装詳細を説明し、意思決定記録はより広範な決定を説明します。驚くべき行、エッジケース、ワークアラウンド、および簡素化できない関数にはコメントを使用します。アーキテクチャが存在する理由、製品動作が存在する理由、インタラクションパターンが存在する理由、およびチームが一方の方向性を他方の代わりに選んだ理由には意思決定記録を使用します。説明が数行に影響を与えるだけなら、コメントが正しいツールです。システムの方針に影響するなら、意思決定記録が正しいツールです。
一般的なミステーク
記録を遅すぎに書く
意思決定記録は、決定が行われたときに書かれるべきであり、誰もがトレードオフを忘れてしまった数ヶ月前ではありません。プルリクエスト中に下書きするのは問題ありません。実装前に、決定がまだ積極的に議論され、代替案が生々しい間に下書きするのがさらに良いでしょう。
記録を長すぎにする
意思決定記録はエッセイではありません。それは判断を保持するのに十分に詳細であり、かつ実際に読まれるほど短くあるべきです。完全性よりも明確さを優先します。読み込まれる簡潔な記録は、スキップされる包括的な記録よりもはるかに価値があります。
結果なしで決定を記録する
結果セクションは記録の心臓部です。述べられた結果のない決定は、しばしば真の決定ではなく単なる好みです。良い記録は、選択の結果として何变得更に困難またはリスクが高くなるかを正直に認めます。
歴史が変化したかのように古い記録を編集する
決定が変化したとき、新しい記録を作成し、古い記録を代替済みとしてマークします。現在の状態に合わせるために古い決定を静かに書き換えることは、意思決定記録を価値あるものにする歴史的文脈を破壊します。歴史は、思考がどのように進化してきたかを示すために、まさに有用です。
AI生成の記録をレビューなしでマージさせる
AIは、微妙に誤っているが、磨かれた、よく構造化された記録を生成できます。AI生成の意思決定記録を、AI生成のコードと同様に扱ってください。注意深くレビューし、理屈が正確であることを検証し、結果セクションがチームが実際に受容したものを反映していることを確認します。
記録をリポジトリ外に隠す
意思決定記録が別個のWikiまたはドキュメントシステムに存在する場合、それらはコード変更と一緒に更新されにくく、タスクのコンテキストを読み込むAIコーディングツールによって読まれる可能性もさらに低くなります。それらをリポジトリ内に保持することは単なる便宜ではなく、AI支援開発においてこの実践を機能させるための必要条件です。
軽量な運用モデル
最小限のオーバーヘッドを追加する実用的なチームプロセスは以下のようになります：
- プランニングまたは実装中に、意味のある決定が行われているかどうかを特定します。
- 議論に基づいて、AIアシスタントにADR、PDR、またはDDRの下書きを依頼します。
- チームとして下書きをレビューし、文脈、代替案、結果を検証します。
- 記録をMarkdownとしてリポジトリにコミットします。
- 関連する課題またはプルリクエストからそれへのリンクを貼ります。
- その領域で将来の変更を行う前に、AIコーディングツールに関連する記録を読むよう指示します。
- 決定が変化したときに記録を代替し、歴史のために古い記録を保持します。
これには、新しい官僚主義や専用のドキュメンテーションロールは必要ありません。必要なのは小さな習慣です：必要とされるコードの近くに、作成された瞬間に重要な判断を保持することです。
ADRの例
# Decision: Use PostgreSQL for primary application storage
Status: Accepted
Date: 2026-06-25
Type: Architecture
Owners: Platform team
## Context
The application needs durable relational storage for accounts, projects,
permissions, and audit events. The team expects frequent reporting queries
and strong consistency requirements for permission checks.
## Decision
We will use PostgreSQL as the primary application database.
## Alternatives considered
### DynamoDB
Pros:
- Operationally scalable
- Good fit for predictable key-value access patterns
Cons:
- More complex for relational queries
- Harder for ad hoc reporting
- Less familiar to the current team
### MySQL
Pros:
- Mature relational database
- Familiar operational model
Cons:
- PostgreSQL better matches the team's needs for JSON support,
indexing options, and existing expertise
## Consequences
PostgreSQL becomes a core operational dependency. The team must manage
migrations carefully and monitor query performance. In return, the
application gets strong relational modeling, mature indexing, and
flexible reporting support.
## AI guidance
When modifying persistence code, prefer relational modeling in PostgreSQL.
Do not introduce a second primary database without a superseding ADR.
PDRの例
# Decision: AI-generated emails must remain drafts
Status: Accepted
Date: 2026-06-25
Type: Product
Owners: Product team
## Context
The product can generate email replies using AI. Sending email is a
high-trust action because mistakes may reach customers, partners, or
internal teams.
## Decision
AI-generated emails must be created as drafts. A human user must
review and send them.
## Alternatives considered
### Send automatically
Pros:
- Faster workflow
- Less user effort
Cons:
- Higher risk of incorrect or inappropriate messages
- Lower user trust
- Harder to recover from mistakes
### Ask for confirmation only after generation
Pros:
- Keeps the workflow simple
- Provides some user control
Cons:
- Still encourages shallow review
- Does not fit existing email client behavior as well as drafts
## Consequences
The workflow is slightly slower, but safer and more trustworthy.
Future automation can improve review speed, but must not bypass
human approval without a superseding PDR.
## AI guidance
When building email-generation features, create drafts by default.
Do not add automatic sending unless a new accepted PDR explicitly allows it.
DDRの例
# Decision: Show AI writing suggestions in a side panel
Status: Accepted
Date: 2026-06-25
Type: Design
Owners: Design team
## Context
Users need help improving written content, but they also need to stay
in control of the final text. Inline AI edits can make it hard to
distinguish user-written content from generated suggestions.
## Decision
AI writing suggestions will appear in a side panel. Users can accept,
reject, or copy suggestions into the main editor.
## Alternatives considered
### Apply suggestions inline
Pros:
- Fast
- Feels integrated
Cons:
- Blurs authorship
- Makes review harder
- Can surprise users
### Show suggestions in a modal
Pros:
- Focused experience
- Easy to implement
Cons:
- Interrupts writing flow
- Harder to compare suggestion and original text
## Consequences
The side panel takes more screen space, especially on small screens.
However, it preserves user control and makes review clearer.
## AI guidance
When adding writing-assistance features, preserve separation between
user text and AI suggestions. Do not apply generated text directly
into the document without explicit user action.
推奨プロンプトライブラリ
これらのプロンプトを使用して、意思決定記録を毎日のAI支援開発の一部にしてください。
機能に取り組む前に関連する記録を見つける：
Read docs/decisions and identify any accepted decision records that apply
to this task. Summarize the constraints before proposing code changes.
新しいADRの下書き：
Draft an Architecture Decision Record for this technical decision.
Include context, decision, alternatives, consequences, and AI guidance.
Keep it concise and specific.
新しいPDRの下書き：
Draft a Product Decision Record for this product behavior.
Include user impact, scope, alternatives, consequences, and AI guidance.
新しいDDRの下書き：
Draft a Design Decision Record for this interaction pattern.
Include user problem, alternatives, tradeoffs, consequences, and AI guidance.
既存の決定に対してプルリクエストをレビュー：
Review this pull request against the accepted decision records in docs/decisions.
Identify any conflicts, missing decision records, or decisions that should
be superseded.
決定を代替する：
Create a new decision record that supersedes the existing one.
Preserve the historical rationale, explain what changed, and link both records.
関連読書
- Michael NygardのオリジナルADRフォーマット — ADRムーブメントを開始した基礎的な投稿
- ADR GitHub組織 — 意思決定記録を管理するためのツール、テンプレート、およびコミュニティリソース
- 仕様駆動型開発とは何か？ 真の源としての仕様 — 機能仕様がどのように意思決定記録を補完するかを説明するSDDの標準的な定義：両方ともシステムの異なるレベルで意図を堅牢にする
- 仕様駆動型開発 vs Vibeコーディング：ウォーターフォールか？ — SDDを使用する時期と、より速く緩やかなワークフローで留まる時期
- 本番環境でのアプリアーキテクチャ：統合パターン、コードデザイン、データアクセス — 統合、テスト、データアクセス、およびソフトウェアドキュメントパターンをカバーするクラスターのホーム
- ナレッジ管理のためのAI：堅実なワークフロー — 意思決定記録の実践を補完する実用的なAI拡張型ナレッジワークフロー
