🧹 育てすぎた環境は腐る――週次 env-audit で Claude Code を棚卸しする

月商0円から半年で120万まで持ってきた唯一の理由は、環境を「育てる」のではなく「腐らせない」仕組みを先に作ったことです。

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

Claude Code を使い込むほど、ファイルは増えます。試しに入れた MCP サーバー、「便利そう」と思って追加したプラグイン、勢いで書いた auto-skill――どれも追加した瞬間は目的があります。問題はその後です。

MCP サーバーは認証トークンが失効していても Failed to connect のまま設定に居座り続けます。プラグインはコマンドファイルがディスク上に残っていても settings.json の enabledPlugins から消えていれば動かないまま容量を使います。auto-skill は「とりあえず書いた」手順が半年後も ~/.claude/skills/auto/ に鎮座し、Claude が毎回それを読み込もうとするコンテキスト税を払い続けます。

これは「使っていないアプリが増えても iPhone は遅くならない」という話とは全く違います。Claude Code のコンテキストウィンドウは有限で、起動時に読み込まれる設定・スキル・フック一覧の総量が直接「最初の返答品質」に影響します。50 個のプラグインが有効になっていれば、そのメタデータは毎回コンテキストに乗ります。10 個の MCP サーバーが Failed のまま残っていれば、接続試行のタイムアウトが起動を遅延させます。

私がこれを身をもって体験したのは、Claude Code を本格導入して 3 ヶ月目のことです。月商が伸びるにつれて「もっと便利に」と MCP を追加し続けた結果、ある週から Claude の初回レスポンスが明らかに鈍くなりました。調べてみると、claude mcp list の出力に Failed to connect が 7 件並んでいました。そのうち 5 件は入れた記憶すらない——プラグイン経由で自動追加されたものでした。

「壊れていることに気づかない」という状態が一番コストが高いのです。壊れたまま 3 週間使い続けた接続試行のタイムアウトは、累積で何十分もの待ち時間になります。気づいて 10 秒で直せる問題を、気づかずに放置し続けるのは純粋な損失です。

だから週次で「健康診断」を自動実行し、レポートを日付付きファイルに蓄積する仕組みを作りました。diff を取れば「どの週から MCP が壊れ始めたか」を過去に遡って確認できます。「なんか最近遅い気がする」という曖昧な感覚を、「3 週前の日曜のレポートから Failed が 3 件に増えていた」という事実に変換できるのです。

この仕組みが特に効く理由がもう一つあります。自分では気づけない腐敗は、自動化でしか検出できないという点です。毎日 Claude Code を使っていると、「なんとなく重い」という感覚は閾値が上がっていきます。3 ヶ月前より 20% 遅くなっても、それが当たり前になってしまう。週次のスナップショットがなければ比較の基準が失われます。

全体の流れ

仕組みは 2 ファイルだけです。診断スクリプトと、それを週次で起動する launchd ジョブ設定。

[毎週日曜 09:00]
        │
        ▼
launchd が com.shun.env-audit を起動
        │
        ▼
~/.claude/scripts/env-audit.sh を実行
        │
        ├─ jq で settings.json をパース
        │    └─ enabledPlugins の数を取得
        │
        ├─ find で plugin ディレクトリを走査
        │    └─ commands / SKILL.md / agents の実ファイル数
        │
        ├─ claude mcp list（timeout 25 秒）
        │    └─ Connected / Needs auth / Failed を集計
        │
        ├─ jq で hooks の構成を出力
        │
        ├─ ls ~/.claude/skills/auto/ で auto-skill 一覧
        │
        └─ ccusage blocks --active で直近コストを取得
                │
                ▼
    ~/.claude/logs/env-audit-YYYYMMDD.md に書き出し
                │
                ▼
    diff で前週比較 → 「いつ壊れたか」を遡れる

スクリプトの構造

~/.claude/scripts/env-audit.sh は 70 行です。全体は一つの {} ブロックで囲まれた Markdown 生成をファイルにリダイレクトする構造になっています。

#!/usr/bin/env bash
set -uo pipefail

OUT="${1:-/tmp/claude-env-audit.md}"
SETTINGS="$HOME/.claude/settings.json"

{
  # ... Markdown を echo で生成 ...
} > "$OUT"

引数を渡さなければ /tmp/claude-env-audit.md に出力されます。launchd から呼ぶときは日付付きパスを引数で渡します（後述）。

Plugin Inventory セクションでは、設定ファイルと実ファイルの両方をカウントします。

