AIはsupersede済みADRに惑わされるのか。175試行で確かめて運用ルールを決めた

こんにちは、テックドクターでバックエンドエンジニアをしている筧です。

AI エージェントを使って開発するようになってから、ADR（Architecture Decision Record）をこまめに残すようになりました。文書にして渡すことで、エージェントに設計判断を守らせることが狙いです。

ただ、ひとつ疑問に思っていることもあります。
設計判断は、後から覆ることがありますよね。その場合、古い ADR に「Superseded by 〜（〜に置き換えられた）」という印を付けて新しい ADR を起こすのが一般的な流儀ですが、AI はこの置き換え（supersede）をちゃんと追ってくれるのでしょうか。古い決定がまだ有効だと思い込み、廃止済みの設計でコードを書いたりしないのでしょうか。

今回のエントリでは、それを実際に検証してみました。
社内の実リポジトリを対象として Claude 系4モデルと OpenAI Codex の両方で検証、結果を踏まえて ADR の運用ルールを作り、チームで v0.1 として採択したところまで含めてご紹介します。

社内のADR運用は1年でバラバラに独自進化

検証の前に、まず社内での ADR の運用状況を確認してみましょう。
社内で ADR を持つリポジトリは 8 つ。ADR の数は合計 119 本でした。ほとんどがこの1年で書かれたもので、AI エージェントとの開発が本格化した時期と重なります。

そして 8 リポジトリを比較すると、それぞれバラバラの書き方で ADR が独自進化していることもわかりました。

観点	社内の実態
置き場所	docs/adr/ 配下、リポジトリ直下の adr/、エージェント設定ディレクトリ配下の3流派
採番	3桁連番、4桁連番、プレフィックス付き連番、タイムスタンプの4方式
ステータスの語彙	採用 / Accepted / accepted / 承認 / 承認済みの5表記
ルールの明文化	詳細な規約を持つリポジトリから、ルール文書なしまで混在

また書き方の不統一以外にも、運用上いくつか気になっている点もあります。

ステータス管理。提案中の ADR を PR で出し、マージされた後に「承認済みに変えるだけの PR」を出す運用に違和感がある。
仕様を改訂したときの記録方法。supersede で新しい ADR を起こすのか、部分改訂で済ませるのか。そもそも AI は改訂の時系列を追えるのか？
粒度。障害対応メモに近いものから基盤方針まで、書かれる決定の大きさがばらばら
フォーマット統一。チームで統一したい気持ちと、読めればそれでいいという気持ちの間で揺れている
量とトークン。ADR 同士が相互参照するので、AI に読ませる量が膨らむ

この中で、特に気になっていたのが改訂でした。どういった運用がAIにとって追いやすいのかは、検証してみる必要がありそうです。

実験: AIはsupersede済みADRに騙されるのか

では実際に、実験してみましょう。実験方法はこのように設計しました。

素材：
社内の実リポジトリ3つ、ADR 計70本を使用します。
3つのリポジトリは supersede の記法が異なります。

ステータス行に「Superseded by 〜」と書き、後継側にもメタデータ行を持たせ、索引（全 ADR のタイトル・ステータス・置き換え関係を表として並べたファイル。index.md）に取り消し線を引く
置き換えられた側の冒頭に撤回理由を数行書き足し、新旧を双方向でリンクする
ステータス行は簡素にして、索引の関係列で「置き換え / 部分置き換え（節単位）」を管理する

質問：
AI エージェントに対して、仕様に関する7つの質問をしました。
質問には現行の方針を答えさせるものと、方針の変遷を説明させるものを混ぜました。

条件：
3通りの条件を用意し、それぞれ実験を行います。

ADR をそのまま渡すもの
索引も含めて渡すもの
（対照実験として）supersede の印をすべて機械的に除去するもの
（対照条件は、ステータスの更新を忘れたリポジトリを模してもいます）

実験対象：
回答するのは実験意図を知らされていない素の AI エージェントです。

Claude で4モデル（fable-5、Opus 4.8、Sonnet 5、Haiku 4.5）各条件２試行ずつ
同モデルに対する追試
OpenAI Codex 上の2モデル（gpt-5.4 と gpt-5.4-mini）で縮小版

追試では、「現行の方針はどれか」という調査型ではなく、「編集途中の状態を失わないように下書き保存を追加したい。どこで保持すべきか」のような実装相談の形で、かつ廃止済みの設計の側に誘導する言葉を仕込んで質問しました。より実務上のユースケースに近い形で検証を行うためです。

試行回数は合計で、Claude には175試行、Codex には50試行となります。

※採点は正解を知る筆者による非盲検で、実験の実行と採点には Claude Code の支援を使っています。被験モデルの答案を同系統の AI が手伝って採点する構図になるため、先に基準を固定して裁量を狭めました。

結果：AIエージェントは騙されなかった

