ソフトウェア開発における「意思決定記録」とは何か？

意思決定記録（Decision Record）は、開発の過程で行われた重要な意思決定を、背景、検討された代替案、および受け入れられた結果を含めて簡潔に記述したMarkdown文書です。意思決定記録は、アーキテクチャ、プロダクト、およびデザインに関する決定の根拠をチームで保持するのに役立ち、将来の貢献者やAIツールが、コードが「何をしているか」だけでなく「なぜそのように構築されたか」を理解できるよう支援します。

ADR、PDR、およびDDRの違いは何ですか？

ADR（アーキテクチャ決定記録）は、データベースの選択やサービス境界といった技術的・構造的な決定を記録します。PDR（プロダクト決定記録）は、セーフティフローや機能の制限といったプロダクトの振る舞いや範囲に関する決定を文書化します。DDR（デザイン決定記録）は、コンポーネントの配置やラベルの命名規則といったユーザー体験やインタラクションに関する決定を記録します。これら3つは同じフォーマットに従いますが、ソフトウェアプロジェクトにおける異なるレイヤーの決定を文書化します。

なぜ意思決定記録はAI支援開発にとって重要なのか

AIコーディングエージェントはコードを読み取れますが、意思決定の背景にある理由を正確に推測することはできません。意思決定記録が存在しない場合、AIツールはすでに結論を出した議論を再燃させたり、ローカル最適化を図るためにシステムレベルの制約を破ったり、背後にある原則を理解せずにコードパターンを維持したりする可能性があります。意思決定記録は、AIツールが動作する前に、プロジェクトの意図に関する査読済みかつバージョン管理された情報源を提供します。

意思決定記録はどのよう保管すべきでしょうか？

意思決定の記録は、プロジェクトリポジトリ内でMarkdownファイルとして保存し、Gitでバージョン管理を行うべきです。また、コードと同様にプルリクエストを通じてレビューされるべきです。リポジトリ内に保持することで、チームメンバーとAIコーディングツールが共にアクセス可能になります。一方、別のWikiやチャットツールに保存すると、発見しにくくなり、情報が最新の状態を保つ可能性も低下します。

「意思決定記録」をいつ作成すべきか

システムの複数の部分に影響を与える場合、実質的な議論を解決する場合、長期的なトレードオフを導入する場合、あるいは後から再検討する際に高コストがかかる可能性がある場合は、意思決定記録を作成してください。実用的な目安として、その決定を撤回するためにチーム内で議論を要するものであれば、記録に残す価値があります。

AIは意思決定記録を自動生成できるか？

AIは意思決定記録を迅速に起草でき、これはソフトウェア開発におけるAIの最も生産的な用途の一つです。ただし、AIは実際の意思決定の文脈、代替案、または結果を正確に反映していない、しかし説得力のある根拠を生成する可能性があるため、生成された記録はマージ前に人間によるレビューが必要です。

AI駆動型ソフトウェア開発における意思決定記録

意図をコードの近くに保つ。

意思決定記録は、AI支援ソフトウェア開発における欠けていたメモリ層です。これらは何が開発されたかだけでなく、なぜそうされたかを捉えます。AIツールがコードを書き始める際、この区別は極めて重要になります。

意思決定記録 — ADR, PDR, DDR — 意図とコードを結ぶ

意思決定記録は欠けていたメモリ層です

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ガバナンス、コードレビューの交点にある、より広範な働き方の一部です。より大きなプロセスを記述する有用な方法は、「意思決定指向型開発」です。

ほとんどのAI駆動型プログラミングワークフローは、生成-レビュー-コミットのループに狭く焦点を当てています。

flowchart LR A[プロンプト] --> B[コードの生成] B --> C[テスト] C --> D[コミット]

このサイクルは、本格的なシステム作業には薄すぎます。より強力なワークフローは、リポジトリをコードと意図の両方のストアとして扱います。ここで使用している図は、Markdownの意思決定記録内でも良く機能する軽量なフォーマットであるMermaidを使用しています。

