設計意図をAIに渡すと、コード品質が上がる。これは私たちの実験でも確認された事実です。しかし実験はもうひとつ、興味深い事実を明らかにしました。
設計意図の記録が「一部だけ」存在する状態は、AIにとって独特のプレッシャーになる、ということです。
記録のある領域とない領域の「落差」
私たちの対照実験には、プロジェクト途中から設計意図を追加した条件がありました。開発の後半で、AIにコードベースを探索させ、実装から推測できる設計方針をsqlewに登録したものです。
この条件の成績は一見優秀でした。根拠の品質は、プロジェクト初期から設計意図を記録していた条件の98%に迫り、過去の方針への参照頻度では設計意図なしの条件の207%を記録しています。
しかし、テストに関する思考密度だけが異常な値を示していました。
テスト思考密度254%：AIの「不安」の痕跡
AIの推論パターンを分析すると、途中追加条件のテスト関連キーワード出現密度は1万文字あたり60.41。初期導入条件の23.76に対して254%、設計意図なし条件の39.39に対しても153%という膨張です。
この数値が意味するのは、AIがテストを「書きすぎている」ということだけではありません。テストについて「考えすぎている」ということです。E2Eテスト生成のプロンプトに対し、途中追加条件は10個のスペックファイルに25件のテストを生成しました。初期導入条件の5ファイル・16件と比較して、出力量は多いのに有効テスト数に大差はなく、超過分は純粋なオーバーヘッドでした。
なぜ途中導入だけでこうなったのか。原因は「意図がある領域とない領域の落差」にあります。
AIは「地図にない場所」を警戒する
コードベースからADRを逆算した場合、すべての実装が均等にカバーされるわけではありません。設計判断が明確に読み取れるモジュールもあれば、慣習的に書かれたコードや歴史的経緯が複雑なモジュールもあります。結果として、ADRの記録密度にまだら模様が生じます。
ここでAIの立場になって考えてみてください。プロジェクトの一部には「なぜこう実装したか」の記録がある。しかし別の一部にはない。AIはこの非対称性を「記録し忘れた」のか「重要でないから記録しなかった」のか判断できません。
そしてAIは安全側に倒します。方針が明示されている領域では、その方針に沿って効率的に動く。方針が存在しない領域では、「何か見落としているかもしれない」と防御的に振る舞い、テストを手厚く書くことでリスクを補償しようとする。テスト思考密度254%は、この防御行動の痕跡です。
興味深いのは、設計意図なし条件ではこの現象が起きていないことです。設計意図の記録がまったくなければ、AIは全領域を均等に扱います。落差が存在しないため、特定の領域を警戒する理由もない。過剰実装は「設計意図がない」ことではなく「設計意図がまだらにある」ことで誘発されていたのです。
対処法：誓約で空白を意図的に埋める
この問題は、sqlewの誓約（Constraint）機能で対処できます。
方針がないことでAIが不安を感じるなら、「ここは意図的にスコープ外としている」と明示すればよいのです。「方針に未記載の領域は現時点では対象外とする」「既存テストが存在する機能への追加テストは、方針に基づく場合のみ作成する」といった誓約を登録することで、AIは空白を「情報の欠落」ではなく「意図的な除外」として解釈できるようになります。
初期導入条件でこの問題が起きなかったのは、開発の過程で「やること」と「やらないこと」がセットで自然に蓄積されていたからです。途中導入では、この「やらないこと」の記録を意識的に補完する必要があります。
途中導入でもADRの質を上げる方法
コードベースの解析だけでは「やらないこと」は見えてきません。しかし、コード以外の情報源にはそれが残っています。
設計ドキュメントや議事録から抽出する
設計ドキュメント、ADR、議事録、Wiki、READMEといった既存の文書には、コードには現れない「なぜこの方針にしたのか」「どの選択肢を検討して何を採用しなかったか」が記録されていることがあります。これらはまさに、途中導入で不足しがちな誓約の原材料です。
ドキュメントが特定のディレクトリにまとまっている場合は、AIにまとめて読み込ませるのが効率的です。
docs/ と wiki/ にある設計ドキュメントを読み、
このプロジェクトの設計方針と、採用しなかった選択肢を
sqlewの方針・誓約として記録してください。
特に「なぜその判断をしたか」と「何をやらないと決めたか」を重視してください。議事録がある場合は、決定事項だけでなく却下された提案にも注目するよう指示するのがポイントです。却下の理由こそが、AIの行動範囲を制限する誓約になります。
GitHub Issue & PRから抽出する
GitHub CLIの gh コマンドを使えば、IssueやPull Requestの議論をAIに直接取り込めます。PRのレビューコメントには「なぜこの実装を選んだか」が、Issueのディスカッションには「検討したけれど見送った案」が残っていることが多く、コードからは読み取れない設計判断の文脈を補完できます。
gh を使って過去のIssueとPRを取得し、
このプロジェクトの設計上の意思決定の歴史を
sqlewの方針・誓約として記録してください。
PRのレビューコメントで議論された設計判断と、
Issueで検討されたが採用されなかった選択肢に特に注目してください。取得対象が多い場合は、ラベルやマイルストーンで絞り込むと精度が上がります。
gh を使って "architecture" ラベルのついたIssueと、
マイルストーン "v1.0" に紐づくPRを取得し、
設計方針と誓約をsqlewに記録してください。この一連の作業自体をAIに委ねることで、途中導入でも実用的なADRの構築が可能になります。コードだけでは「アクセルだけの地図」しか描けませんが、ドキュメントとGitHubの議論を加えることで「ブレーキの位置」も記録された、バランスの取れた設計記録が得られます。
プロジェクト初期からの導入が理想である理由
もちろん、最も効果的なのはプロジェクトの最初からsqlewを導入することです。開発の過程で方針と誓約が均衡しながら蓄積されるため、ADRのカバレッジにまだら模様が生じません。AIは全領域で一貫した精度で動作し、テスト思考密度も適正範囲に収まります。
「まず途中導入で効果を確認し、次の新規プロジェクトで初期から導入する」。実験データが示す現実的な移行パスです。
参考文献
- "Rediscovering Architectural Decision Records: How Persistent Design Context Improves LLM Code Generation" — Shingo Kitayama (2026) — sqlew Efficacy Study
- "Context Length Alone Hurts LLM Performance Despite Perfect Retrieval" — ACL Findings (EMNLP 2025)
