AI駆動型ソフトウェア開発のための意思決定記録

意図をコードに近づけよう。

目次

意思決定記録は、AI支援ソフトウェア開発における欠けている記憶レイヤーです。何を構築したかだけでなく、なぜそうしたかを取締ります — この区別は、AIツールがコードを書いている場合に極めて重要になります。

意思決定記録 — ADR、PDR、DDR — 意図とコードの接続

意思決定記録は欠けている記憶レイヤーです

AI駆動プログラミング は、コードを生成しやすく、リファクタリングしやすく、手放すのが速くなるようにすることで、ソフトウェア開発の経済性を根本から変えます。これは有用です。しかし同時に危険でもあります。なぜなら、コードが生成しやすくなると、希少資源はもはやタイピングではなく、判断力だからです。

なぜチームはDynamoDBではなくPostgreSQLを選んだのか？ なぜこの製品は、AI生成メールの送信前に人間のレビューを必須としているのか？ なぜインターフェースは提案をサイドパネルに表示し、直接適用しないのか？ なぜ6か月前に単純なアプローチが拒否されたのか？ コードは存在するものを示すかもしれませんが、それがなぜ存在するのかを説明することはめったにありません。

意思決定記録は、重要な選択、その背景にある文脈、検討された代替案、およびチームが受容した結果を、短くバージョン管理されたドキュメントとして取り込むことで、この問題を解決します。AI支援コードベースにおいて、これらの記録は単なるドキュメントを超え、将来の変更を行う前に人間とAIコーディングエージェントの両方が読み取れる、永続的なプロジェクト記憶になります。実践的な運用ルールはシンプルです：意思決定記録をリポジトリ内にMarkdownファイルとして保持し、コードと同じようにレビューし、AIツールに変更を提案または実装する前にそれらを読み込ませます。

意思決定記録とは何か

意思決定記録とは、意味のある決定の書面化された記録であり、4つの基本的な質問に答えるよう構成されています：私たちは何を決定したか、なぜそれを決定したのか、どのような代替案を検討したのか、そしてどのような結果を受容したのかです。最も一般的な形態はアーキテクチャ意思決定記録（Architecture Decision Record, ADR）であり、略してADRと呼ばれます。ADRは技術的な決定を文書化するために広く使用されており、同じパターンはアーキテクチャを超えて、製品やデザイン業務にも拡張できます。

AI駆動プログラミングにおいて、特に有用なのは以下の3つのタイプです：

記録タイプ 取り込む内容 例
ADR アーキテクチャおよび技術的な決定 主要データベースとしてPostgreSQLを使用する
PDR 製品の動作およびスコープの決定 AI生成メールは下書きのままにする
DDR デザインおよびインタラクションの決定 AI提案をサイドパネルに表示する

together、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駆動プログラミングワークフローは、生成-レビュー-コミットループに狭く焦点を当てています：

flowchart LR A[Prompt] --> B[Generate code] B --> C[Test] C --> D[Commit]

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

flowchart TB subgraph top[" "] direction LR A[Frame the problem] --> B[Identify existing decisions] --> C[Explore options and tradeoffs] --> D[Record the selected decision] end subgraph bottom[" "] direction LR E[Generate or modify code] --> F[Review code vs decisions] --> G[Merge implementation and memory] --> H[Use record to guide future work] end D --> E

このプロセスは、リポジトリを単なるコードストア以上のものでします。実装、意図、および推論の真のソースとなり、決定が行われるたびに価値が蓄積される永続的な成果物になります。

意思決定記録とドキュメントとしてのコード

意思決定記録は、ドキュメントとしてのコード（Docs-as-code）の原則に従う場合に最もよく機能します。つまり、コードと同じリポジトリに保存され、プレーンなMarkdownで書かれ、プルリクエストでレビューされ、Gitでバージョン管理され、関連する問題とプルリクエストにリンクされ、人間とAIツールの両方で検索可能であるべきです。これは、重要な決定をチャット、ウィキページ、スライドデッキ、または会議メモに保存するよりはるかに信頼性があります — それらのツールは議論にはまだ有用かもしれませんが、承認された決定は常にコードに近接して存在させるべきです。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テンプレートです：

# 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 guidance」セクションはオプションですが、AI駆動プログラミングでは極めて価値があります — 同一コードベースの領域で働く将来のエージェントに対する永続的な指示として、意思決定記録を変換します。

意思決定記録に何を含めるべきか

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

良い候補は、以下の決定です：

  • システムの複数の部分を影響する
  • 製品の約束を符号化する
  • 実際の議論を解決する
  • 長期的なトレードオフを導入する
  • ビジネス、コンプライアンス、または運用制約に依存する
  • 後に再発見するコストが高い
  • 将来のAIツールが誤解する可能性が高い
  • 将来のコントリビューターが軽率に取り消そうとする誘惑がある

悪い候補には、小さなリファクタリング選択、明白なバグ修正、一時的な実験、ローカルの命名決定、永続的な結果のない実装詳細が含まれます。良いルールは明白です：決定を取り消すのに議論が必要であれば、その決定を記録してください。

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

意思決定記録には、現在の立場を示すライフサイクルが必要です。最もシンプルなステータス値が十分です。

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

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