flowchart TB subgraph top[" "] direction LR A[問題の定義] --> B[既存の決定の特定] --> C[オプションとトレードオフの探索] --> D[選択された決定の記録] end subgraph bottom[" "] direction LR E[コードの生成または修正] --> F[決定に対するコードのレビュー] --> G[実装とメモリの統合] --> H[記録を使用して将来の作業をガイドする] end D --> E

このプロセスは、リポジトリをコードストア以上のものに変えます。それは実装、意図、理屈の真の源となり、行われる決定ごとに価値を蓄積する耐久性のあるアーティファクトとなります。

意思決定記録とドキュメントをコードとして扱う手法

意思決定記録は、ドキュメントをコードとして扱う原則に従う場合に最も効果的です。つまり、コードと同じリポジトリに保管され、プレーンなMarkdownで記述され、プルリクエストでレビューされ、Gitでバージョン管理され、関連するイシューやプルリクエストとリンクされ、人間とAIツールの両方で検索可能であるべきです。これは、重要な決定をチャット、Wikiページ、スライドデッキ、または会議メモに保管するよりもはるかに信頼性が高いです。それらのツールは議論にはまだ有用かもしれませんが、承認された決定は常にコードの近くに存在すべきです。AI開発における仕様、テスト、コードの同期維持は、この「記録へのリンク」の習慣を、要件とデザイン決定IDをテストやプルリクエストに紐付ける完全なトレーサビリティモデルに拡張しています。

よく整理された意思決定記録のリポジトリ構造は以下のようになるかもしれません。

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/レイアウトの横に自然に配置されます。これはdocs/をアーキテクチャ決定とAPI参照のホームとして推奨しています。

実用的な意思決定記録テンプレート

実用的な意思決定記録テンプレートは、人々が実際に使用するほど短くあるべきです。以下に、オプションながら価値のあるAIガイドセクションを含む実用的なMarkdownテンプレートを示します。

# 決定：短いタイトル

ステータス：提案中 | 承認済み | 廃止 | 非推奨
日付：YYYY-MM-DD
タイプ：アーキテクチャ | プロダクト | デザイン
所有者：チームまたは名前

## 文脈

この決定に至った問題、制約、目標、ユーザーニーズ、技術的事実、
およびビジネス要因を記述します。

## 決定

決定を明確に述べてください。

## 検討された代替案

### オプション1

メリット：
- ...

デメリット：
- ...

## 結果

何が容易になり、何が困難になり、どのようなリスク
またはフォローアップ作業が生じるかを記述します。

## AIガイド

AIアシスタントがこの領域で作業する際には、以下を行うべきです：
- ...を保持する
- ...を避ける
- ...を優先する
- ...場合にレビューを求める

## リンク

- 関連イシュー：
- 関連プルリクエスト：
- 関連ファイル：
- 廃止する対象：
- 廃止された対象：

「AIガイド」セクションはオプションですが、AI駆動型プログラミングにおいては極めて価値があります。それは意思決定記録を、同じコードベースの領域で作業する将来のエージェントに対する耐久性のある指示に変えます。

意思決定記録に含まれるべきもの

すべての選択が記録を必要とするわけではありません。すべての小さな実装詳細が意思決定記録になる場合、そのプロセスはノイズに崩壊します。選択が意味を持ち、後で重要になる可能性が高い場合に意思決定記録を作成します。

良い候補となる決定は以下の通りです。

システムの複数の部分に影響を与える
プロダクトの約束をエンコードする
実際の議論を解決する
長期的なトレードオフを導入する
ビジネス、コンプライアンス、または運用制約に依存する
後で再発見するのに費用がかかる
将来のAIツールが誤って解釈する可能性がある
将来の貢献者が安易に逆転させそうになる

