🧹 🧹 育おすぎた環境は腐る――週次 env-audit で Claude Code を棚卞しする — リヌダヌ×
🧹

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

#automation#claudecode#副業2026-08-10 · 箄30分

月商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サヌビスを量産しおいたす

  • AIで「寝おおも回る仕組み」を䜜っお月120䞇にした話は noteの有料蚘事 に💰
  • OSS: github.com/bokuwalily 🐙
  • 最新情報・お問い合わせは X @bokuwalily ぞ🌍

皆さんの ❀ やシェアが励みになりたす