Superseded（差し替え済み） — 決定は新しい記録によって置き換えられました。古い記録を削除しないでください；履歴のためにそれらを保持し、新しい決定にリンクすることで、思考の進化が視覚的にわかります。

Deprecated（非推奨） — 決定はもはや推奨されていませんが、システムの既存部分の説明としてまだ機能する場合があります。これは、古いパターンが新しいアプローチと並んでコードベースに存在する移行中に特に有用です。

重要な原則は、意思決定記録が追記可能であるべきということです。チームが方向を変えた場合、新しい記録を作成し、古いものにリンクするのではなく、過去をよりクリーンに見せるために歴史を書き換えるべきではありません。

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は、なぜチームがより単純な代替案またはより分散された代替案ではなく、その境界を選んだかを説明します。

仕様は実装をガイドします。意思決定記録は判断を保持します。 together、AIコーディングエージェントに両方、つまり「何を」そして「なぜ」を与え、これが複雑で長寿命のシステムにおいてこの組み合わせをこれほど効果的にするものです。仕様駆動ツールチェーンを採用する際は、各オプションがそのコンテキストをどのように表面化するかを比較してください；GitHub Spec Kit vs Kiro vs Claude Code SDD Workflows は、主要なセットアップ全体のポータビリティ、レビューゲート、およびリポジトリの根拠化を分解します。それらのツールが実装するツール非依存の5フェーズプロセスについては、要件からコードへの仕様駆動開発ワークフロー を参照してください。ほとんどのSDDツールは、そのループの「リリース済み」半分だけをクリーンに処理します；OpenSpec Rejected Proposals: A Decision Memory Convention は、もう半分 — エージェントが同じアイデアを再提案する前にチェックするように、拒否された決定を永続的に記録すること — に取り組んでいます。

意思決定記録は仕様ではない

意思決定記録は仕様に関連していますが、異なる目的を果たします。仕様は「システムはXをしなければなりません」と述べ、意思決定記録は「これらの制約とトレードオフのため、YではなくXを選びました」と述べるのです。その「Yではなく」が価値ある部分です。AIツールは、要求された結果への妥当な経路を見つけることでソリューションを生成しがちですが、意思決定記録は、どの妥当な経路がすでに探索、評価、そして拒否されたかを伝えます — チurn（無駄な変更）を減らし、AI支援作業の品質を向上させます。

意思決定記録はテストの代わりではない

テストは動作を検証し、意思決定記録は意図を説明します。どちらも必要であり、一緒に機能します。テストはAI生成メールが下書きとして保存されなければならないことを強制でき、製品意思決定記録は、AI生成の通信がシステムから出る前にユーザーがレビューする必要があるため、これが必須であることを説明します。テストは動作を守り、意思決定記録は意味を守ります。 together、将来の変更をより安全で予測可能にします。

意思決定記録はコードコメントの代わりではない

コードコメントはローカルな実装詳細を説明し、意思決定記録はより広範な決定を説明します。驚くべき行、エッジケース、ワークアラウンド、および単純化できない関数にはコメントを使用してください。アーキテクチャが存在する理由、製品動作が存在する理由、インタラクションパターンが存在する理由、およびチームが一方の方向を他方よりも選んだ理由は、意思決定記録を使用してください。説明が数行のみに影響する場合、コメントが正しいツールです。システムの方針に影響する場合、意思決定記録が正しいツールです。

一般的なミス

記録を遅く書く

意思決定記録は、決定がなされたときに書かれるべきであり、何ヶ月も後にすべてのトレードオフを忘れたときに書くべきではありません。プルリクエスト中に草稿を作っても問題ありません。しかし、決定がまだ活発に議論され、代替案が新しい間に、実装前に草稿を作ることはさらに良いことです。

記録を長すぎる

意思決定記録はエッセイではありません。判断を保持するのに十分詳細ですが、人々が実際に読むほど短くあるべきです。網羅性よりも明確さを優先してください — 読まれる簡潔な記録は、スキップされる総合的な記録よりはるかに価値があります。

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

結果セクションは記録の核心です。明示された結果のない決定は、しばしば真の決定ではなく、単なる好みです。良い記録はトレードオフを正直に認め、選択の結果として何が難しくなり、何がリスクが増加するを含みます。

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

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

AI生成の記録をレビューなしでマージさせる

AIは、洗練され、よく構造化されているが、微妙に誤った記録を生成できます。AI生成の意思決定記録は、AI生成のコードと同じように扱ってください — 注意深くレビューし、根拠が正確であることを確認し、結果セクションがチームが実際に受容したもの反映了ことを確認してください。

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

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

軽量な運用モデル

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

  1. プランニングまたは実装中、意味のある決定がなされているかどうかを特定します。
  2. AIアシスタントに、議論に基づいてADR、PDR、またはDDRを起草するよう依頼します。
  3. コンテキスト、代替案、結果を検証しながら、チームとして草稿をレビューします。
  4. 記録をMarkdownとしてリポジトリにコミットします。
  5. 関連する問題またはプルリクエストからリンクします。
  6. AIコーディングツールに、その領域で将来の変更を行う前に関連する記録を読むよう指示します。
  7. 決定が変わったら記録を差し替え、履歴のために古い記録を保持します。

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

例：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.

関連する読書

購読する

システム、インフラ、AIエンジニアリングの新記事をお届けします。