悪い候補には、小さなリファクタリングの選択、明らかなバグ修正、一時的な実験、ローカルな命名決定、持続的な結果のない実装詳細が含まれます。良い経験則は単純です。決定を逆転させるために議論が必要であれば、その決定を記録します。

ステータス値とライフサイクル

意思決定記録は、その現在の立ち位置を示すためにライフサイクルを持つべきです。最もシンプルなステータス値で十分です。

提案中 — 決定は検討中ですが、まだ承認されていません。チームがコミットする前にプルリクエストで決定を議論したい場合に使用します。

承認済み — 決定は有効であり、将来の作業をガイドすべきです。最も有用な意思決定記録の多くは、その寿命の大部分をこの状態に費やすでしょう。

廃止 — 決定は新しい記録によって置き換えられました。古い記録を削除しないでください。履歴として保持し、新しい決定にリンクして、思考の進化が目に見えるようにします。

非推奨 — 決定はもはや推奨されませんが、システムの既存の部分を記述している場合があります。これは、コードベース内に古いパターンが存在し、新しいアプローチと共存している移行期間中に特に有用です。

重要な原則は、意思決定記録は追記フレンドリーであるべきです。チームが方向性を変更する場合、過去をよりクリーンに見せるために履歴を書き直すのではなく、新しい記録を作成し、古い記録にリンクします。

AIが意思決定記録を生成する方法

AIは意思決定記録の作成を支援できます。これはソフトウェア開発におけるAIのより良い使用法の1つです。それは文脈から構造化されたドキュメントをドラフトするのが速いからです。議論、アーキテクチャレビュー、またはプルリクエストの後、AIアシスタントに記録のドラフトを依頼できます。

このプルリクエストの決定に関するアーキテクチャ決定記録をドラフトしてください。
文脈、代替案、結果、およびAIガイドを含めてください。
docs/decisions/architectureの下にMarkdownとして保存してください。

プロダクト作業の場合：

AI生成メッセージがユーザーによってレビューされるまで下書きのままにする必要がある理由を
説明するプロダクト決定記録をドラフトしてください。
ユーザーへの影響、スコープ外の振る舞い、トレードオフ、およびAIガイドを含めてください。

ただし、AI生成された記録を自動的に信頼してはいけません。人間のレビューは、文脈が正確であり、AIが理屈を創作しておらず、リストされた代替案が実在しており、結果が誠実であり、AIガイドがチームの実際の意図と一致していることを検証すべきです。AIはドラフトの補助者であり、決定の所有者ではありません。

AIが意思決定記録を読む方法

実践のもう半分は、AIに行動する前に記録を読むよう指示することです。AIアシスタントに変更の実装を依頼する前に、以下の指示を含めます。

この機能を変更する前に、docs/decisionsを読んでください。
適用されるアーキテクチャ、プロダクト、またはデザイン決定記録を特定してください。
承認された決定に従ってください。提案された変更が決定記録と
衝突する場合は、コードを変更する前にその衝突を説明してください。

より大きなタスクの場合、記録をプロジェクトメモリとしての役割を強化します。

意思決定記録をプロジェクトメモリとして使用してください。
新しい廃止記録を提案せずに、承認された決定を逆転しないでください。
コードを生成する際、どの意思決定記録が実装に影響を与えたかを説明してください。

これにより、AIの役割は「妥当なコードを予測する」ことから「文書化された制約システム内で動作する」ものへと変化します。これは、複雑または長寿命なプロジェクトの信頼性において、重要な改善です。

プルリクエストにおける意思決定記録

意思決定記録は、別々のプロセスではなく、通常のプルリクエストレビューの一部であるべきです。シンプルなPRチェックリストのエントリが、その習慣を目に見えるものにします。

## 意思決定記録チェックリスト

