👻 「Plugin directory does not exist」を自動修復するスクリプト設計

月10万の大学生から掛け持ちで月60万、会社都合の解雇でゼロ、半年でClaude Code自律環境を建て直して今は月商120万。その環境を支えるスクリプトを一本ずつ解剖していきます。

なぜこの仕組みが効くのか

Claude Codeを本格的に使い込んでいると、ある日突然、起動時にこんなエラーが出るようになります。

Plugin directory does not exist: ~/.claude/plugins/cache/marketplace/plugin-name

焦って ~/.claude/settings.json を覗いてみると、enabledPlugins にはちゃんと true が並んでいます。設定上は「有効」なのに、対応するキャッシュディレクトリが物理的に存在しない。これが「幽霊エントリ」問題です。

なぜ幽霊エントリが生まれるか

原因は複数あります。一番多いのは、プラグインを手動で無効化したとき（あるいは無効化スクリプトが走ったとき）にキャッシュディレクトリだけ退避・削除され、settings.json 上のフラグが true のまま残るケースです。Claude Codeのプラグインキャッシュは ~/.claude/plugins/cache/<marketplace>/<plugin-name>/ という2段ディレクトリ構造を取っていますが、この「実体」と「設定ファイルのエントリ」は独立して管理されています。設定とキャッシュのどちらかだけが変更されると、両者がズレます。

もう一つは、OS移行やバックアップからの復元です。設定ファイルは .dotfiles で管理しているのにキャッシュは対象外、というケースで同様のズレが起きます。自分の環境でも、macOSを移行したときに一気に7〜8本の幽霊エントリが生まれました。

「作業」ではなく「環境」を直す

この問題が厄介なのは、発生が散発的で再現性が低い点です。毎日使っていても気づかない日もあれば、プラグインが必要なタスクを始めた瞬間にエラーで止まる日もある。そして手動で直すとなれば、settings.json を開いてどのキーが問題なのかを目で確認し、対応するエントリを書き換える。プラグインが10本以上あれば一つ一つ確認するだけで数分消えます。

ここで大事なのは、これが「作業の問題」ではなく「環境の問題」だということです。Claude Codeが出すエラーを毎回手で直しているうちは、自分が環境の管理者ではなく環境の消耗品になっています。自動化で仕組みとして解決することで、同じ問題が何十回起きても対処コストがゼロになります。

2段フォールバックという設計

単純に「幽霊エントリを見つけたら false に倒す」だけでは情報が失われます。キャッシュが消えているだけで、別の場所（.disabled-cache/）にコピーが残っていれば復元できる可能性があるからです。

plugin-cache-repair.sh は「復元できるものは復元し、復元できないものだけ無効化する」という2段フォールバックを取っています。この区別が、修復後にプラグインをすぐ使える状態に戻せるかどうかを左右します。

さらに、いきなり設定を書き換えるのではなく、dry（確認のみ）とapply（実行）の2段階を分けることで、副作用をゼロに近づけています。自動化スクリプトが自分の知らないところで何かを変更していた、という状況は生産環境でも個人の開発環境でも同様に怖い。dryランで「これから何をするか」を表示させ、確認してからapplyする設計は、信頼できる自動化の基本です。

全体の流れ

スクリプトの処理は4フェーズに分かれています。

settings.json
enabledPlugins: { "plugin-name@marketplace": true, ... }
        │
        ▼
【フェーズ1: 検出】
Python で enabledPlugins:true のキーを抽出
        │
        ▼
【フェーズ2: 分類】
各キーについて cache/<marketplace>/<name>/ の存在確認
        │
        ├─ 存在する  → OK（スキップ）
        └─ 存在しない → MISSING
                        │
                        ├─ .disabled-cache/<name>/ あり → RESTORE候補
                        └─ .disabled-cache/<name>/ なし → FLIP候補
        │
        ▼
【フェーズ3: dry表示】
OK/RESTORE/FLIP の件数と詳細を標準出力
        │
        ▼（applyモードのとき）
【フェーズ4: apply実行】
1) RESTORE: cp -R .disabled-cache/<name>/ → cache/<market>/<name>/
2) FLIP: python3 で settings.json の該当キーを false に書き換え
        │
        ▼
verify: スクリプト自身を dry モードで再実行（全件OKなら修復完了）

フェーズ1：Python による JSON パース

settings.json の読み取りに jq を使わず python3 を選んでいるのは、bash 3.2 互換を保ちながら外部コマンド依存を最小にするためです。コメントにも bash 3.2 互換（mapfile / 連想配列を使わない） と明記されています。