TOTAL=$(jq -r '.enabledPlugins // {} | length' "$SETTINGS")
echo "- Enabled plugins: **$TOTAL**"
echo "- Plugin commands on disk: **$(find $HOME/.claude/plugins -path '*/commands/*.md' 2>/dev/null | wc -l | tr -d ' ')**"
echo "- Plugin skills on disk: **$(find $HOME/.claude/plugins -name 'SKILL.md' 2>/dev/null | wc -l | tr -d ' ')**"
echo "- Plugin agents on disk: **$(find $HOME/.claude/plugins -path '*/agents/*.md' 2>/dev/null | wc -l | tr -d ' ')**"

enabledPlugins の件数とディスク上の実ファイル数の乖離が「ゾンビファイル」の指標になります。設定から外れているのにディスクに残っているプラグインは、容量こそ使いませんが整理対象です。逆に enabledPlugins に載っているのにディスクにファイルがなければ、そのプラグインは動いていません。

MCP Server Status セクションが核心です。

MCP_OUT=$(timeout 25 claude mcp list 2>&1)
TOTAL_MCP=$(printf '%s' "$MCP_OUT" | grep -cE "://|^plugin:|^claude\.ai")
OK=$(printf '%s' "$MCP_OUT" | grep -c "Connected")
AUTH=$(printf '%s' "$MCP_OUT" | grep -c "Needs auth")
FAIL=$(printf '%s' "$MCP_OUT" | grep -c "Failed to connect")

timeout 25 が重要です。MCP サーバーが無応答のとき claude mcp list 自体がハングすることがあります。25 秒のタイムアウトを設けることで、壊れたサーバーがあってもスクリプト全体が止まらない設計になっています。

集計結果は 1 行のサマリーと、Failed / Needs auth の詳細リストの両方を出力します。

echo "- Total: $TOTAL_MCP / Connected: **$OK** / Need auth: **$AUTH** / Failed: **$FAIL**"

続く Hooks セクションでは jq でイベント種別と登録数を一覧します。

jq '.hooks | to_entries | map({event: .key, count: (.value | length)})' "$SETTINGS" 2>/dev/null

フックは増えやすく、削除は怖いと感じやすいカテゴリです。「UserPromptSubmit に何個フックが刺さっているか」を週次で確認することで、意図せず重複したフックが積み重なっているのを早期に気づけます。

Auto-skills セクションはシンプルに一覧を出します。

ls "$HOME/.claude/skills/auto/" 2>/dev/null | grep -v README

私の環境では現在 ~/.claude/skills/auto/ に 20 本以上の SKILL.md が存在します。用途が終わったものを残し続けると、Claude がシステムプロンプトで読み込むコンテキストが膨らみます。週次で一覧を目視することで、「そういえばこれもう使ってないな」に気づくきっかけになります。

Cost セクションは直近の稼働ブロックのコストを引っ張ります。

ccusage blocks --active 2>&1 | grep -E "Block|Time|Tokens:|Cost:|/h" | sed 's/^/  /'

MCP の接続失敗が増えた週はリトライコストが上乗せされることがあります。MCP の状態とコストの推移を同じレポートに収めることで、「この週コストが跳ねた理由が MCP 不安定だった」という相関を後から読み取れます。

Recommendations セクションは閾値ベースの自動判定です。

[ "$FAIL" -gt 0 ] && echo "- ⚠️  $FAIL MCP servers failed. Review/disable to reduce startup time."
[ "$AUTH" -gt 5 ] && echo "- ⚠️  $AUTH MCP servers unauthenticated. Either auth or disable to reduce noise."
[ "$TOTAL" -gt 50 ] && echo "- ⚠️  $TOTAL plugins enabled - likely heavy context tax. Consider pruning unused."

閾値の根拠：FAIL > 0 はゼロトレランス（1 件でも失敗していれば要対処）。AUTH > 5 は「5 件まではプロジェクトごとに認証待ちが出うる許容範囲」という経験値。plugins > 50 は「50 件を超えると起動時のコンテキスト注入量が体感できるレベルで重くなる」という経験から設定しました。

launchd ジョブの設定

~/Library/LaunchAgents/com.shun.env-audit.plist が週次実行のトリガーです。

<key>StartCalendarInterval</key>
<dict>
    <key>Hour</key>
    <integer>9</integer>
    <key>Minute</key>
    <integer>0</integer>
    <key>Weekday</key>
    <integer>0</integer>
</dict>

Weekday の 0 が日曜です。毎週日曜 9:00 に起動します。週次での実行を日曜の朝にした理由は、月曜から使い始める前に状態を把握しておきたいからです。土日に実験的な MCP を追加して月曜に忘れる、というサイクルを何度か繰り返した後に決めました。

実行コマンドは次のように日付付きのファイル名を動的に生成しています。