- [ ] このPRは、重要なアーキテクチャ、プロダクト、またはデザイン決定を導入しません。
- [ ] このPRは重要な決定を導入し、新しい意思決定記録を含んでいます。
- [ ] このPRは以前の決定を変更し、廃止する記録を含んでいます。
- [ ] 関連する既存の意思決定記録が検討されました。
- [ ] AI生成コードは、承認された意思決定記録に従っています。
- [ ] AI生成された意思決定記録は人間によってレビューされました。

このチェックリストはシンプルですが、コードがプルリクエストで重要であるアーティファクトの唯一のものではないことをチームに思い出させることで、行動を変化させます。また、AI生成された変更が以前の決定を静かに違反している場合を自然に発見しやすくします。

意思決定記録とアーキテクチャガバナンス

伝統的なアーキテクチャガバナンスは、しばしば重すぎ、遅すぎ、または実装から切り離れすぎているために失敗します。中央承認委員会、大規模な前もってのドキュメント、ガイドするのではなくブロックするゲートキーピングプロセスです。意思決定記録は、開発ワークフローに直接統合されるより軽量な代替策を提供します。

それらはすべての変更に対して中央アーキテクチャ委員会を必要とせず、チームが学習し適応することをブロックしません。代わりに、時間とともにレビュー、参照、構築されることのできる決定の痕跡を作成します。これは進化的アーキテクチャをサポートします。アーキテクチャは変化できますが、それに反してではなく、メモリを持って変化します。チームは、なぜそれらが行われたかを再発見する必要なく古い決定を再検討でき、それはより健康的で誠実なガバナンスの形態です。

巨大なドキュメントではなく小さな記録
別の承認の劇場ではなく、コード近くのレビュー
部族知識ではなく歴史的な文脈
隠れた前提ではなく明確なトレードオフ

意思決定記録とプロダクトマネジメント

プロダクト作業もまた意思決定メモリを必要とし、これは意思決定記録の価値がしばしば過小評価される領域です。ロードマップは何が起きる可能性があるかを示します。チケットは次に何を構築するかを示します。アナリティクスはユーザーが何をしたかを示します。それらのどれかが、プロダクトの振る舞いが存在する理由を完全に説明するわけではありません。

プロダクト決定記録はその隙間を埋め、価格設定とパッケージングの決定、権限モデル、制限とクォータ、AI安全性とレビューフロー、オンボーディングの選択、ユーザーロールの定義、コラボレーションルール、データ保持ポリシー、および機能範囲の境界において特に有用です。一度実装されると、プロダクト決定はコード内で目に見えなくなります。後で、誰かがコードのみを見て「なぜこのように機能するのか？」と尋ねます。PDRは、人間とAIツールの両方が見つけ使用できる形で答えを提供します。

意思決定記録とデザインシステム

デザインシステムはしばしばコンポーネント、トークン、使用ルールを文書化しますが、なぜそのように機能するかを文書化することは稀です。デザイン決定記録はその隙間を埋めます。コンポーネントライブラリは「破壊的なアクションには確認ダイアログを使用する」と言うかもしれませんが、DDRはその理屈を説明します。「破壊的なアクションには確認が必要なのは、ユーザーはしばしば共有チームデータと作業し、誤って削除すると復元コストが高いからです」。

その理屈は特定のコンポーネントを超えて重要です。それは将来のデザイナー、開発者、AIツールが原則を正しく新しい状況に適用するのを助けます。DDRがなければ、AIエージェントは確認をスキップするより速いインタラクションを生成するかもしれません。それはより効率的に見えるためです。DDRがあれば、エージェントは安全性プロパティの保持が意図的で妥協できないものであることを認識できます。

意思決定記録が仕様駆動型開発を支援する方法

仕様駆動型開発は、システムが何をすべきかを説明します。意思決定記録は、チームがその方向性を選んだ理由を説明します。この区別は、AI支援作業において著しく重要です。

