BDD・ADR・PRD・WTF：人間も AI も決断を記録する

AI エージェント開発の破綻を防ぐ：記録・検証・強制の 3 つの柱

AI エージェントがコードを生成するだけでなく、組織のルールやアーキテクチャを遵守して自律的に動作するためには、「人間の忘却」と「AI のコンテキスト制限」を克服する必要があります。その鍵となるのは、単なるコード生成ツールを超え、設計思想から UI まで一貫性を担保する仕組みを構築することです。

本記事では、意思決定の記録（ADR/PRD）、実行可能な仕様（BDD）、そして自動的な強制ループという 3 つの要素が、どのように複雑な AI 開発における品質保証と自律性を支えるのかを解説します。

人間の忘却と AI の限界：なぜ「記録」が必要なのか

AI エージェントの開発において最も深刻な問題は、人間も AI も「記憶」に依存している点です。科学者が行った猿の実験で示されたように、組織には理由が不明なままルールが継承される傾向があります。しかし、現代の開発ではより深刻な問題が発生しています。

製品を使い始めてしばらく経つと、チームは問い始めます。「なぜこのフローがあるのか？」「なぜこのコードはあの形なのか？」

創設エンジニアですら、数週間後には「なぜその設計にしたか」を説明できなくなります。LLM（大規模言語モデル）も同様で、コンテキストの制限により過去の決定を忘れてしまいます。この状態では、AI エージェントが誤った判断を下したり、一貫性のないコードを生み出したりするリスクが高まります。

これを解決するのがADR（アーキテクチャ決定記録）とPRD（製品要件定義書）です。

ADR：なぜその設計にしたのかを記録する

ADR は、アーキテクチャ上の重要な決定とその理由、実装方法、そして「なぜそうするのか」を文書化するものです。単なるメモではなく、参照ドキュメントやコードスニペットの例を含め、組織の知見として蓄積します。

例えば、「N+1 クエリを防ぐためにコードをレイヤーに分割する」という決定を下した場合、その理由と実装ルール（モジュール内のインポート制限など）を ADR に明記します。これにより、AI エージェントが新しい機能を実装する際にも、過去の失敗や設計意図を参照して、一貫した判断を下すことができます。

PRD：機能の目的と体験フローを定義する

PRD は、ADR よりも軽量な文書ですが、機能開発における「なぜ」を明確にします。その機能が解決する問題、ユーザーがアプリ内でどのように行動するか、そして最終的なゴール是什么かを記述します。

6 週間後、自分がなぜそうしたのか忘れた時にも役立ちます。

これは AI エージェントのためだけでなく、人間側の開発者にとっても、過去の判断を振り返るための羅針盤となります。AI に与える指示も、「機能を作る」ではなく「この問題を解決し、この体験を提供する」という文脈を含めることで、より意図に沿ったコードが生成されます。

仕様と実装のギャップを埋める：BDD と Cucumber の再評価

多くの開発者が直面する課題に、「仕様に準拠しているか」を検証する方法があります。Markdown で記述された仕様書があっても、それが実際に動作するコードとして検証されることは稀です。

AI が生成したテストを読むことより難しいのは、AI が生成したコードを読むことです。

ここで有効なのがBDD（振る舞い駆動開発）と、その実装ツールであるCucumberです。BDD は、人間が読みやすい自然言語（Gherkin 構文など）でシステムの振る舞いを記述し、それを AI も理解できる実行可能なテスト仕様として機能させます。

Cucumber を活用することで、以下のメリットが生まれます。

• 中間層の確立: 人間の言葉で「アプリがどのように振る舞うべきか」を記述する中間層が存在します。
• 検証可能性: シナリオは PRD や重要なユーザーフローに直接結びつけられ、仕様と実装の整合性を自動検証できます。
• AI との対話: AI は生成したコードが BDD テストを満たしているかを確認でき、人間もそのテスト内容を読みやすくレビューできます。

これにより、「仕様主導型開発」が抱えるループ（仕様が書かれているが実行されていない状態）を埋め、AI エージェントが正しい振る舞いをするよう強制します。

UI の混沌を防ぐ：設計システムによる強制力

AI エージェントに UI を構築させる際、最も難しい課題の一つが一貫性の維持です。人間が手動で実装する時代から、デザインシステムやパターンライブラリは存在しましたが、AI 時代にはそれが「ルール」として厳格に適用される必要があります。

メインボタンはこれとこれです。青色で、この形状をしています。サイト上で同時にメインボタンを一つだけ表示します。

設計システムでは、コンポーネントの色、サイズ、状態、そして使用ルール（例：1 ページに 1 つのメインボタン）を明確に定義します。AI エージェントは、これらのルールに基づいてコンポーネントを組み立てることで、一貫性のある UI を構築できます。

また、インラインスタイルの使用禁止や、特定のデザイン原則への準拠も、設計システムを通じて強制されます。これにより、コードが混沌とするのを防ぎ、再利用可能な部品として AI が自律的に動作できる基盤を作ります。

自動フィードバックループ：Git Hooks と CI/CD でルールを強制する

優れた文書や仕様があっても、AI エージェントがそれを守らない限り意味がありません。重要なのは、「記録→検証→強制」のサイクルを自動化し、AI がルールを破った瞬間に即座にフィードバックを与える仕組みです。

この仕組みは、Git Hooks、CI/CD、リンターを組み合わせた自動 enforced ループ（ハネス）によって実現されます。

1. 事前チェック: エージェントがプルリクエストを作成しようとする際、Git Hooks が自動的に実行されます。ここでは、コードのスタイル、型チェック、重複検出だけでなく、「アーキテクチャ違反」や「ドキュメント不整合」もチェックします。
2. 即時フィードバック: ルール違反が見つかった場合、コミットは拒否され、AI エージェントにエラーメッセージと関連する ADR や PRD のリンクが返されます。
3. 自己修正: AI は指示された文書を読み直し、ルールを遵守するようにコードを修正します。これをループして行うことで、最終的に仕様に合致したコードだけがマージされます。

ルールであり、強制され、自動化されています。なぜなら、これらについての議論の余地がもうないからです。

このアプローチにより、スタイルやフォーマットに関する人間同士の議論は不要となり、AI は自律的に高品質なコードを生成し続けることができます。また、BDD テストスイートがデータベースにアクセスできないルールなどを設けることで、N+1 クエリなどの根本的な問題を未然に防ぐことも可能です。

まとめ：記録と強制こそが AI 開発の自律性を支える

AI エージェントを単なるコード生成ツールから、組織のルールやアーキテクチャを理解して自律的に動作する開発パートナーへと進化させるには、ADR や PRD による「意思決定の記録」、BDD による「実行可能な仕様」、そして Git Hooks を活用した「自動強制ループ」が不可欠です。

これらを組み合わせることで、人間の忘却や AI のコンテキスト制限という壁を乗り越え、複雑な開発環境においても一貫性と品質を保証する基盤が完成します。これが、エンタープライズレベルの AI 開発における真の自律性とセキュリティを担保する鍵となるのです。