<string>/bin/zsh -c ~/.claude/scripts/env-audit.sh
  ~/.claude/logs/env-audit-$(date +\%Y\%m\%d).md &gt; /dev/null 2&gt;&amp;1</string>

plist では % をエスケープして \%Y\%m\%d と書く必要があります。これを忘れると launchd が date コマンドを正しく解釈できず、ファイル名が固定文字列になってしまいます（実際に 1 回踏みました）。

プロセスの優先度設定にも注意が必要です。

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

Nice 10 でスケジューリング優先度を下げ、LowPriorityIO で I/O も低優先にしています。claude mcp list は内部で接続試行を行うため、Mac がスリープから復帰した直後の日曜 9:00 に実行されると他のプロセスへの影響が出ます。バックグラウンド設定で逃がしておくのが無難です。

標準出力とエラー出力は両方 ~/.claude/logs/com.shun.env-audit.log に集約しています。スクリプト本体の出力（Audit written to: ... と先頭 80 行のプレビュー）はここに残るので、「launchd が本当に動いたか」の確認はこのファイルを tail するだけで済みます。

diff による過去遡及

レポートが env-audit-20260727.md env-audit-20260803.md と蓄積されるので、前週との差分は 1 コマンドで確認できます。

diff ~/.claude/logs/env-audit-20260727.md ~/.claude/logs/env-audit-20260803.md

典型的な変化パターンとして：

• Connected: **8** → Connected: **5** / Failed: **3** の変化が 1 週間で発生していれば、その週に何かが壊れた
• Enabled plugins: **34** → Enabled plugins: **41** の変化があれば、その週に 7 個のプラグインを有効化したことがわかる
• auto-skill の一覧に新しい名前が増えていれば、誰か（自分または Claude）が新しいスキルを生成した

この diff 運用が本当に役に立ったのは、「2 週前から MCP の Failed が増えていた」と気づいたときです。その週の作業ログを確認すると、特定のプラグインを追加した直後から崩れていることが判明し、そのプラグインを無効にしたら元に戻りました。日付付きレポートがなければ「なんとなく直った」で終わっていたはずです。

実装の詳細

一括リダイレクトブロック { } > "$OUT" を選んだ理由

スクリプト全体が次の構造になっています。

{
  # すべての echo がここに入る
} > "$OUT"

最初に書いたバージョンは echo "..." >> "$OUT" を各行で繰り返す素朴な実装でした。問題はすぐ出ました。スクリプトが途中でエラー終了したとき、>> 追記モードでは「何行か書かれた中途半端なファイル」が残ります。次回のレポートと diff を取ると、前回の残骸が混入してノイズになります。

{ } > "$OUT" ブロックに変えると、ファイルの open は 1 回です。ブロック全体の出力がすべて同じファイルディスクリプタに流れるため、「書き込み途中で止まった」という状態は減ります（ファイル自体は最初にトランケートされて開かれますが、書き込みエラー時の残骸は最小限）。もう一つの利点は可読性です。各行に >> "$OUT" を付け忘れるミスがなくなり、インデントが揃ってレビューしやすい。70 行のスクリプトなのに構造が追いやすいのはこのおかげです。

timeout 25 の根拠

MCP セクションの核心部分がここです。

MCP_OUT=$(timeout 25 claude mcp list 2>&1)

claude mcp list は設定されているすべての MCP サーバーへ接続を試みます。サーバーが stdio 型（ローカルプロセス起動）なら 1 秒以内に応答します。HTTP 型でも、サーバーが正常に動いていれば 3 秒以内。問題は「動いているように見えてハングしている」状態のサーバーです。TCP コネクションは確立するが、応答が永遠に来ない——ローカルで立てた開発用 mock server をそのまま放置したとき、これが起きます。

timeout なしだと claude mcp list がそのサーバーにブロックされ、スクリプト全体が止まります。25 秒にした理由は「正常なサーバーが最大でも 5 秒、壊れたサーバーの TCP タイムアウトは OS 次第で 20 秒前後」という経験値から、余裕を 5 秒足した数字です。壊れた MCP が 2 つ 3 つ並んでいてもタイムアウトは並行して処理されるので、25 秒で打ち切れば十分です。

2>&1 を入れる場所と入れない場所

スクリプトには 2>&1 が複数登場します。使い分けの基準は「その情報をレポートに残すかどうか」です。

MCP_OUT=$(timeout 25 claude mcp list 2>&1)          # stderr を拾う
find $HOME/.claude/plugins ... 2>/dev/null           # stderr を捨てる
ccusage blocks --active 2>&1 | grep -E "..."         # stderr を stdout に合流させてフィルタ