機能仕様は、AI生成メールが下書きとして保存されるべきであると述べるかもしれません。プロダクト決定記録は、自動送信がなぜ却下され、どのようなリスクが検討され、どのような将来の変更が新しい決定を必要とするかを説明します。デザイン仕様はサイドパネルインタラクションを記述するかもしれませんが、対応するDDRは、インラインAI編集が明示的に却下された理由と、ワークフローの速度よりもユーザー制御の保持がより重く考慮された理由を説明します。アーキテクチャ仕様はサービス境界を定義し、そのADRはチームがよりシンプルまたはより分散された代替案よりもその境界を選んだ理由を説明します。

仕様は実装をガイドします。意思決定記録は判断を保持します。それらは一緒に、AIコーディングエージェントに指示と文脈の両方、「何」と「なぜ」を与えます。これが、複雑で長寿命なシステムにおいてこの組み合わせを非常に効果的にする理由です。仕様駆動型ツールチェーンを採用する場合、各オプションがその文脈をどのように表面化するかを比較してください。GitHub Spec Kit vs Kiro vs Claude Code SDD Workflowsは、主要なセットアップ間のポータビリティ、レビューゲート、リポジトリグラウンディングを分解します。それらのツールが実装するツール中立の5フェーズプロセスについては、要件からコードへの仕様駆動型開発ワークフローを参照してください。

意思決定記録は仕様ではありません

意思決定記録は仕様に関連していますが、異なる目的を兼ねています。仕様は「システムはXを行うべき」と述べ、意思決定記録は「これらの制約とトレードオフのために、YではなくXを選んだ」と述べます。「Yではなく」という部分が価値のある部分です。AIツールは、要求された結果への妥当な経路を見つけることでソリューションを生成することがよくありますが、意思決定記録は、すでに探索、評価、却下された妥当な経路を伝えます。これにより、変更頻度が減少し、AI支援作業の品質が向上します。

意思決定記録はテストの代替ではありません

テストは振る舞いを検証し、意思決定記録は意図を説明します。両方が必要であり、それらは一緒に機能します。テストはAI生成メールが下書きとして保存されるべきであることを強制できますが、プロダクト決定記録は、ユーザーがシステム外に出る前にAI生成コミュニケーションをレビューする必要があるため、これが要求されていることを説明します。テストは振る舞いを保護します。意思決定記録は意味を保護します。一緒に、それらは将来の変更をより安全で予測可能にします。

意思決定記録はコードコメントの代替ではありません

コードコメントはローカルな実装詳細を説明し、意思決定記録はより広範な決定を説明します。驚くべき行、エッジケース、ワークアラウンド、簡素化できない関数にはコメントを使用します。アーキテクチャが存在する理由、プロダクト振る舞いが存在する理由、インタラクションパターンが存在する理由、チームが1つの方向を他方よりも選んだ理由には意思決定記録を使用します。説明が数行のみに関わる場合、コメントが正しいツールです。それがシステムの方向性に影響する場合、意思決定記録が正しいツールです。

一般的なミス

記録を遅く書く

意思決定記録は、決定が行われた際に書かれるべきであり、誰もがトレードオフを忘れてしまった数ヶ月後ではありません。プルリクエスト中にドラフトを書くのは問題ありません。実装前、決定がまだ積極的に議論されており、代替案が新鮮なうちにドラフトするのはさらに良いでしょう。

記録を長すぎるものにする

意思決定記録は論説ではありません。それは判断を保持するのに十分な詳細さを持ちつつ、人々が実際に読むのに十分な短さを持つべきです。完全性よりも明確さを優先します。読まれる簡潔な記録は、スキップされる包括的な記録よりもはるかに価値があります。

結果なしで決定を記録する

結果セクションは記録の心臓部です。記述された結果のない決定は、しばしば実際の決定ではなく単なる好みです。良い記録は、選択の結果として何が可能になり、何が困難またはリスクが高くなるかを誠実に認めます。

歴史が変わったかのように古い記録を編集する