ENABLED_KEYS=$(python3 - "$SETTINGS" <<'PY'
import json, sys
with open(sys.argv[1]) as f:
    s = json.load(f)
for k, v in (s.get('enabledPlugins') or {}).items():
    if v is True and '@' in k:
        print(k)
PY
)

enabledPlugins キーが存在しない場合も or {} で安全に空dictに落ちます。'@' in k の条件は plugin-name@marketplace という形式を前提に、不正なエントリを暗黙でスキップするガードです。結果は改行区切りの文字列として ENABLED_KEYS に入ります。

フェーズ2：分類ループ

抽出したキーを一本ずつ処理して、RESTORE_LIST と FLIP_LIST の2本のリストに振り分けます。

while IFS= read -r KEY; do
  [ -z "$KEY" ] && continue
  NAME="${KEY%@*}"
  MARKET="${KEY#*@}"
  EXPECTED="$CACHE_DIR/$MARKET/$NAME"
  if [ -d "$EXPECTED" ]; then
    OK_COUNT=$((OK_COUNT + 1))
    continue
  fi
  MISSING_COUNT=$((MISSING_COUNT + 1))
  if [ -d "$DISABLED_DIR/$NAME" ]; then
    RESTORE_LIST="${RESTORE_LIST}${KEY}|${NAME}|${MARKET}
"
  else
    FLIP_LIST="${FLIP_LIST}${KEY}
"
  fi
done <<EOF
$ENABLED_KEYS
EOF

