ADR-0025: 文脈の乖離でビルドを落とさず、検知より記載の削減を主とする

ステータス

採用(2026-08-07)

コンテキスト

開発が速くなるほど文脈の更新は後回しになり、実態と食い違う記述が残る。AI は古い記述を正しい前提として扱うため、誤りが増幅される。

規定済みだったのは、陳腐化の検知3手段(参照切れ・更新の停滞・実態との乖離)と、指示資産の保守要求(分量の上限、追記条件、削除権限の集約、四半期の棚卸し、導出できる内容を書かない、読み込み実績の記録)の2つにとどまる。欠けていたのは、コードの変更と文脈の更新の乖離を機械で検知する仕組みと、古い記述を参照対象から外す手続にあたる。

調査により次を確認した(research/phase4-standard/133-context-freshness.md)。

大規模な静的解析の運用指針では、ビルドを落とすか、そもそも出さないかの2つしか置いていない。「We either enable a compiler check as an error (and break the build) or don’t show it in compiler output.」。落としてよいのは機械的で実効的な偽陽性がない解析に限られる
**実効偽陽性は「開発者が見て何も行動しなかった指摘」**と定義されている。技術的に正しくても行動につながらない指摘は偽陽性として数える
第3章 3.11.4 は既に、分量が増えるほど遵守率が下がること、入力長の増加で精度が非一様に低下すること、指示ファイルの付与で成功率は改善せず費用が2割超増えたことを根拠に持っている。「多く書く」方向の解決は精度と費用の両面で不利である

決定

乖離の検知でビルドを落とさない。警告としても出さない。台帳へ記録し、既存の四半期の棚卸しの入力とする
参照切れ(リポジトリ内のパスに限る)と分量の上限超過は落とす。機械的で実効的な偽陽性がないためである。G-5 の判定基準6 とする
外部リンクの死活を落とす対象に含めない。ネットワークの一時的な障害で失敗し、実効偽陽性が生じる
コードと文脈の対応表を別ファイルで保守しない。対応は文脈ファイルの frontmatter(scope)へ書く。別置きの表は、その表自体が陳腐化する
乖離を変更履歴だけで定義する。「scope に該当するコードが、当該文脈ファイルの最終更新より後に一定の回数を超えて変更された状態」とし、内容を読まない
乖離の閾値の初期値を本標準が示さない。実証がないためである
記載内容の削減を主とし、検知はその入力とする。忘却は鮮度の維持と分量の抑制を同時に果たす操作である
外す第一の基準を「読み込まれていない」とする。3.11.4 要求事項6 の読み込み実績を用い、新しい計測を追加しない
削除ではなく保管とする(要求事項7を新設)。保管領域はエージェントが読み込むパスの指定から明示的に除外する。外した日・理由・外した者・復帰の条件を記録する
外す判断を AI に行わせない。要求事項3 のとおり権限は AI維持管理者1名に集約し、AI は候補の提示までとする
新しい判定の場を設けない。判定は既存の四半期の棚卸しで行う

検討した選択肢

乖離でビルドを落とす — 無視されなくなるが、内容のない形式的な更新が入る。乖離の判定は対応関係の推定を含み、実効的な偽陽性が生じる。落としてよい条件を満たさない
乖離を警告として出し続ける — 実装は最も簡単だが、調査した運用指針が明示的に避けている構成である。無視できる警告は無視される
一定件数を超えたら差し戻す — 中間の設計として検討したが、閾値の根拠がない。加えて、件数で差し戻すと期限の直前に一括で形式的な更新が入る。棚卸しで扱うほうが、内容の判断を伴う
コードと文脈の対応表を別ファイルで持つ — 一覧性は高いが、その表自体が陳腐化する。本 ADR が解こうとしている問題を、対象を変えて再生産する
CODEOWNERS を対応表として流用する — 既存の仕組みを使えるが、CODEOWNERS が表すのは「ファイル → 人」であり「文脈 → コードの範囲」ではない。意味が異なる
検知の強化を主とする — 直感には合うが、3.11.4 の根拠に照らすと逆である。記述が減れば乖離しうる記述も減る。検知を強めても記述は減らない
外す判断を AI に行わせる — 棚卸しの負担は減るが、誤って外すと必要な前提が失われる。5.7.4・G-4 と同じ切り分け(機械は候補まで、判定は人)を維持する
外した記述を削除する — 分量は最も減るが、誤りを取り返せない。保管して復帰の条件を定めるほうが、外す判断の心理的な障壁も下がる

影響

第3章 3.11.4 に要求事項7(保管)を追加し、棚卸しの入力・AI へ判断させない旨・乖離で落とさない旨を規定した
第4章 G-5 に判定基準6(文脈ファイルの形式検査)を追加した。乖離を含めない旨を明記した
フェーズ5 context-base.md の陳腐化の検知の表へ扱いの列を追加し、「乖離の監査」「忘却の手続」の2節を新設した
新しいゲート・判定の場・記号のいずれも増やしていない。既存の四半期の棚卸しへ入力を足した
調査根拠は research/phase4-standard/133-context-freshness.md に記録した
決定6 により、乖離の閾値は組織が定める。初期値がないため、導入時に決める手間が残る
決定4 により、既存の文脈ファイルへ scope を後から付与する作業が発生する。付与しないファイルは監査の対象外となり、乖離が検知されない
コードと文書の乖離検知の精度を測った研究は複数あるが、対象はソースコード中のコメントであり、文脈基盤の文書ではない。本標準は精度の数値を引用していない
「読み込まれていない記述を外す」運用、および保管した記述を復帰させる運用の実証は特定できなかった。本標準の独自の構成である
CACM 2018 の論文本文は 403 のため未取得であり、書籍の章を根拠とした