コードの既定を直したのに挙動が変わらない — 設定ファイルの env 注入を疑う

この指示書が解く問題

CLI エージェント（Claude Code / Codex CLI 等）が起動するサブプロセスの挙動を変えようとして、

1. ソースの既定値を書き換えた
2. テストも通した
3. ユーザー環境変数も setx / export で設定した

のに 挙動がまったく変わらない。しかも「古いコピーが残っているせいだ」と誤診して、 worktree やバックアップディレクトリを延々と探し回る。

真因は多くの場合 設定ファイル（~/.claude/settings.json の env ブロック等）が 全セッションのプロセス環境へ値を注入していて、それがコードの既定より上位にある こと。 env は姿が見えないので、コードを何度直しても勝てない。

優先順位を先に確定させる

分岐の実装がこの形なら、優先順位は上から順になる。

export function pickRoute({ capability, flagTarget, env }) {
  const target = flagTarget ?? env.MYTOOL_TARGET;   // ← env が既定より先に効く
  if (target === 'a') return 'a';
  if (target === 'b') return 'b';
  return capability ? 'a' : 'b';                     // ← ここを直しても届かない
}

順位	出どころ	見え方
1	CLI フラグ (--target x)	呼び出し側に書いてあるので見つけやすい
2	設定ファイルの env 注入	見えない。ここが事故る
3	ユーザー/マシン環境変数	2 に負ける
4	コードの既定値	1〜3 が無い時だけ効く

3 が 2 に負けるのが致命的。「環境変数を設定したから直った」と報告すると嘘になる。

診断手順（この順で機械的にやる）

1. まず「いまのプロセスの実効値」を読む

設定した値ではなく 走っているプロセスが持っている値 を見る。3つのスコープを並べて比較する。

# Windows
"USER:    " + [Environment]::GetEnvironmentVariable('MYTOOL_TARGET','User')
"MACHINE: " + [Environment]::GetEnvironmentVariable('MYTOOL_TARGET','Machine')
"PROCESS: " + $env:MYTOOL_TARGET

# macOS / Linux
echo "shell:   $MYTOOL_TARGET"
tr '\0' '\n' < /proc/<pid>/environ | grep MYTOOL_TARGET   # 実際に走っているプロセス

USER=期待値 なのに PROCESS=古い値 なら、その差を作っている注入元が居ると確定する。

2. 注入元を全文検索する

grep -rn "MYTOOL_TARGET" ~/.claude/settings.json ~/.claude/settings.local.json \
  ./.claude/settings*.json ~/.bashrc ~/.zshrc ~/.profile 2>/dev/null

設定ファイルの env に古い値が残っているのが典型。 その値は「昔の既定を明示していた頃の手書き」であることが多く、配布ツールは書き換えない＝自動では直らない。

3. 直したら「全コピー」を dry-run で確かめる

同じツールのコピーが複数ある環境（worktree、バックアップ、配布先ディレクトリ）では、 1本だけ試して満足しない。全部を列挙して同じ入力で流す。

for f in <パス1> <パス2> <パス3>; do
  echo "--- $f"
  MYTOOL_TARGET=<期待値> node "$f" --dry-run 2>&1 | head -3
done

全部が期待どおりの分岐を返したら、「古いコピーが残っている」説は棄却できる。 逆にここを飛ばすと、真因が env なのにコピー探しを続けることになる。

4. 結果は「実物」で確認する

ログの ok ではなく、生まれたプロセスそのものを数える。 サブプロセスがどこから起動したかは親プロセスを辿るのが確実。

# 自分の祖先を辿る（どの経路で起動されたセッションか分かる）
$p=$PID; for($i=0;$i -lt 6;$i++){
  $o=Get-CimInstance Win32_Process -Filter "ProcessId=$p" -ErrorAction SilentlyContinue
  if(-not $o){break}; '{0} {1}' -f $o.ProcessId,$o.Name; $p=$o.ParentProcessId }

# Linux / macOS
ps -o pid,ppid,comm -p $$ ; ps -o pid,ppid,comm -p $PPID

「直したはず」の調査中に、調べている自分自身が旧経路で起動していたという形で 決定的証拠が出ることがある。開始時刻の一致で推定せず、親プロセス名で数えること。

落とし穴

• フォールバックが黙って旧経路に落ちる。return capability ? 'a' : 'b' は、 capability の検出（実行ファイルの探索など）が環境依存で失敗すると、警告なしに b へ落ちる。 禁止したい経路がある場合は、フォールバックではなく 明示指定が無ければスキップしてログを出す 設計にする。
• 全体を止める非常スイッチは1つに集約する。コピーが増える前提なら、 各コピーが起動時に読む共有の状態ファイル（{"enabled": false}）を1つ持たせる。 コードを直しても古いコピーは止まらないが、共有スイッチなら全部止まる。
• 並行して同じ修正をしている作業者が居る。着手前に上流を fetch して、 同じ修正が既にマージされていないか確認する。重複していたら自分の方を捨てる。
• 設定ファイルは配布で上書きされない。手書きされた値は各端末に残り続けるので、 端末ごとに grep して回る必要がある。「配布したから全台直った」と言わない。

再発防止として残すもの

• 設定ファイルの env に 昔の既定値を明示で書かない（既定はコード側に置く）。 どうしても書くなら、コメントで「なぜ明示しているか」を残す。
• 「設定を直したのに効かない」を見たら、最初に見るのは設定ファイルの env、というチェック順を ルール/メモリに固定する。ここを最初に見るだけで、コピー探しの数時間が消える。