claude mcp list は接続失敗のメッセージを stderr に出します。2>&1 を付けないと MCP_OUT が空になり、全項目が 0 のレポートが出来上がります。最初これを忘れていて「全 MCP Connected」の嘘レポートをしばらく信じていました。

find の 2>/dev/null は逆で、プラグインディレクトリが存在しないときの "No such file or directory" をレポートに混入させないためのノイズ除去です。

grep -c と :-0 デフォルト代入の関係

OK=$(printf '%s' "$MCP_OUT" | grep -c "Connected")
AUTH=$(printf '%s' "$MCP_OUT" | grep -c "Needs auth")
FAIL=$(printf '%s' "$MCP_OUT" | grep -c "Failed to connect")
TOTAL_MCP=${TOTAL_MCP:-0}; OK=${OK:-0}; AUTH=${AUTH:-0}; FAIL=${FAIL:-0}

grep -c は 0 件のとき「0」という文字列を標準出力に出しますが、exit code は 1 を返します。set -o pipefail が効いているため、このパイプラインの exit status は 1 になります。スクリプトに set -e（errexit）が入っていない理由はここです。-e を入れると、MCP サーバーが全部 Connected だった「正常な週」に Fail が 0 件 → grep -c が exit 1 → スクリプト終了、という逆説が起きます。

:-0 デフォルト代入は別の保険です。timeout が発火してコマンドが強制終了された場合、コマンド置換の変数が空文字になる可能性があります。空文字のまま [ "$FAIL" -gt 0 ] を評価すると算術エラーになるので、0 にフォールバックさせています。

Section 6 の犯人特定パイプライン

echo "$MCP_OUT" | grep -E "Failed to connect" | grep "^plugin:" \
  | awk -F: '{print $2}' | sort -u | head -20 | sed 's/^/- /'

claude mcp list の出力には、MCP の登録方法によって plugin:プラグイン名:スキル名 形式の行と、直接 URL で登録した行が混在します。grep "^plugin:" でプラグイン経由の MCP だけを絞るのは、「削除するならプラグインごと無効化する」という操作の単位に合わせるためです。awk -F: '{print $2}' でコロン区切りの 2 番目フィールド（プラグイン名）だけを取り出し、sort -u で同じプラグインが複数の MCP を持つ場合の重複を除去してから head -20 で出力を制限しています。壊滅的な状態でも出力が溢れない設計です。

launchd ジョブが EnvironmentVariables を必要とする理由

plist の先頭に明示的な PATH が入っています。

<key>EnvironmentVariables</key>
<dict>
    <key>PATH</key>
    <string>/path/to/nvm/bin:/opt/homebrew/bin:/opt/homebrew/sbin:...</string>
</dict>

launchd が起動するプロセスは ~/.zshrc も ~/.zprofile も読みません。/etc/paths 相当の最小 PATH（/usr/bin:/bin:/usr/sbin:/sbin 程度）しか持たない状態でスクリプトが走ります。claude コマンドは nvm 管理下の Node.js バイナリ、jq は Homebrew 経由のバイナリ——どちらもデフォルト PATH に入っていません。この設定を書かない場合、スクリプトは一見正常に終了するのに、中身がほぼ空のレポートが出力されます（各コマンドが command not found で失敗して変数が空になる）。

---

私が詰まった話

その1：launchd から claude が見えない

最初に plist を作ったとき、EnvironmentVariables を入れ忘れました。

症状：レポートファイルは毎週更新される。しかし MCP セクションを見ると Connected も Failed も全部 0、Cost セクションも空。スクリプトが動いているのにレポートが空。

調査：tail ~/.claude/logs/com.shun.env-audit.log を見ると次が並んでいました。

zsh: command not found: claude
zsh: command not found: jq
zsh: command not found: ccusage
Audit written to: /path/to/env-audit-20260720.md

スクリプトはエラーなく完走しています。set -uo pipefail の -u（未定義変数エラー）も引っかからず、command not found は 2>&1 で変数に取り込まれるか /dev/null に捨てられていたため、スクリプト自体は終了コード 0 で終わっていました。「動いている」と「意味のある出力が出ている」は別の話だとこのとき学びました。

直し：which claude を実行しても not found。nvm which current で Node.js のパスを特定し、その bin/ ディレクトリを plist の EnvironmentVariables > PATH に追加。同様に /opt/homebrew/bin を jq 用に追加。launchctl unload ~/Library/LaunchAgents/com.shun.env-audit.plist && launchctl load ~/Library/LaunchAgents/com.shun.env-audit.plist でリロードして、手動でスクリプトを走らせて全セクションが埋まるのを確認してから終了しました。

このデバッグで 2 時間溶けました。「cron 系のジョブは PATH を明示する」は今や反射的にやります。

その2：日付が展開されず固定ファイル名になった

