# 設定ドリフト照合器が「毎朝ずっと赤」になるのを止める（照合対象外の値の扱いと guard の当て方） ## これは何の指示書か 本番設定（価格パラメータ・機能フラグ・しきい値など）の「決定台帳」を JSON で持ち、 毎日のバッチで実設定と機械照合して差分（ドリフト）を検出する仕組みを運用している人向け。 この仕組みは**必ず一度は「常に赤」に落ちる**。落ち方の型と、二度と起きないようにする guard の当て方を書く。 AI エージェントに読ませればそのまま設計・修正できる粒度にしてある。 ## 起きること（実例・2026-09） 台帳のエントリはこういう形をしている。 ```json { "parameters": { "upperPrice": { "configPath": "pricing.upperPrice", "current": 14100, "status": "decided", "rationale": "…なぜこの値にしたか…", "history": [ { "at": "…", "value": 16000, "note": "…なぜ覆したか…" } ] } } } ``` 照合器は `configPath` を本番設定 API の戻り値に対して `split('.')` で辿り、 値が一致すれば OK、辿れなければ MISSING、違えば DRIFT を出す。MISSING か DRIFT が1件でもあれば exit 1。 半年運用したあと、**本番 API には現れない場所に住む値**を台帳へ載せる日が来る。 コード内の定数、管理画面にしかない項目、表計算シートの列などだ。 その時、担当者（または AI）は親切心で `configPath` に**所在の説明文**を書く。 ```json "configPath": "PriceCalculator の FLOOR 定数（コード内・API には出ない）" ``` 照合器はこれを設定パスとして `split('.')` するので、**永遠に MISSING を返す**。 以後、毎日のバッチは必ず exit 1 で終わり、レポートの冒頭と通知が毎朝 「🚨 前提が崩れています」で始まるようになる。 ## なぜ致命的か 1. **本物のドリフトが埋もれる。** 毎朝赤いので、誰も赤を見なくなる。 照合器は「値が勝手に変わったこと」を捕まえるために作ったのに、その用を成さなくなる。 2. **原因の表示が嘘に見える。** 出るのは「台帳と実設定が一致しない」。 実際には**設定は正しく、壊れているのは台帳の書き方だけ**。読んだ人は本番設定を疑って時間を溶かす。 3. **見つかるのが遅れる。** 常駐ジョブが固定の版（ミラーやコンテナイメージ）で走っていると、 台帳の更新が反映されず**何日も隠れる**。版を揃えた瞬間に初めて出る。 ## 直し方（設計） 照合器に「照合対象外」の第3の状態を持たせ、台帳の書式でそれを表現できるようにする。 - `configPath: null` → **DOC**（記録専用。機械照合しない。緑扱い） - `configPath: "a.b.c"` → 設定 API を辿って OK / DRIFT / MISSING - **所在の説明は別キー**（`location`）に書く。`configPath` には自由文を一切入れない 多くの実装は既に「null なら飛ばす」を持っている。持っているのに使われないのは、 **書式の契約が台帳ファイル自身に書かれていない**からなので、台帳の先頭 `rules` 配列にも1行入れる。 ``` "configPath には設定 API のドット区切りパスだけを書く。API に現れない値は configPath を null にし、 所在は location に書く。説明文を configPath に入れると照合器が MISSING を返し毎朝 exit 1 になる" ``` ## 直し方（guard・ここが本題） 契約を文章で書いても次の人は破る。**機械で止める**。 ```js // 設定 API の戻りを辿れる形だけ許す const DOTTED_PATH = /^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)*$/; test('configPath は null か設定 API のドット区切りパスだけ（説明文を書かない）', () => { const bad = Object.entries(ledger.parameters) .filter(([, e]) => e.configPath !== null && !DOTTED_PATH.test(String(e.configPath))) .map(([k, e]) => `${k}: ${JSON.stringify(e.configPath)}`); assert.deepEqual(bad, []); }); test('configPath が null の項目は所在を location か sheetCell に持つ', () => { const bad = Object.entries(ledger.parameters) .filter(([, e]) => e.configPath === null) .filter(([, e]) => !e.location?.trim() && !e.sheetCell?.trim()) .map(([k]) => k); // 既存の未記入分は許容し、新しく増えないことだけを守る const KNOWN = ['legacyEntryName']; assert.deepEqual(bad.filter(k => !KNOWN.includes(k)), []); }); ``` **guard は必ず「落ちる側」で先に検定する。** 読み込む台帳のパスを環境変数で差し替えられるようにしておき、 ```js const LEDGER_PATH = process.env.LEDGER_PATH || path.join(HERE, '..', 'config', 'decisions.json'); ``` 1. **修正前の台帳**に当てて **fail すること**（何件・どの項目を検出したかまで見る） 2. 修正後の台帳で **pass すること** の順で確かめる。この順を守らないと、「常に通る空の検査」を追加して満足する事故が起きる。 `assert.deepEqual(bad, [])` は対象が0件でも通るので、**通ったことは検知できることの証拠にならない**。 ## 直すときにやってはいけないこと - **値を一緒に直さない。** これは書式の修正であって、判断の変更ではない。 `current` / `history` / 根拠文は1文字も変えず、機械比較で差分ゼロを確認してからコミットする。 ```js // 修正前後の台帳を突き合わせて「値は動いていない」を証明する for (const k of Object.keys(next.parameters)) { const a = next.parameters[k], b = prev.parameters[k]; if (JSON.stringify(a.current) !== JSON.stringify(b.current)) diff.push(k); if (JSON.stringify(a.history) !== JSON.stringify(b.history)) diff.push(k + ' history'); } ``` - **照合器の側を緩めない。** 「MISSING を警告どまりにする」で赤は消えるが、本物のドリフトも消える。 直すのはデータの書式であって検出器の感度ではない。 ## 検収（この順で確かめる） 1. 修正した台帳で照合器を実走 → exit 0 / MISSING 0 / DRIFT 0 2. guard を旧台帳に当てて fail → 新台帳で pass 3. テスト全体が緑 4. **常駐ジョブが実際に読む場所**（ミラー・コンテナ・デプロイ先）を新しい版に揃えてから、そこで照合器を実走 → exit 0 手元のリポジトリで通っても、常駐ジョブが古い版を読んでいれば翌朝また赤くなる ## 横に効く教訓 - 「毎朝赤い」は**壊れている**のではなく**検出器が死んでいる**。赤を見なくなった時点で仕組みが無効になっている - 自由文と機械が辿る値を**同じキーに同居させない**。同居させた瞬間、片方が必ず壊れる - 常駐ジョブが固定版を読む構成では、**台帳の不良は版を揃えた日に初めて出る**。 「今まで出ていなかった」は「無かった」ではない ---