実際に実験をしてみた結果……。

予想外の結果が出ました。明示的に「廃止済み」の仕様を現行として答えた試行は、4モデル175試行を通じてゼロでした。

さらに意外なことに、fable-5 では、supersede の印をすべて除去した対照実験でさえも（！）誤答が出ませんでした。後継 ADR の本文に「前の方針をなぜやめたのか」という経緯が書かれており、そこから時系列を読み取ったようです。くわえて、ファイル名の連番や、後続 ADR の参照関係も手がかりになっていました。
撤回理由を本文に書き残す文化は、保険として大いに機能することが分かりました。

そして誘導を仕込んだ追試でも、多くの試行は釣られず、むしろ「その方向は撤回済みの設計への逆戻りになる」と経緯を引用して警告してきました。AI を釣るつもりが、逆にたしなめられてしまいました……。

索引の有無による影響は、正答率、探索コストのどちらにも見受けられませんでした。エージェントは、索引をもっぱら本文で得た結論の確認と補強に使っていました。

コスト面では、fable-5 の本試行の探索コストは、1回の回答でツール呼び出し3〜10回、数万トークン規模でした。

また Codex でも結果は同じでした。廃止済みを現行と答えた回答はゼロ、減点となった12件はすべて例の ADR ペアが原因でした。
ただし、supersede の印を除去した対照実験でも正解できたのは Claudeの上位モデルだけで、Codex の2モデルはうまくいきませんでした。

唯一の落とし穴は……運用不備

一方で、Claude 系の175試行のうち、13件で減点が発生しました。原因をたどると、すべて同一の新旧 ADR のペアに起因していました。

その ADR ペアは、

旧 ADR が Accepted のまま
新 ADR は実装済みなのに Proposed のまま
新 ADR の関連 ADR にも、置き換え元として旧 ADR が示されていない

という状態になっていました。

新 ADR よりも後の関連 ADR を見ると新 ADR の仕様が前提になっていることが分かるのですが、ステータスを信じると古い方が現行に見えます（実験用に仕込んだ罠ではなく、人間がたまたま改訂を忘れていた、実在する ADR でした）。

これに対して、上位モデルは「後続の ADR 群が新しい方を前提にしている。更新漏れではないか」と自発的に警告してきました。一方でHaiku はステータスをもとに古い仕様を現行と答えました。軽量なモデルほど、ステータスの正確さが重要になるようです。

また、質問の仕方も回答に影響するようでした。調査型の質問では正解できる Claude の上位モデルも、「できるだけ早く反映したい」といった相談の仕方をすると間違った回答をします。

検証の結果は以上です。AI の読解力は、思っていたより正確でした。むしろ問題は人間側の運用の方で、ステータスの更新を忘れないこと、その重要性が再確認できました。

※試行数は小規模で、かつCodex 側は縮小版のため、モデル差・基盤差が完全に検証できていない可能性はあります。また今回の検証は撤回理由をしっかり書く文化のリポジトリなので、そうでない ADR 群では結果が変わる可能性があります。

実験結果をもとに運用ルールを整備

その後、上記の検証の結果を踏まえて、新たな運用ルールを定めることにしました。
下記が、筆者が暫定案として起票し、チームレビューを経て v0.1 として採択された新たなルールです。

マージ＝採用とし、ステータスを変えるだけの PR をやめる。
最初に挙げた「『承認済みに変えるだけの PR』を出す運用への違和感」が解消されるとともに、誤答の原因となった「提案中のままマージされ、承認済みへの変更を忘れる」が構造的に起きなくなります。
方針変更の宣言は新旧双方に書き、理由を本文に書く。
万が一ステータス更新忘れがあった場合でも、変更経緯が書かれていれば保険になることが、実験で検証できました。
粒度は既存ガイドの基準を借りる
この記事が良いガイドになりました。中でも「現場で遭遇する罠と対策」のパートに書かれたADR に書く基準、「複数コンポーネントに影響するか」「6ヶ月後に説明を求められるか」「複数の選択肢を検討したか」は非常に参考になりました。
索引を整備する
索引の有無で正答率は大きく変わりませんでしたが、エージェントは結論の確認に使っていました。人間の一覧性のためにも整備します。
置き場所と採番は統一しない、と決める
連番は複数人運用時に衝突しますし、タイムスタンプはあとで統合したときに時系列が失われます。統一したい気持ちはありつつも、いったん「読めればよい」としました。
統一しないのは外側だけで、中身は揃える
新規 ADR は Status、Context、Decision、Consequences に相当する項目を持ち、main 上のステータスは Accepted、Rejected、Deprecated、Superseded by リンク、Amended by リンクの5つのいずれか1つに固定します。
また、Proposed は PR 中にだけ存在可能とします。これで実験中に問題となったステータス更新漏れも、今後は CI で機械的に検出できるようになります。