症状：~/.claude/logs/ に env-audit-20260720.md のような日付付きファイルができるはずが、env-audit-%Y%m%d.md というリテラルのファイル名で 1 つだけ存在。毎週上書きされるため、diff が取れない。

原因：plist の <string> 内では % 記号が特殊扱いされます。date +%Y%m%d と書くと launchd が %Y や %m をフォーマット指示子として解釈しようとし、うまく展開されません。正しくは \%Y\%m\%d とエスケープします。

<!-- 誤り: リテラル文字列になる -->
<string>~/.claude/scripts/env-audit.sh ~/.claude/logs/env-audit-$(date +%Y%m%d).md</string>

<!-- 正しい: \% でエスケープ -->
<string>~/.claude/scripts/env-audit.sh ~/.claude/logs/env-audit-$(date +\%Y\%m\%d).md</string>

ついでに言うと、plist の中で ~ はホームディレクトリに展開されません。絶対パスで書く必要があります。これを知らずに ~/.claude/logs/... と書いたら、~ ディレクトリ（存在しない）を作ろうとしてエラーになりました。絶対パスを書く・パスに空白を入れない・% はエスケープする——この 3 つを plist のルールとして覚えておくと詰まらずに済みます。

直し：エスケープを修正し、パスを絶対パスに変更してリロード。ls -lt ~/.claude/logs/env-audit-*.md で日付付きファイルが新しく作られることを確認。

その3：claude mcp list が 10 分以上ハングした

最初のスクリプトには timeout がありませんでした。

症状：特定の週から、launchd のログが途中で止まっています。head -80 のプレビューで出るはずの Hooks セクション以降が書かれていない。ファイルは MCP セクションの途中で終わっています。

ps aux | grep claude を実行すると、claude mcp list が PID を持って実行中のまま。時刻を確認すると 12 分経過していました。

原因：その週、ローカル開発中に建てた HTTP 型 mock MCP サーバーを試して、コンテナを落とさずに放置していました。サーバーのプロセスは死んでいるが、設定から削除していないため claude mcp list は接続を試み続けます。TCP の SYN は届かないが、OS の接続タイムアウト（macOS のデフォルトは 75 秒前後）を待ち続けていた状態です。壊れた HTTP MCP が 1 つあっただけで、スクリプト全体が 1 分以上ブロックされていました。

直し：timeout 25 claude mcp list 2>&1 に変更。あわせて MCP の設定を確認し、使っていない HTTP 型サーバーを 3 件削除。削除後の起動時間が体感で速くなりました。time timeout 25 claude mcp list を実行したら 2.3 秒で終了——以前は何秒かかっていたか測る気にもなれませんでした。

このデバッグ後に「なぜ壊れた MCP を放置していたか」を振り返ると、単純に「リストを見ていなかった」からです。claude mcp list を手動で打つ習慣がなければ、壊れていても気づきません。環境診断を自動化する動機として、このハング体験は一番効きました。

その4：set -uo pipefail の -u が別の場所で噛んだ

スクリプトのごく初期のバージョンには、line 28 の :-0 デフォルト代入がありませんでした。

# 古いバージョン（デフォルト代入なし）
OK=$(printf '%s' "$MCP_OUT" | grep -c "Connected")
FAIL=$(printf '%s' "$MCP_OUT" | grep -c "Failed to connect")

echo "- Connected: **$OK** / Failed: **$FAIL**"

症状：timeout 25 claude mcp list がタイムアウト終了した週（つまり MCP がハングしていた週）に、レポートの MCP セクション以降が何も出ていない。ログには出力なし。

原因：timeout が発火すると exit code 124 を返します。コマンド置換 $() の中でタイムアウトした場合、外側の変数への代入は実行されますが、MCP_OUT の中身は空文字になることがあります（2>&1 で取れる出力が途中で打ち切られるため）。その状態で grep -c に空の入力を流すと 0 件として FAIL="0" が設定されますが、TOTAL_MCP は場合によって未定義のまま参照されました。set -u が「unbound variable」として扱いスクリプトが終了します。

直し：TOTAL_MCP=${TOTAL_MCP:-0}; OK=${OK:-0}; AUTH=${AUTH:-0}; FAIL=${FAIL:-0} のデフォルト代入ブロックを追加。タイムアウト時でも変数が 0 に収束し、レポートが最後まで生成されるようになりました。:-0 は単なる初期値設定ではなく、異常系での保険です。

---

4 つの失敗を並べて気づくことがあります。どれも「スクリプト自体のバグ」ではなく「環境の前提が崩れたことへの対処不足」です。PATH が違う、エスケープルールが違う、タイムアウトがない、デフォルト値がない——それぞれ単体では些細なことですが、組み合わさるとレポートが出なくなります。「動いているのに意味がない」状態が最も検出しにくいバグです。今のスクリプトはそれぞれへの対処を一箇所ずつ積み上げた結果です。