${KEY%@*} でプラグイン名、${KEY#*@} でマーケットプレイス名を分割するシェル展開は、bash組み込みだけで動く点が重要です。キャッシュの期待パスは $CACHE_DIR/$MARKET/$NAME となり、-d でディレクトリとして存在するかを確認します。存在しなかった場合、.disabled-cache/$NAME を次に確認します。マーケットプレイス名はここではチェックしない——.disabled-cache はマーケットプレイスを問わずプラグイン名だけで格納される設計だからです。

連想配列を使わず RESTORE_LIST をパイプ区切りの改行文字列として積み上げているのも、bash 3.2 制約への対応です。

フェーズ3：dry 表示

apply を渡さない限り（あるいはデフォルトの dry で実行した場合）、スクリプトは何も変更せず集計結果だけを表示します。

=== plugin-cache-repair (dry) ===
enabled(true) total : 14
cache present       : 11
cache missing       : 3
  -> restorable     : 2  (will cp from .disabled-cache)
  -> flip to false  : 1   (no copy available)

この出力だけで「3本ズレている・うち2本は復元可能・1本は無効化するしかない」という状況が一目で分かります。副作用ゼロで現状把握できるのがdryモードの価値です。apply前にかならずこの出力を確認するのが正しい使い方です。

フェーズ4：apply 実行

applyモードでは最初に settings.json のバックアップを取ります。

TS=$(date +%Y%m%d-%H%M%S)
BACKUP="$BACKUP_DIR/settings.json.before-plugin-cache-repair-$TS"
cp "$SETTINGS" "$BACKUP"

タイムスタンプを含むバックアップ名にすることで、複数回実行しても上書きされません。~/.claude/backups/ に積み上がっていきます。

復元処理（RESTORE）

SRC="$DISABLED_DIR/$N"
DST_PARENT="$CACHE_DIR/$M"
DST="$DST_PARENT/$N"
if [ "$SRC" = "$DST" ]; then
  echo "  SKIP (src==dst): $K"
  continue
fi
if [ -e "$DST" ]; then
  echo "  SKIP (already exists): $DST"
  continue
fi
mkdir -p "$DST_PARENT"
if cp -R "$SRC" "$DST" 2>/dev/null; then
  echo "  RESTORED: $K"

コメントに 既存 cache は絶対に上書きしない（src/dst 重複確認） とある通り、src=dst の一致チェックと -e "$DST" の事前確認で二重ガードをかけています。キャッシュが壊れていて空ディレクトリだけ残っているケースで上書きが起きないようにするためです。

無効化処理（FLIP）

復元できなかったエントリは Python で settings.json を書き換えます。

echo "$FLIP_LIST" | python3 - "$SETTINGS" <<'PY'
import json, sys
settings_path = sys.argv[1]
flips = [line.strip() for line in sys.stdin if line.strip()]
with open(settings_path) as f:
    s = json.load(f)
ep = s.setdefault('enabledPlugins', {})
flipped = 0
for k in flips:
    if ep.get(k) is True:
        ep[k] = False
        flipped += 1
        print(f"  FLIPPED: {k}")
with open(settings_path, 'w') as f:
    json.dump(s, f, indent=2, ensure_ascii=False)
    f.write('\n')
print(f"flipped total: {flipped}")
PY

ep.get(k) is True の is True 比較は意図的です。None や文字列が混入していたときに誤って書き換えないための厳密チェックです。書き込み時に indent=2 と末尾改行（f.write('\n')）を付けることで、既存の settings.json のフォーマットを崩さないようにしています。

修復後の検証コマンド

applyが終わると、スクリプトの最後にこの一行が出力されます。

echo "verify with:  $0 dry"

修復直後に自分自身をdryモードで再実行することを促しています。cache missing: 0 が表示されれば修復完了。cache missing がまだ残っていれば何らかの異常があった（cp権限エラー・パスの不一致など）と判断できます。修復スクリプトが「検証コマンドまでセットで提示する」設計になっているのは、「apply後に自分で確認する手順を人間が忘れる」という実運用の経験からきています。

実装の詳細

plugin-disable.sh が持つ3層の防御

plugin-cache-repair.sh が「キャッシュと設定のズレを直す」スクリプトなら、plugin-disable.sh は「意図してプラグインを無効化する」スクリプトです。この2本がセットになっています。repairがpassiveな修復ツールなのに対し、disableはactiveに設定を書き換えるため、誤爆時の影響が直接的です。そこでdisableのほうには明示的な防御レイヤーが3枚重ねで入っています。

第1層：空文字・短すぎる引数を弾く

# DEFENSE: skip empty plugin names (otherwise startswith("") matches ALL)
[ -z "$p" ] && { echo "  (skipped empty arg)"; continue; }
# DEFENSE: require at least 3 chars to avoid accidental wildcard
[ ${#p} -lt 3 ] && { echo "  (skipped too-short: '$p')"; continue; }

コメントが全てを物語っています。startswith("") はjqの仕様上、全てのキーにマッチします。空文字を渡すだけで enabledPlugins の全エントリが無効化されます。これを空文字チェックと3文字最低ルールで塞いでいます。「3文字」という数字は恣意的に見えますが、自分の環境で最短のプラグイン名が4文字だった実測値から決めています。

第2層：完全一致を優先し、前方一致は単一ヒット時のみ許可

EXACT=$(jq -r --arg p "$p" \
  '.enabledPlugins // {} | keys[] | select(. | split("@")[0] == $p)' "$TMP")
if [ -n "$EXACT" ]; then
  KEYS="$EXACT"
else
  KEYS=$(jq -r --arg p "$p" \
    '.enabledPlugins // {} | keys[] | select(startswith($p))' "$TMP")
  HIT_COUNT=$(echo "$KEYS" | grep -c .)
  if [ "$HIT_COUNT" -gt 1 ]; then
    echo "  ⚠ '$p' matches $HIT_COUNT entries via prefix (no exact match found):"
    echo "$KEYS" | sed 's/^/      /'
    echo "    → use exact plugin name to be safe. SKIPPING."
    continue
  fi
fi

キーの形式は plugin-name@marketplace なので、完全一致は split("@")[0] == $p でプラグイン名部分だけを比較します。前方一致はフォールバックとして残しているのは、Claude Codeのバージョンによってmarketplace名がたまに変わるケースへの対応です。ただし前方一致が2件以上ヒットした場合は「ambiguous」として必ずSKIPし、ユーザーに正確な名前での再実行を促します。前方一致で複数を一気に無効化するのは設計として許可しない、という判断です。

第3層：50%ガード

ORIG_COUNT=$(jq -r '.enabledPlugins // {} | length' "$SETTINGS")
NEW_COUNT=$(jq -r '.enabledPlugins // {} | length' "$TMP")
if [ "$NEW_COUNT" -lt $((ORIG_COUNT / 2)) ]; then
  echo "REFUSED: would disable >50% of plugins ($ORIG_COUNT -> $NEW_COUNT). Aborting."
  rm -f "$TMP"
  exit 1
fi

処理後のエントリ数が元の半数を下回ったら書き込みを拒否します。削除の単位はjqによる del(.enabledPlugins[$k]) なので、誤ったキーが複数マッチしたときに一気に消える可能性があります。それを最終的に「半数以上が消えるのはおかしい」という量的チェックで捕まえます。

バックアップ世代管理

ls -1t "$BACKUP_DIR"/settings.json.before-plugin-disable-* 2>/dev/null \
  | tail -n +6 | while IFS= read -r old; do rm -f "$old"; done

ls -1t でタイムスタンプ降順に並べ、6番目以降を削除することで直近5世代だけ保持します。~/.claude/backups/ はrepairとdisableの両方がバックアップを積むディレクトリなので、世代制限なしで運用すると数週間で数十個に膨らみます。5世代あれば1週間分の変更は復元できます。

from-auditモードと自動化パイプラインへの接続

plugin-disable.sh には from-audit というモードがあります。

extract_dormant() {
  awk '/^## Dormant/{flag=1; next} /^## /{flag=0} flag && /^[a-z]/' "$AUDIT" \
    | sed 's/```//' | grep -v '^$' | head -100
}

~/.claude/scripts/plugin-audit-latest.md という監査レポートの ## Dormant Plugins セクションを awk でパースし、休眠中のプラグイン名を抽出します。/^## Dormant/{flag=1} でセクション開始を検知、/^## /{flag=0} で次のセクション開始を検知してフラグを落とす。シンプルですが正確に動きます。

さらに PROTECTED_FILE を使って「休眠に見えるが意図的に常設しているプラグイン」を除外します。

PROTECTED_FILE="$HOME/.claude/scripts/lib/protected-plugins.txt"
if [ -f "$PROTECTED_FILE" ]; then
  PLUGINS=$(extract_dormant | grep -vxF -f "$PROTECTED_FILE" || true)
fi

grep -vxF -f は「ファイルに書いたパターンと完全一致する行を除外」する形式です。LSP系やプロセス管理系のプラグインは使用頻度が低くても常に有効にしておく必要があり、監査レポートでは「休眠」と判定されてしまいます。この除外リストがあることで、from-auditの一括無効化が意図したものだけに絞られます。

launchdで毎週日曜6:45に自動化する

com.shun.plugin-auto-disable.plist がこの自動化の起点です。

<key>StartCalendarInterval</key>
<dict>
    <key>Hour</key>
    <integer>6</integer>
    <key>Minute</key>
    <integer>45</integer>
    <key>Weekday</key>
    <integer>0</integer>
</dict>

macOSのlaunchdでは Weekday=0 が日曜日です。毎週日曜の朝6時45分、起床前に自動実行されます。

<key>LowPriorityIO</key>
<true/>
<key>Nice</key>
<integer>10</integer>
<key>ProcessType</key>
<string>Background</string>

LowPriorityIO=true と Nice=10 と ProcessType=Background の3つが揃っています。ディスクIOの優先度を下げ、CPUスケジューリングの優先度を下げ、プロセス種別をバックグラウンドにする。この設定にしておくと、仮に朝6:45に起きてMacを触っていても処理に気づかないくらい静かに動きます。自動化スクリプトが作業を妨げてはいけない、という考え方です。

実行内容はシンプルです。

<string>~/.claude/scripts/plugin-auto-disable.sh apply &gt;&gt;
    ~/.claude/logs/plugin-auto-disable.log 2&gt;&amp;1</string>

ログは ~/.claude/logs/plugin-auto-disable.log に追記されます。週次で実行されるため、ログが肥大化しないよう plugin-auto-disable.sh 側でログローテーションを別途設けています。

---

私が詰まった話

その1：set -uo pipefail と grep -c . の死闘

最初に書いたバージョンの分類ループは、RESTOREとFLIPのカウントをこう取っていました。

RESTORE_COUNT=$(printf '%s' "$RESTORE_LIST" | grep -c .)
FLIP_COUNT=$(printf '%s' "$FLIP_LIST" | grep -c .)

ローカルでテストしている間は問題ありませんでした。実際に全プラグインが正常な（MISSINGがゼロの）環境で走らせた瞬間、スクリプトが途中で止まりました。

症状：RESTORE_LIST が空文字のとき、printf '%s' "" | grep -c . はマッチがゼロなので終了コード1を返します。set -uo pipefail 環境では、パイプラインの最後のコマンドの終了コードが1だとスクリプト全体がそこで止まります。全件OKのはずが、exit code 1で異常終了していたわけです。

原因に気づくまで30分かかりました。なぜなら手元でテストするときは必ずMISSINGが1件以上あったからです。完全にクリーンな状態をわざわざ作らないとこのパスは通らない。

修正はシンプルで、|| true を末尾に足すだけです。

RESTORE_COUNT=$(printf '%s' "$RESTORE_LIST" | grep -c . || true)
FLIP_COUNT=$(printf '%s' "$FLIP_LIST" | grep -c . || true)

|| true を付けることでgrep終了コード1をシェルが無視し、スクリプトは継続します。こういうケースを踏んだ後から、「空入力のgrep -c」を使うときは必ずセットで書くようにしています。

その2：macOSデフォルトbashで連想配列が使えない

初稿では RESTORE_MAP を連想配列で実装していました。

declare -A RESTORE_MAP
RESTORE_MAP["$NAME"]="$MARKET"

手元では問題なく動いていました。しかし「スクリプトを /bin/bash で明示実行したら動かない」というパターンに後で気づきました。macOSに入っているデフォルトの /bin/bash はバージョン3.2です。連想配列（declare -A）は bash 4.0 以降の機能なので、shebangを #!/usr/bin/env bash にしていても、環境によっては 3.2 が拾われます。

homebrew で入れた bash 5.x が PATH の前に来ている環境では動きますが、そうでない環境では declare: -A: invalid option で即死します。

これを踏んでからコメントに明記しました。

# bash 3.2 互換（mapfile / 連想配列を使わない）

代替実装として採用したのがパイプ区切りの改行文字列です。

RESTORE_LIST="${RESTORE_LIST}${KEY}|${NAME}|${MARKET}
"

読み出すときは IFS='|' read -r K N M で分割します。連想配列より一見トリッキーですが、bash 3.2でも動くし、外部コマンドを増やさないという点でシェルスクリプトの理想に近いです。この制約を自分に課したことで、スクリプトの動作環境が一つ広がりました。

その3：settings.json がgitで巨大な差分になる

applyモードで settings.json を書き換えたとき、最初は json.dump をオプションなしで呼んでいました。

with open(settings_path, 'w') as f:
    json.dump(s, f)

json.dump のデフォルト出力は1行に全て詰め込んだミニファイ形式です。元々の settings.json がインデント2のフォーマットで書かれていた場合、1エントリを false に変えただけで git diff が数百行に膨らみます。Claude Code自身もsettings.jsonを読み書きするので、次回Claude Codeが保存した時点でまたフォーマットが変わる。差分が意味を成さなくなります。

さらに、末尾改行がないと一部のエディタやgitツールが「ファイルの末尾に改行がない」警告を出し続けます。

修正は2点です。

json.dump(s, f, indent=2, ensure_ascii=False)
f.write('\n')

indent=2 で元のフォーマットに合わせ、ensure_ascii=False で日本語プラグイン名がUnicodeエスケープに化けないようにします。f.write('\n') で末尾改行を保証します。この3行を揃えて初めて「1エントリ変えると1行だけ差分が出る」という状態になります。

その4：50%ガードが正当なバッチ操作を止めた

from-audit apply を初めて本番環境で走らせたとき、こんなメッセージが出てスクリプトが止まりました。

REFUSED: would disable >50% of plugins (22 -> 8). Aborting.

22本のうち14本が休眠判定されていました。確かに半数以上です。でも実態として14本を一気に無効化したかったのに、ガードが正当な操作を止めてしまいました。

原因は protected-plugins.txt の更新漏れです。監査レポートが出た後、新しいLSP系プラグイン2本を導入していたのに保護リストに追記し忘れていました。その2本が「休眠（実際は意図的常設）」として無効化対象に含まれ、合計14本になっていた。

対処は2段階でした。まず protected-plugins.txt に2本を追記してから from-audit dry で件数を確認、9本に減ったことを確認してから from-audit apply を再実行。今度はREFUSEDが出ずに通りました。

この経験から「監査を走らせる前に保護リストを最新化する」というルーティンを launchd の前段に置くようにしています。どのプラグインを保護対象にするかは数週間に一度レビューするものなので、自動化の中に人間のレビューポイントを挟んでおく設計が正解でした。

その5：修復後dryランを忘れてエラーが残り続けた

apply を走らせてすぐ Claude Code を再起動したとき、まだ同じエラーが出ることがありました。

Plugin directory does not exist: ~/.claude/plugins/cache/marketplace/plugin-name

dryランで確認しなかったのが原因でした。cp -R が権限エラーで静かに失敗していた（2>/dev/null で隠していた）のに、ログを見ていなかったため気づかなかったのです。

スクリプトが最後に出力する一行の重さを改めて実感しました。

echo "verify with:  $0 dry"

applyが「終了した」ことと「意図した通りに完了した」ことは別です。修復後にdryを走らせて cache missing: 0 を確認することが、完了の定義になります。この検証コマンドをスクリプト自身が提示するのは、「verify を人間が忘れる」という経験から来ています。自動化を信頼しすぎず、確認コマンドまで一式として提供することが、自律環境を健全に保つための現実的な設計です。

つまずきポイント

前段で書いた5つの詰まりとは別に、このスクリプト群を実際に手元で動かそうとしたときに追加でハマった箇所をまとめます。「コードは読んだ、動かしたら死んだ」というパターンのほぼ全てがここに集約されています。

• launchdがnvmを知らない問題。 .plist の EnvironmentVariables に PATH を明示しないと、launchdが起動するシェルは /usr/bin と /bin しか見ません。nvm管理下の node や homebrew 経由の bash は全滅です。実際の plist には .nvm/versions/node/v24.13.0/bin:/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin という完全PATHが直書きされていますが、これを省略すると command not found が ~/.claude/logs/com.shun.plugin-auto-disable.log に積まれ続けます。ログを確認する習慣がなければ「毎週自動で動いているはず」と思いながら何ヶ月も何もしていない状態が続きます。

• .disabled-cache にマーケットプレイス名がない設計の盲点。 repairスクリプトは .disabled-cache/$NAME で探しますが、cache 側は $CACHE_DIR/$MARKET/$NAME という2段構造です。もし同名のプラグインが異なるマーケットプレイスに存在した場合、.disabled-cache には最後に退避されたものだけが残り、別マーケットの同名エントリに誤って復元されます。現実的にはほぼ起きませんが、マーケットプレイスをまたいで実験的なプラグインを試している環境では意識しておく必要があります。

• cp -R の 2>/dev/null が失敗を隠すトレードオフ。 コードには if cp -R "$SRC" "$DST" 2>/dev/null; then echo " RESTORED: $K"; else echo " FAIL: $K (cp failed)"; fi とあります。FAIL のメッセージは標準出力に出ますが、なぜ失敗したかの詳細（権限エラーなのかパスの問題なのか）は 2>/dev/null で捨てています。デバッグ中は一時的に 2>/dev/null を外して実行すると原因が即座に分かります。本番運用では静かに失敗するほうが後続処理を止めないので正解ですが、修復後 dry ランで FAIL が見えたときの調査手順として覚えておく必要があります。

• repair 側のバックアップに世代管理がない。 plugin-disable.sh は ls -1t | tail -n +6 で直近5世代だけ保持しますが、plugin-cache-repair.sh 側のバックアップ削除ロジックはコードに存在しません。apply を走らせるたびに settings.json.before-plugin-cache-repair-YYYYMMDD-HHMMSS が ~/.claude/backups/ に積み上がります。週次で自動化しているなら年間52個。複数環境で使っていると数百個になります。定期的に手動で掃除するか、ls -1t "$BACKUP_DIR"/settings.json.before-plugin-cache-repair-* | tail -n +6 | xargs rm -f を repair 側にも足しておくのが現実的な運用です。

• Python3 のヒアドキュメント構文が zsh 直接実行で死ぬ。 plugin-cache-repair.sh は shebang に #!/usr/bin/env bash を使い、python3 - "$SETTINGS" <<'PY' という bash のヒアドキュメント形式で Python を呼び出しています。bash 経由では問題ありませんが、スクリプトの中身を切り出して zsh のプロンプトに直接貼り付けると構文エラーになります。デバッグ時はスクリプト全体を bash script.sh dry で呼ぶ、あるいは Python 部分だけを別ファイルに切り出して呼ぶのが安全です。

• Claude Code 起動中に apply を走らせると競合する。 settings.json はClaude Code本体も起動時・設定変更時に読み書きします。apply モードでスクリプトが json.dump で書き込んでいる最中に Claude Code が同じファイルを書き換えると、後勝ちで一方の変更が消えます。スクリプト内にロック機構はありません。repair や disable の apply は Claude Code を終了した状態で走らせるのが原則です。launchd の週次自動実行を日曜 6:45 にしているのは「Claude Codeを使っていない時間帯」という意図が含まれています。

• from-audit の awk パターンが小文字始まりにしか対応しない。 extract_dormant 関数の最終パターンは /^[a-z]/ です。## Dormant セクション内でプラグイン名が大文字で始まる場合（例：LSP-server）はマッチしません。今の環境では全プラグイン名が小文字始まりなので実害はありませんが、マーケットプレイスによっては大文字プラグインが混在します。自分の環境に大文字始まりのプラグインがあるなら /^[a-zA-Z]/ に変更する必要があります。

• launchctl load を忘れる。 .plist を ~/Library/LaunchAgents/ に置いただけでは動きません。launchctl load ~/Library/LaunchAgents/com.shun.plugin-auto-disable.plist が必要です。置いた直後から「毎週動いているはず」と信じて数ヶ月後にログを見たら一度も走っていなかった、という経験が一度あります。配置後は launchctl list | grep plugin-auto-disable で PID 欄を確認するのが最初の検証手順です。

• set -u と shift || true の組み合わせ。 plugin-disable.sh の冒頭に MODE="${1:-}"; shift || true という行があります。set -uo pipefail 環境で shift を引数なしで呼ぶと終了コード1になるため || true が必要です。これを知らずにスクリプトをコピーして改変し、shift || true を shift に変えると引数なし実行で即死します。set -u と set -e（pipefailを含む）を使っているスクリプトでは、終了コード1を返しうる全ての組み込みコマンドにこの考え方が必要です。

• protected-plugins.txt と監査レポートのタイミングずれ。 from-audit apply は監査レポートと保護リストの「両方が最新」であることを前提にします。監査を走らせた後に新しいプラグインを導入し、保護リストに追加するのを忘れると、次の from-audit で意図しない無効化が起きます。50%ガードがあるので壊滅はしませんが、手動でリストアする作業が発生します。監査→保護リスト確認→from-audit dry で件数チェック→from-audit apply という順序を崩さないことが運用上の鉄則です。

---

ベストプラクティス

この仕組みを半年以上運用して、「これを最初から知っていれば詰まらなかった」と思うことを整理しました。

1. dry をデフォルトにし、apply は明示引数でしか動かないようにする。
MODE="${1:-dry}" というデフォルト設定がrepairスクリプトにあります。引数を渡し忘れた実行が副作用を出さないことが、信頼できる自動化スクリプトの最低条件です。apply フラグを引数で明示させる設計は全ての自動化スクリプトに適用してください。

2. バックアップはタイムスタンプ付き、ファイル名に何をしたかを含める。
settings.json.before-plugin-cache-repair-20260120-064523 という命名規則には「日時」と「何の操作の前か」の両方が入っています。これにより ls -lt で時系列に並べたときに「どの操作で何が変わったか」が一目で分かります。backup.json のような汎用名は複数操作が混在したときに区別できなくなります。

3. bash 3.2 互換を基準に書くと環境依存を一つ削れる。
declare -A（連想配列）、mapfile、<<<（ヒアストリング） は bash 4.0 以降の機能です。macOS のデフォルト /bin/bash は 3.2 であり、homebrew で bash 5.x を入れていても shebang や PATH の順序によっては 3.2 が拾われます。最初から 3.2 の制約で書いておくと「特定の環境でだけ動かない」という類のバグが発生しません。

4. 外部コマンド依存より python3 のほうが安定する。
jq は多くの環境にありますが、インストールが必要な外部ツールです。python3 は macOS 11 以降ならプリインストールされています。repairスクリプトが jq ではなく python3 で JSON を操作しているのはこの判断からです。import json, sys の2行だけで外部依存がゼロになります。ただし disable スクリプトは jq の .enabledPlugins[$k] による部分削除を使っているため jq 依存が残っています。用途によって使い分けるのが現実的です。

5. set -uo pipefail を使うなら grep -c には必ず || true を添える。
空文字列を入力した grep -c . は終了コード1を返します。set -e（pipefail含む）環境でこれが起きるとスクリプト全体がそこで止まります。「ゼロ件」という正常状態を「エラー」と誤認させない設計として RESTORE_COUNT=$(printf '%s' "$RESTORE_LIST" | grep -c . || true) のパターンを徹底してください。

6. JSON の書き戻しは indent=2, ensure_ascii=False プラス末尾改行を必ずセットにする。
json.dump(s, f, indent=2, ensure_ascii=False) と f.write('\n') の3点セットを省くと、次の git diff が数百行になります。indent=2 は元のフォーマットに合わせるため、ensure_ascii=False は日本語や記号が \u エスケープに化けないため、末尾改行はエディタとgitツールの警告抑制のためです。Python で設定ファイルを書き換える全てのスクリプトにこれを入れてください。

7. is True で厳密比較し、None や文字列を誤って書き換えない。
if ep.get(k) is True: の is True は意図的な厳密比較です。== True では 1 や空でない文字列もマッチします。設定ファイルのエントリには予期しない型が混入することがあり、それを誤って false に倒してしまうのを防ぐための一行です。is True / is False を習慣にするだけでこの種のバグが根絶できます。

8. 50%ガードは「何かがおかしい」という量的シグナルとして機能する。
NEW_COUNT < ORIG_COUNT / 2 という判定は「半数以上消えるのはおかしい」という直感的な閾値です。完全な正しさより「明らかな異常を止める」ことを優先する設計です。この数字は環境に合わせて調整してください。プラグインが5本しかない環境では50%ガードが効きすぎることがあります。30本以上あれば50%は実用的な閾値です。

9. launchd の自動実行タスクには LowPriorityIO + Nice + ProcessType=Background を必ず付ける。
com.shun.plugin-auto-disable.plist には LowPriorityIO=true、Nice=10、ProcessType=Background の3つが揃っています。これを省くと、6:45に起きてMacを使っていたとき、自動タスクのディスクIOやCPUが前面の作業を妨げます。コスト的には plist に3行足すだけで、効果は「自動化が作業を邪魔しない」という信頼感です。

10. 検証コマンドを修復スクリプト自身に出力させる。
echo "verify with: $0 dry" というスクリプト末尾の一行は、apply完了後に人間が何をすべきかを明示します。「applyが終了した」と「意図通りに完了した」は別のことです。修復スクリプトが自分自身のdryコマンドを提示することで、人間が「何を確認するか」を考えなくて済みます。確認の存在を知っているよりも、次のコマンドが画面に表示されているほうが実際に確認する確率が上がります。

11. protected-plugins.txt は自動化パイプラインの唯一の「人間の介入点」として機能させる。
全自動化の中に「人間がレビューするファイル」を一つ置くことで、意図しない全消しを防ぐ緩衝材になります。grep -vxF -f "$PROTECTED_FILE" による除外は、監査の自動判定を覆す最後の砦です。このファイルを「更新が面倒な余計なもの」ではなく「自動化への信頼の根拠」として扱うことが、from-auditパイプラインを安全に運用する前提条件です。

12. launchd配置後は launchctl list で PID を即確認する。
ファイルを置いただけでは何も起きません。launchctl load ~/Library/LaunchAgents/com.shun.plugin-auto-disable.plist の後、launchctl list | grep plugin-auto-disable でエントリが出ることを確認してください。PIDが - なら「登録済み・未実行」、数字なら「現在実行中」です。エントリ自体がなければ load が失敗しています。/var/log/system.log か log stream --predicate 'subsystem == "com.apple.launchd"' でエラーを拾えます。

---

まとめ

plugin-cache-repair.sh の核心は「設定ファイルとキャッシュのズレを、情報を捨てずに直す」という方針です。単純に false に倒すだけなら5行で書けます。ただそれだと、復元できたはずのプラグインまで一律に無効化してしまう。.disabled-cache を経由した2段フォールバックによって、「復元できるものは復元し、本当に復元できないものだけ無効化する」という区別が生まれます。

dry と apply の分離は、この仕組みへの信頼をもう一段高めます。「このスクリプトは apply を渡さない限り何もしない」という保証があるから、毎朝の確認ルーティンに plugin-cache-repair.sh dry を差し込めます。副作用ゼロで現状把握し、必要なときだけ apply する。自動化スクリプトを「恐いもの」ではなく「いつでも呼べるもの」にするのはこの設計判断からきています。

plugin-disable.sh の3層防御と世代管理付きバックアップは、「意図しない一括無効化」を多段で防ぐためのものです。空文字チェック、前方一致の曖昧マッチ禁止、50%ガード——それぞれが独立したフェイルセーフとして機能するので、一つが潜り抜けても次が捕まえます。

launchd による毎週日曜 6:45 の自動実行は、この仕組みをメンテナンスフリーにします。LowPriorityIO + Nice + Background の3点セットで作業を妨げず、ログは ~/.claude/logs/com.shun.plugin-auto-disable.log に積まれ続けます。半年後に「そういえばあのスクリプト、ちゃんと動いてたか」と思ったときにログを開けば週次で実行された証跡が並んでいる——これが自律環境の感触です。

月商120万を支えているのは一つの巨大なシステムではなく、このスクリプトのような小さな仕組みが100本以上積み重なって初めて成立しています。Claude Code の起動エラーを毎回手で直している時間は、実質的にタスクの処理速度に直結します。環境の管理コストをゼロに近づけることで、生産できる量が変わります。

---

仕組みの全体像・月120万の内訳・30日手順は有料noteにまとめています。

📕 Claude Code自律環境で、実際どう稼ぐか ― 仕組み・実例・始め方・サポート

---

Lily（@bokuwalily）― 個人開発者。Claude Code で自動化基盤を組みながら、iOSアプリやWebサービスを量産しています

• 制作物・記事は bokuwalily.com にまとめています🖥️
• AIで「寝てても回る仕組み」を作って月120万にした話は noteの有料記事 に💰
• OSS: github.com/bokuwalily 🐙
• 最新情報・お問い合わせは X @bokuwalily へ🌍
• AI導入・自動化の相談と実装テンプレ7本の配布は 公式LINE から💬

皆さんの ❤️ やシェアが励みになります！