決定が変わった場合、新しい記録を作成し、古い記録を廃止とマークします。現在の状態に合わせて古い決定を静かに書き直すことは、意思決定記録を価値あるものにする歴史的な文脈を破壊します。歴史は、思考がどのように進化했のかを示すために有用です。コンパイルされたナレッジベースは、異なる名前の下で同一の問題に直面しています。LLM Wiki Maintenance: Drift, Contradictions and Reviewはこれを決定ドリフトと呼び、Wikiページに同じ「上書きではなく廃止」ルールを適用します。

人間によるレビューなしでAI生成記録をマージさせる

AIは、微細に誤っているが磨かれ、構造化された記録を生成できます。AI生成された意思決定記録を、AI生成されたコードと同様に扱ってください。注意深くレビューし、理屈が正確であることを検証し、結果セクションがチームが実際に受け入れたものを反映していることを確認します。

リポジトリ外に記録を隠す

意思決定記録が別のWikiまたはドキュメントシステムに存在する場合、コード変更と並行して更新される可能性が低くなり、タスクのコンテキストを読み込むAIコーディングツールによって読まれる可能性もはるかに低くなります。リポジトリ内に保持することは単なる便利さではなく、AI支援開発においてこの実践を機能させるものです。

軽量な運用モデル

最小限のオーバーヘッドを追加する実用的なチームプロセスは以下のようになります。

プランニングまたは実装中、意味のある決定が行われているかどうかを特定します。
議論に基づいて、AIアシスタントにADR、PDR、またはDDRのドラフトを依頼します。
チームとしてドラフトをレビューし、文脈、代替案、結果を検証します。
記録をリポジトリ内のMarkdownとしてコミットします。
関連するイシューまたはプルリクエストからリンクします。
AIコーディングツールに、その領域で将来の変更を行う前に関連する記録を読むよう指示します。
決定が変わった場合に記録を廃止し、古い記録を履歴として保持します。

これは、新しい官僚主義や専用のドキュメントロールを必要としません。それは小さな習慣を必要とします。それが必要とされるコードの近くに、作成された瞬間に重要な判断を保持することです。

ADRの例

# 決定：主要アプリケーションストレージにPostgreSQLを使用する

ステータス：承認済み
日付：2026-06-25
タイプ：アーキテクチャ
所有者：プラットフォームチーム

## 文脈

アプリケーションは、アカウント、プロジェクト、権限、監査イベントのための
耐久性のある関係型ストレージを必要としています。チームは頻繁なレポートクエリと、
権限チェックのための強い一貫性要件を想定しています。

## 決定

主要アプリケーションデータベースとしてPostgreSQLを使用します。

## 検討された代替案

### DynamoDB

メリット：
- 運用上のスケーラビリティ
- 予測可能なキーバリューアクセスパターンに適合

デメリット：
- 関係型クエリには複雑
- アドホックなレポートには困難
- 現在のチームにとってなじみが薄い

### MySQL

メリット：
- 成熟した関係型データベース
- なじみのある運用モデル

デメリット：
- JSONサポート、インデックスオプション、既存の専門知識において、
  PostgreSQLがチームのニーズにより適合

## 結果

PostgreSQLはコアな運用依存関係となります。チームはマイグレーションを慎重に管理し、
クエリパフォーマンスを監視する必要があります。その見返りとして、
アプリケーションは強い関係型モデリング、成熟したインデックス、
柔軟なレポートサポートを得ます。

## AIガイド

永続化コードを修正する際、PostgreSQL内の関係型モデリングを優先してください。
廃止するADRなしに、2番目の主要データベースを導入しないでください。

PDRの例

# 決定：AI生成メールは下書きのままにする必要がある

ステータス：承認済み
日付：2026-06-25
タイプ：プロダクト
所有者：プロダクトチーム

## 文脈