つまずきポイント

実装が完成してからが運用の本番です。スクリプト内部のバグ（前段で4件解説）とは別に、「導入後の運用フェーズ」で詰まる場面があります。実際に体験したものを並べます。

launchctl load だけでは plist の変更が反映されない

plist を編集した後、多くの人が最初にやるのが「もう一度 launchctl load ~/Library/LaunchAgents/com.shun.env-audit.plist」です。しかしジョブがすでにロードされていると Load failed: 5: Input/output error が返るか、黙って失敗します。どちらの場合も変更は反映されません。正しい手順は unload してから load し直すセットです。

launchctl unload ~/Library/LaunchAgents/com.shun.env-audit.plist
launchctl load  ~/Library/LaunchAgents/com.shun.env-audit.plist

このひと手間を省いて「なぜか変更が効かない」と30分悩む体験を少なくとも3回しました。今は plist を触ったら反射的に unload && load をセットで実行します。

登録してから1週間待たないとテストできないと思っていた

「毎週日曜 9:00 にしか動かない」と思い込み、初回動作確認のために日曜まで待った話が恥ずかしいのですが本当のことです。launchctl start で任意のタイミングに手動トリガーできます。

launchctl start com.shun.env-audit

実行直後に ~/.claude/logs/com.shun.env-audit.log を tail すれば、スクリプトが走ったか・全セクションが埋まっているかを確認できます。launchd ジョブを登録したら「週次で動くかどうか」の前に「今すぐ動くか」を確認するのがセオリーです。

スクリプトを修正したのにリロードを忘れて古いバージョンが動き続ける

~/.claude/scripts/env-audit.sh を直接編集してスクリプト内部を改善した場合、plist はパスを参照しているだけなのでリロード不要です。次回の起動から変更後の内容で動きます。

一方、plist の設定（PATH・スケジュール・引数など）を変えた場合は unload && load が必要です。この2ケースを混同して「どっちだっけ」と毎回迷うより、「plist を触ったら必ずリロード」でルールを統一するほうが判断コストがなくなります。

生成されたレポートを誰も読まない

自動化の落とし穴として最も典型的なのが「動いているが読まれていない」状態です。~/.claude/logs/ に env-audit-20260727.md が毎週追加されていても、確認の動線がなければ意味がありません。

最初に作った仕組みは「日曜朝にログが生成されるだけ」でした。月曜に Claude Code を立ち上げるとき、レポートを確認するきっかけがありませんでした。2ヶ月後に偶然ログを見たら Failed: 3 が5週間分並んでいた、という実体験があります。

解決策は「読む仕組み」を別に用意することです。月曜朝の最初のセッションで最新レポートの先頭行を Claude に強制表示させるフックを入れてから、対応が翌週に持ち越されるケースがゼロになりました。

ログファイルが無限に増える

env-audit-YYYYMMDD.md が毎週追加されるので、1年で52ファイルになります。容量は問題ありませんが、ls -l ~/.claude/logs/env-audit-*.md したとき、古いファイルが diff の基準を曖昧にします。

「直近3ヶ月分だけ保持する」クリーンアップを月次で走らせると管理しやすくなります。

find ~/.claude/logs -name "env-audit-*.md" -mtime +90 -delete

私はこの1行をスクリプト末尾の } > "$OUT" ブロックの後に追記しています。管理するファイルを増やさず、レポート生成と同じスクリプトにまとめることで一元管理できます。

diff が大きすぎて読めない

前後のレポートを素の diff で比較すると、Cost セクションが実行ごとに全行変わるためノイズになります。セクション単位で比較するには grep で絞るのが実用的です。

# MCPの状態だけ週次比較
grep "Total:\|Connected\|Failed\|Need auth" ~/.claude/logs/env-audit-20260727.md
grep "Total:\|Connected\|Failed\|Need auth" ~/.claude/logs/env-audit-20260803.md

週次の確認に30秒かからない手順にしておくことで「確認が面倒」という感覚を防げます。

ccusage が未インストールでも静かに空のままになる

Cost セクション（Section 5）は ccusage blocks --active に依存しています。ccusage が入っていない環境では、セクション全体が空になります。スクリプトは 2>&1 で stderr を拾っていますが、続く grep -E "Block|Time|Tokens:|Cost:|/h" フィルタで zsh: command not found: ccusage の行がスキップされます。つまり「Cost セクションが空のレポート」が毎週静かに生成されます。

