TL;DR
- Copilot coding agentを使った開発で、設計書（ファイルツリー）が更新されないまま実装が進み、デグレが起きる問題に直面しました
- 原因は「AIが悪い」のではなく、前提が変わるのに、前提を固定しないまま指示していたことでした
- ADR（Architecture Decision Record）を使って前提を明示・固定し、agentに段階実行させる運用に変えました
- 結果として、同種のデグレを約2時間で再発しにくい状態まで抑え込めました
背景：Copilot coding agentで起きた「静かなデグレ」
Copilot coding agentを使って、設計 → 実装 → テストまでを自動化する流れを作っていました。
あるとき、実装自体は正しく見えるのに、
- 設計書と実装が微妙にズレる
- ファイル構成が意図と違う
- 後続の修正で別の箇所が壊れる
という 「一見問題なさそうに見えるデグレ」 が発生しました。
問題の正体：AIではなく「前提が固定されていない」こと
最初は、
- agentの理解が甘い？
- プロンプトが弱い？
- モデルの限界？
と思ったのですが、ログを追うと違いました。
何が起きていたか
- 設計書（
architect.md）のファイルツリー定義が途中で変わった - しかしagentは最初に読んだ前提のまま実装を継続していた
- 人間側も「変わった前提」を明示的に伝えていなかった
つまり、
前提が変わるのに、前提を固定・更新する仕組みがなかった
これが原因でした。
図で見る：Before / After
Before：前提が流れる
After：ADRで前提を固定する
なぜAgentはこの問題に弱いのか
人間同士のチームであれば、「あの時こう決めたよね」という文脈を暗黙的に共有できます。会話・記憶・空気感で補完できるからです。
しかしAgentはセッションをまたいで文脈を引き継げません。前提が変わっても、それを明示的に渡さない限り、最後に読んだ状態を正として動き続けます。
つまりADRは、今まで「大規模チームのドキュメント文化」の産物として語られてきましたが、Agent開発においては**「人間がAgentに渡す引き継ぎ書」**として機能します。Agentを使う規模が大きくなるほど、「決定をどこに書いておくか」が開発の安定性に直結してきます。
参考にした考え方：github/gh-aw の設計スタイル
ここで参考にしたのが github/gh-aw（GitHubが公開しているAgentic Workflowのリファレンスリポジトリ）です。
このリポジトリでは、
- 人間は「何を決めたか」を明示的に書く
- agentは「決まった前提の中で」作業する
- 前提が変わるときは、必ず決定を更新する
という思想が一貫しています。
解決策：ADRで「前提」を固定する
そこで取ったのが ADR運用 です。
ADRとは
Architecture Decision Record の略で、「何を」「なぜ」「どこまで」決めたかを明文化する記録です。詳細は adr.github.io を参照してください。
今回の使い方
- 設計書（
architect.md）の第4章：ファイルツリー定義を対象に - 「ここまでは決定済み」「ここからは未決定」をADRで明示
- agentにはADRを前提として順番に実行させる
実際の構成
.
├── architect.md # 全体設計
├── adr/
│ └── ADR-001.md # 前提・決定事項の固定
└── .github/
└── copilot-instructions.md
ADRに書いた内容（例）
| 項目 | 内容 |
|---|---|
| 対象 | ファイルツリー構成 |
| 決定事項 |
pkg/ 配下の責務分離 |
| 非対象 | 将来の拡張用ディレクトリ |
| 禁止 | ADR未更新での構造変更 |
agentの動かし方（重要）
ADRに以下のステップを書き、順番に実行させました。
- ADRを読む
-
architect.mdの該当章を確認する - 実装を行う
- テスト・検証する
- 結果をレポートする
これにより、
- 「勝手に解釈を広げる」
- 「古い前提で実装を続ける」
といった挙動が止まりました。
結果：デグレは「防げる問題」になった
この運用に変えてから、
- 同種のデグレは再発していません
- 問題が起きても「どの前提が壊れたか」がすぐ分かります
- 人間のレビュー負荷も減りました
AIが賢くなったわけではありません。前提を固定しただけです。
学び
- AIは「曖昧な前提」を自分で補完してしまいます
- それはバグではなく、仕様です
- 前提が変わるなら、人間が決定として固定する必要があります
Copilot coding agentは強力ですが、設計と意思決定を省略できるわけではありません。
むしろ、
「人間は決める、AIは実行する」
を徹底した方が、開発は安定します。
おわりに
「AIがデグレを生む」のではなく、決定を記録しない運用がデグレを生みます。
ADRは地味ですが、agent開発ではかなり効きます。
次の一手（検討中）
- ADRテンプレを公開する
- gh-aw構成を最小化したサンプルを作る
- チーム向けハンズオンに落とす