AI に壊させない「変換」の作り方 — 不変条件とリトライ閾値の設計

AI に「このファイルを圧縮して」「この形式に移行して」「重複を整理して」と頼むと、 指示どおり動いたのに情報が消えることがある。実際に踏んだ2つの失敗と、その予防策をまとめる。 どちらも特定の言語・サービスに依存しない。

---

失敗1: 不変条件が弱いと、機械的変換でも情報が黙って消える

索引ファイル（1行1エントリの一覧）が読み込み上限に近づいたので、AI に圧縮ツールを書かせた。 仕様には検証条件をこう書いた:

変換前後で *.md のリンク集合が完全一致することを assert し、壊れたら中止する

ツールは仕様どおり動き、assert も通った。しかし出力はこうなった:

- [User: 経営者プロフィール](user_role.md) [[user_device]] [[user_company]] — 4社の設立/代表/実績

リンクは1本も失われていない。だが エントリのタイトルと説明（— のあとの hook）が消え、 残った説明が別エントリのものに付いていた。索引の目的は「開かずに中身が分かること」なので、 リンクだけ残っても価値はゼロ。実装は正しく、仕様が誤っていた。

なぜ起きるか

検証条件は「壊れたら困るもの」ではなく 「機械的に書きやすいもの」 を選んでしまう。 ID・ファイル名・件数は書きやすい。一方、意味を担っているフィールド（タイトル・説明・出典・単位・注記）は 書きにくい。弱い不変条件は「検証した」という誤った安心を生むぶん、無検証より危険。

予防策

1. 人間がその出力を読むときに見るフィールドを列挙し、そのすべてに集合一致の assert を置く。 上の例なら ①リンク集合 ②タイトル集合 ③説明（hook）集合 の3つ。

function assertInvariants(before, after) {
  const sets = {
    links:  (t) => new Set(t.match(/[\w-]+\.md/g) || []),
    titles: (t) => new Set([...t.matchAll(/\[([^\]]+)\]\(/g)].map((m) => m[1])),
    hooks:  (t) => new Set([...t.matchAll(/—\s*([^／\n]+)/g)].map((m) => m[1].trim())),
  }
  for (const [name, extract] of Object.entries(sets)) {
    const a = extract(before), b = extract(after)
    const lost = [...a].filter((x) => !b.has(x))
    if (lost.length) throw new Error(`${name} が ${lost.length} 件失われた: ${lost.slice(0, 5).join(' / ')}`)
  }
}

2. 1つでも壊れたら書き換えを中止して異常終了する。「警告して続行」にしない。
3. --dry-run を先に作り、実データで目視してから --apply。上の失敗は dry-run の出力を読んで気付けた。 dry-run が無いツールは、最初の実行が本番になる。
4. バックアップを取ってから書く（<file>.bak-YYYYMMDD-HHMM）。
5. 目標（行数・サイズ）に届かないときは 勝手に内容を削らず「これ以上は機械的に畳めない」と言って正常終了する。 目標を達成させようとすると、AI は最後に必ず「削る」を選ぶ。
6. LLM に一発で全文を書き換えさせない。 機械的変換＋assert に落として、LLM は仕様を書く側に置く。 実測: 索引を LLM に一括で書き直させたとき、リンクが 161 → 57 に減っていたのに完了報告は「圧縮しました」だった。

---

失敗2: 「N回失敗で打ち切り」は試行レートに依存する

無人で回るバッチに、暴走防止の打ち切りを入れていた。

5回連続で失敗した対象は処理を止める（最終失敗から3日経過したらカウンタを捨てて再開）

これは 1晩に1回しか試行されない前提で書かれていた＝実質「5晩ダメなら止める」。

その後、走査順を「リスト先頭から時間制限まで」→「未着手・未完を優先するカーソル方式」に変えた。 すると 全対象が毎スロット試行されるようになった（1晩7スロット）。結果、 処理対象が無い（＝毎回失敗する）対象が 1晩で 5回に到達して停止した。 打ち切り自体は設計どおりでも、「一時的な失敗でも1晩で3日間止まる」のは設計意図と違う。

なぜ起きるか

閾値は「回数」で書くと読みやすいが、意味は常に 回数 ÷ 試行レート = 時間。 性能改善やスケジューリング変更はレートを変えるので、 一見無関係な変更が閾値の意味を静かに書き換える。

予防策

1. 無人リトライの打ち切りは 時間軸で数える。「失敗した異なる日付の集合」を保存し、その要素数で判定する。 同じ日の再試行はカウントしない。

const DAY_MS = 86400000, COOLDOWN_MS = 3 * DAY_MS, MAX_DAYS = 5

function dayKey(ms, tzOffsetHours) {          // ローカル日付で数える
  return new Date(ms + tzOffsetHours * 3600000).toISOString().slice(0, 10)
}

function recordFailure(prev, nowMs, tz) {     // 同日は増やさない
  const days = Array.isArray(prev.days) ? [...new Set(prev.days)]
    : (prev.lastMs ? [dayKey(prev.lastMs, tz)] : [])   // 旧形式 {n,lastMs} からの移行
  const today = dayKey(nowMs, tz)
  if (!days.includes(today)) days.push(today)
  return { days: days.slice(-10), lastMs: nowMs }
}

function shouldSkip(state, nowMs) {           // 期限切れを必ず入れる
  const distinct = new Set(state.days || []).size || Number(state.n) || 0
  return distinct >= MAX_DAYS && state.lastMs > 0 && nowMs - state.lastMs < COOLDOWN_MS
}

2. 打ち切りには必ず期限切れを入れる。 永久停止は「静かに対象が消える」事故になる。 ただし打ち切り自体は消さない（外部APIを叩き続けてアカウントが凍結された実例がある）。
3. 既存データの移行を忘れない。 旧形式（{n, lastMs}）も読めるようにし、 移行前に貯まったカウンタはクールダウンで自然回復させる。回復までの日数を運用メモに書く。
4. スケジューリングや走査順を変えるレビューでは 「この変更で試行レートが何倍になるか」 を1行で確認し、 倍率が変わるなら回数で書かれた全ての閾値・クォータ・上限を洗い出す。
5. 変更後はカウンタの実物を読む。回数 / 停止中か / 最終失敗時刻 を見る。 カウンタが残っている = その試行は成功していない（成功時に削除する実装なら）。

---

共通の教訓

• assert は「壊れたら困るもの」に掛ける。書きやすいものに掛けると、検証した気になるだけ。
• 閾値は単位を疑う。 回数・バイト・件数で書かれた条件は、レートやサイズ分布が変わると意味が変わる。
• AI に実装を任せるほど、仕様の穴がそのまま出力の穴になる。実装のレビューだけでなく 「この仕様で守りたいものが全部守れるか」を先に読み返す。
• 直したあとは実データで1回動かして目で見る。テストが緑でも、仕様が誤っていれば緑になる。