新しい環境に移植するときは which ccusage で事前確認が確実です。nvm 管理下では npm install -g ccusage でインストールしたあと、plist の PATH に ~/.nvm/versions/node/<バージョン>/bin が含まれているかを再確認します。

MCP の Failed を「後で直す」まま放置する

レポートに Failed: 2 が出ても「後で直す」とそのままにすると、翌週また Failed: 2 が出ます。「後で」は来ません。HTTP 型 MCP の削除は claude mcp remove <name> の1コマンドで3秒です。スクリプトの閾値を FAIL > 0（ゼロトレランス）にしている理由は、1件でも許容すると「2件まで OK」という運用に滑落するからです。Recommendations セクションに ⚠️ 1 MCP servers failed. が出たら、確認した日のうちに処理します。

launchctl list でジョブ状態を確認する方法を知らない

launchctl list com.shun.env-audit

このコマンドは PID（実行中なら数字・停止中なら -）と前回の終了コード（LastExitStatus）を返します。LastExitStatus が 0 以外ならスクリプトが異常終了しています。ログを tail する前に、まずこのコマンドで「走ったか」「正常終了したか」を1秒で確認できます。存在を知らないと、「動いているはずなのに」という状態で詰まり続けます。

nvm のバージョン更新後に plist の PATH が古いままになる

nvm で Node.js のバージョンを上げると、バイナリのパスが変わります。たとえば v24.13.0 から v24.15.0 に上げた場合、plist に書いた ~/.nvm/versions/node/v24.13.0/bin のディレクトリが存在しなくなります。その週から claude mcp list が動かず、MCP セクションが全部 0 のレポートになります。nvm でバージョンを変えたら which claude を実行して、plist の PATH を更新してリロードするのがセットです。

---

ベストプラクティス

1. 登録直後に手動トリガーで全セクションを確認する

launchctl load の直後に launchctl start com.shun.env-audit を実行します。~/.claude/logs/com.shun.env-audit.log を tail して、MCP セクションに数値が出ているか・Cost セクションに値があるかを目視します。ここで MCP が「Total: 0 / Connected: 0」なら PATH の問題です。最初に全セクション確認を済ませておけば、「何週間も空レポートが来ていた」を後から発見するコストがゼロになります。

2. plist の PATH は which で確認してから書く

which claude    # ~/.nvm/versions/node/v24.13.0/bin/claude
which jq        # /opt/homebrew/bin/jq
which ccusage   # ~/.nvm/versions/node/v24.13.0/bin/ccusage

上記3コマンドの bin/ 部分を抽出して plist の PATH に並べます。nvm でバージョンを上げた際も同じ確認コマンドで差分が即座にわかります。

3. plist 変更時は unload && load をセットで

plist を触ったら必ず launchctl unload ~/Library/LaunchAgents/com.shun.env-audit.plist && launchctl load ~/Library/LaunchAgents/com.shun.env-audit.plist のセットで実行します。「スクリプトの変更はリロード不要・plist の変更はリロード必要」という判断を都度するより、「plist を触ったら必ずリロード」で統一するほうが安全です。

4. plist の Label は自分のハンドルで名前空間を作る

com.shun.env-audit の shun 部分を自分のハンドルに変えます。複数の launchd ジョブが増えてきたとき、launchctl list | grep com.自分のハンドル で自分のジョブだけを絞り込めます。他のツールが自動生成したジョブと混在しても判別できます。

5. timeout の秒数は「MCP 数 × 5 秒」を目安にする

timeout 25 は当時の MCP 登録数から計算した数値です。正常な MCP 5 件 × 最大 5 秒 = 25 秒が根拠です。MCP が 30 件以上ある環境では timeout 60 に引き上げるか、MCP 自体を整理するほうが根本解決です。タイムアウト値を上げ続けると「壊れた MCP を放置しても動く仕組み」に変質します。スクリプトの修正より MCP の整理を先にします。

6. FAIL > 0 はゼロトレランス・確認日のうちに対処する

Failed が 1 件でも出たら確認した日のうちに claude mcp remove <name> か claude mcp auth <name> で対処します。HTTP 型 MCP の削除は3秒、stdio 型の再認証は1コマンドです。「後で」は「永久に」に変わります。

7. auto-skill の削除基準を明確に決める

ls ~/.claude/skills/auto/ の一覧を見たとき「最後に Claude が使ったのはいつか」を問いかけます。半年以上呼ばれた記憶がないスキルは削除候補です。削除基準がなければスキルは際限なく増え、コンテキスト税が静かに上がり続けます。「半年使わなければ削除」というルールを設けてから、~/.claude/skills/auto/ のファイル数が管理可能な範囲に収まりました。

8. diff を読む前に特定セクションだけ grep する