プロダクトはAIを使用してメール返信を生成できます。メール送信は、
ミスが顧客、パートナー、または内部チームに届く可能性があるため、
高信頼アクションです。

## 決定

AI生成メールは下書きとして作成されるべきです。人間ユーザーが
レビューし、送信する必要があります。

## 検討された代替案

### 自動的に送信する

メリット：
- より速いワークフロー
- ユーザーの努力が少ない

デメリット：
- 誤ったまたは不適切なメッセージのリスクが高い
- ユーザー信頼が低い
- ミスからの復元が困難

### 生成後にのみ確認を求める

メリット：
- ワークフローをシンプルに保つ
- ある程度のユーザー制御を提供

デメリット：
- 依然として浅いレビューを促進する
- 下書きほど既存のメールクライアントの振る舞いに適合しない

## 結果

ワークフローはわずかに遅くなりますが、より安全で信頼性があります。
将来の自動化はレビュー速度を改善できますが、廃止するPDRなしに
人間の承認をバイパスしてはいけません。

## AIガイド

メール生成機能を構築する際、デフォルトで下書きを作成してください。
新しい承認済みPDRが明示的に許可しない限り、自動送信を追加しないでください。

DDRの例

# 決定：AIの書き込み提案をサイドパネルに表示する

ステータス：承認済み
日付：2026-06-25
タイプ：デザイン
所有者：デザインチーム

## 文脈

ユーザーは書かれたコンテンツの改善を支援する必要がありますが、最終的なテキストの
制御を維持する必要があることも事実です。インラインAI編集は、ユーザーが書いたコンテンツと
生成された提案を区別しにくくする可能性があります。

## 決定

AI書き込み提案はサイドパネルに表示されます。ユーザーは提案を受け入れ、
拒否、またはメインエディターにコピーできます。

## 検討された代替案

### インラインで提案を適用する

メリット：
- 速い
- 統合された感觉

デメリット：
- 作者性を曖昧にする
- レビューを困難にする
- ユーザーを驚かせる可能性がある

### モーダルで提案を表示する

メリット：
- 集中した体験
- 実装が容易

デメリット：
- 書き込みフローを中断する
- 提案と元のテキストの比較が困難

## 結果

サイドパネルは、特に小さな画面ではより多くの画面領域を占めます。
しかし、それはユーザー制御を保持し、レビューを明確にします。

## AIガイド

書き込み支援機能を追加する際、ユーザーテキストとAI提案の間の分離を保持してください。
明示的なユーザーアクションなしに、生成されたテキストを直接ドキュメントに
適用しないでください。

推奨プロンプトライブラリ

これらのプロンプトを使用して、意思決定記録を日々のAI支援開発の一部にしてください。

機能に取り組む前に関連する記録を探す：

docs/decisionsを読んで、このタスクに適用される承認済み意思決定記録を特定してください。
コード変更を提案する前に、制約を要約してください。

新しいADRをドラフトする：

この技術的決定のためのアーキテクチャ決定記録をドラフトしてください。
文脈、決定、代替案、結果、およびAIガイドを含めてください。
簡潔で具体的であるようにしてください。

新しいPDRをドラフトする：

このプロダクト振る舞いのためのプロダクト決定記録をドラフトしてください。
ユーザーへの影響、範囲、代替案、結果、およびAIガイドを含めてください。

新しいDDRをドラフトする：

このインタラクションパターンのためのデザイン決定記録をドラフトしてください。
ユーザー問題、代替案、トレードオフ、結果、およびAIガイドを含めてください。

既存の決定に対してプルリクエストをレビューする：

docs/decisions内の承認済み意思決定記録に対してこのプルリクエストをレビューしてください。
衝突、欠落している意思決定記録、または廃止すべき決定を特定してください。

決定を廃止する：

既存のものを廃止する新しい意思決定記録を作成してください。
歴史的な理屈を保持し、何が変わったかを説明し、両方の記録をリンクしてください。