全文 diff は読むのに時間がかかります。「今週 MCP が壊れたか」だけを知りたいなら、

grep "Total:\|Connected\|Failed" ~/.claude/logs/env-audit-20260727.md
grep "Total:\|Connected\|Failed" ~/.claude/logs/env-audit-20260803.md

でセクションを絞ります。30 秒以内に確認できる手順にしておくことで「確認が面倒」を防げます。

9. レポートを「読む仕組み」を別に用意する

生成だけ自動化して読む動線がなければ、レポートは無意味です。月曜朝の最初のセッションで最新レポートを Claude に強制表示させるフックを追加するか、Slack の webhook で要約を送るかのどちらかを組み合わせます。「週次で診断→週の最初のセッション前に把握→その場で対処」のサイクルが成立して初めてこの仕組みが価値を持ちます。

10. スクリプト自体をバージョン管理する

~/.claude/scripts/ ごと private な dotfiles リポジトリに入れ、スクリプトの改善のたびにコミットします。「なぜこの行を変えたか」の文脈が残り、「3ヶ月前のバージョンに戻したい」が10秒で完結します。スクリプトを単体ファイルで管理していると、劣化してからの原因追跡が困難になります。

11. プラグイン追加後は即座に claude mcp list で確認する

新しいプラグインを追加したら、その場で claude mcp list を打って Failed が出ていないかを確認します。週次レポートを待たず、記憶と状態が一致した直後に確認することで「どのプラグインが原因か」が自明な状態で問題を発見できます。

12. launchctl list com.shun.env-audit でジョブ状態を1秒で確認する

launchctl list com.shun.env-audit

PID（実行中なら数字・停止中なら -）と LastExitStatus（0 以外なら異常終了）が返ります。ログを読む前にまずこれで「走ったか」を確認します。

13. ゾンビファイルを3ヶ月に1回一掃する

enabledPlugins から削除されてもディスクに残るプラグインファイルは find の走査対象に入り続けます。「Plugin commands on disk: 83」なのに「Enabled plugins: 31」なら52ファイルがゾンビです。3ヶ月に一度 ~/.claude/plugins/ 以下を直接確認し、対応するプラグインが無効化されているディレクトリを rm -rf で整理します。

14. プラグイン数の閾値は自分の体感に合わせて調整する

スクリプトの TOTAL > 50 という閾値は私の環境での経験値です。コマンドだけのプラグインとスキル・エージェントを持つプラグインではコンテキスト税の重さが違います。「重い」と感じ始めた時点のプラグイン数を記録し、その値 × 0.8 を警告閾値に設定するのが現実的な調整法です。

15. find ~/.claude/logs -name "env-audit-*.md" -mtime +90 -delete をスクリプト末尾に追記する

ログローテーションをスクリプト本体に組み込むことで、「3ヶ月で古いレポートを自動削除」が追加設定なしに動きます。} > "$OUT" の後の末尾に1行追加するだけです。レポート生成と整理が同じスクリプトに収まり、管理するジョブが増えません。

---

まとめ

「環境が腐る」という感覚はもともと曖昧です。MCP の接続失敗が増えても、auto-skill が増殖しても、その週に自分がそれに気づくことはほぼありません。気づかないまま使い続けると、コンテキスト税の増加・起動遅延・リトライコストの上乗せが少しずつ積み重なり、数ヶ月後に「なんか最近遅いな」という感覚だけが残ります。

env-audit.sh と launchd ジョブが解決するのは「気づかない問題」です。70行のスクリプトが週次で現状のスナップショットを作り、日付付きで蓄積し、diff によって「いつから壊れたか」を遡れる記録を作る——それだけです。難しい技術は一切使っていません。

月商 0 円から 120 万まで持ってくる過程で学んだのは、「道具を増やすこと」と「道具を維持すること」は別のコストがかかるという事実です。追加は瞬間ですが、管理は毎週です。追加のたびに管理コストが積み上がります。それを自動化で回収しない限り、環境は機能ではなく負債として増え続けます。

週次の健康診断は、そのコストを Claude に払わせる仕組みです。MCP が壊れているかどうかを人間が気にしなくてよい状態が、人間の思考を本来の作業に集中させます。

---

仕組みの全体像・月120万の内訳・30日手順は有料noteにまとめています。
📕 Claude Code自律環境で、実際どう稼ぐか ― 仕組み・実例・始め方・サポート

---

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

• 制作物・記事は bokuwalily.com にまとめています🖥️
• AIで「寝てても回る仕組み」を作って月120万にした話は noteの有料記事 に💰
• OSS: github.com/bokuwalily 🐙
• 最新情報・お問い合わせは X @bokuwalily へ🌍

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