🛡️ 複数リポジトリを毎朝自動監査する仕組み

会社都合で解雇され月商ゼロになった夜、私の手元に残ったのは複数の個人リポジトリだけでした。それを半年で月商120万円まで育て直せたのは、コードを書くより先に「環境」を整えたからです。今回はその環境の中核、複数リポジトリを毎朝自動監査するスクリプトの実装を公開します。

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

副業でプロジェクトを複数並走させていると、必ず「人間の注意力」が律速になります。私の場合、shukatsu-tracker（就活関連のトラッキングツール）と seo-affiliate-site（SEOアフィリエイトサイト）を同時に動かしていましたが、一方に集中している間にもう一方で小さな腐敗が積み重なっていきました。

具体的にどういう問題が起きたか、正直に書きます。

未コミットファイルの山。フィーチャー開発中の一時的なデバッグコードをコミットしないまま2週間放置したことがあります。後で「この変更、なんで入れたんだっけ」と追えなくなり、30分をゼロリターンの調査に費やしました。今のスクリプトでは未コミット50件超で🟡警告が出ます（UNCOMMITTED_WARN=50）。50件は甘いと思われるかもしれませんが、「コミットすべき変化量の指標」として機能させることが目的で、日常的なWIP作業を過検知しない水準に設定しています。

stale commitの恐怖。最終コミットから14日経過すると🟡になります（STALE_COMMIT_DAYS=14）。これは「プロジェクトが死んでいる」サインではなく、「意識的に触っていない」サインとして使います。2週間ログを漁っても理由のないstaleは、依存パッケージが古くなるリスクと直結します。副業の場合、本業との兼ね合いで意図的に停止することもあるので、スクリプトは事実を報告するだけで自動的にpushやissue作成はしません。監視の責任は見た人間にある、という設計です。

.envの誤tracking。これは🔴の即時警告です。UNCOMMITTED_WARN や STALE_COMMIT_DAYS は緩いしきい値で運用しますが、.envのトラッキングだけは即アウト。git ls-files で .env.example を除くすべての .env* パターンを拾います。一度でも git add . を叩いたときに .env を混入させた経験がある人なら、この恐怖は共有できると思います。私は初期に seo-affiliate-site の開発中、.gitignore の更新を後回しにして危うく APIキーを含む .env をコミット寸前まで行きました。それ以来、このチェックを外したことはありません。

node_modules の肥大。820MiB（1GiBの80%）で事前警告、1GiBで🟡に入ります。

NODE_MODULES_WARN_BYTES=$((1024 * 1024 * 1024))      # 1 GiB
NODE_MODULES_NEAR_BYTES=$((1024 * 1024 * 1024 * 80 / 100))  # 820 MiB (80% 事前警告)

なぜ2段階か。SSDの空き容量が不意に1GiBを切ると、ビルドやDockerの動作が怪しくなります。「急に遅くなった」の原因追跡に1時間溶かすより、820MiB時点で npm prune を検討する方が安い。

---

これらの問題に共通するのは、「気づいたときには手遅れ」という構造です。コードを書く人間が、コードの健全性を能動的にチェックし続けることはできません。脳内のワーキングメモリは常に「今作っているもの」に全振りされているからです。だからこそ、チェックを人間の外に出す必要があります。

そしてもう一つ、見落とされがちな設計原則があります。監視スクリプトが壊れても、本業を止めてはいけない、という原則です。

trap 'exit 0' ERR

スクリプト冒頭のこの1行が、設計の根幹です。set -u（未定義変数をエラーにする）を有効にしながら、ERRシグナルをキャッチして exit 0 で抜けます。つまりスクリプト内のどこかでエラーが出ても、launchdから見ると「正常終了」です。

なぜこれが重要か。launchdはジョブが失敗すると再試行やアラートを出すことがあります。監視ツール自体がエラーを吐き続け、それが連鎖的な通知やログ肥大を引き起こす——これを「モニタリングの二次災害」と呼びますが、個人開発ではこれが致命的です。月商120万を支えているのはメインのプロダクトコードであり、監視スクリプトではありません。監視ツールは静かに失敗していい。正確には、失敗を自分で吸収して本体に波及させてはいけない。

fail-open（失敗時に通過させる）の設計は、セキュリティの文脈では忌避されますが、可用性優先の監視ツールでは正解です。このスクリプトが誤動作して shukatsu-tracker のビルドが止まるより、監視が沈黙する方がずっとましです。

全体の流れ

実際の配線を図にすると次の通りです。

毎朝 7:30（launchd が起動）
       │
       ▼
 ~/.claude/scripts/project-health.sh
       │
       ├──[ shukatsu-tracker ]
       │       ├─ 未コミット件数（git status --porcelain）
       │       ├─ 最終コミット経過日（git log -1 --format='%ct'）
       │       ├─ .env* tracking（git ls-files）
       │       └─ node_modules サイズ（du -sk）
       │
       └──[ seo-affiliate-site ]
               ├─ 同上 4 軸
               └─ package.json の依存数（python3 で JSON パース）
                       │
                       ▼
         ~/.claude/logs/project-health-YYYYMMDD.md  ← 日付別アーカイブ
         ~/.claude/logs/project-health-latest.md    ← 常に最新（cp で上書き）

出力は Markdown テーブルです。Claude Code のダッシュボードや任意のエディタで直接参照できます。

| Project | Uncommitted | Last commit | Deps | node_modules | Status |
|---------|-------------|-------------|------|--------------|--------|
| `shukatsu-tracker` | 3 | 2 days ago - feat: ... | 12+8 | 234MiB | 🟢 |
| `seo-affiliate-site` | 0 | 16 days ago - chore: ... | 9+5 | 187MiB | 🟡 |

Deps 列は package.json の dependencies と devDependencies の件数を 12+8 形式で表示します。ここで python3 を使っているのは、bash だけで JSON をパースするより確実だからです。

DEPS=$(python3 -c "
import json, sys
try:
    p = json.load(open('$PKG'))
    d = len(p.get('dependencies', {}) or {})
    dd = len(p.get('devDependencies', {}) or {})
    print('%d+%d' % (d, dd))
except Exception:
    print('?')
" 2>/dev/null)

except Exception: print('?') で握りつぶしているのは意図的です。package.json のパースに失敗してもスクリプト全体を落とす理由はありません。? が出たらそのリポジトリだけ個別確認すればいい。

launchd による配線

スクリプト単体がどれだけ正確でも、実行され続けなければ意味がありません。cronよりもmacOSネイティブの launchd を選んだ理由は2つあります。システム起動後の再実行保証と、標準エラーのファイル永続化です。

plistの核心部分を示します。

<key>StartCalendarInterval</key>
<dict>
  <key>Hour</key>
  <integer>7</integer>
  <key>Minute</key>
  <integer>30</integer>
</dict>

<key>LowPriorityIO</key>
<true/>

<key>Nice</key>
<integer>10</integer>

<key>ProcessType</key>
<string>Background</string>

<key>StandardErrorPath</key>
<string>~/.claude/logs/com.shun.project-health.log</string>

<key>StandardOutPath</key>
<string>~/.claude/logs/com.shun.project-health.log</string>

LowPriorityIO: true と Nice: 10 の組み合わせがポイントです。du -sk はディスク読み取りを伴うため、普通に実行するとビルドやIDEのインデックス更新と競合します。LowPriorityIO はI/Oスケジューラに「後回しにしていい」と伝え、Nice: 10 はCPUスケジューラに同じことを伝えます。朝7:30はまだ本格的な作業前ですが、MacBookを開いたとたんにXcodeのindex更新やnpmのビルドが走ることも多い。監視スクリプトに本業のビルドを遅延させる権限は与えません。

EnvironmentVariables に PATH を明示しているのも重要です。

<key>EnvironmentVariables</key>
<dict>
  <key>PATH</key>
  <string>/Users/.../.nvm/versions/node/v24.13.0/bin:/opt/homebrew/bin:...</string>
</dict>

launchd はシェルプロファイル（.zshrc 等）を読み込まずに起動します。nvm 経由でインストールした node や、Homebrew の git を使うには PATH を plist に直書きする必要があります。「手動実行は動くのにlaunchdだと動かない」の大半はこれです。スクリプト内の python3 も /usr/bin/python3（macOS同梱）ではなく Homebrew 配下の python が使われるかどうかで挙動が変わります。plist の PATH に /opt/homebrew/bin を含めることで、開発環境と自動実行環境の差異を潰しています。

ログの二重化

OUT="$LOG_DIR/project-health-${DATE_TAG}.md"     # 例: project-health-20260801.md
LATEST="$LOG_DIR/project-health-latest.md"
...
cp "$OUT" "$LATEST" 2>/dev/null || true

日付別ファイルと latest の2本立てにしているのは、用途が違うからです。日付別は「先週の火曜はどういう状態だったか」を遡るためのアーカイブ。latest は「今朝の状態を今すぐ知る」ためのショートカット。Claude Code のメモリや別スクリプトから参照するときは常に latest を読みます。cp の後ろに || true を付けているのも fail-open の延長線上で、コピーの失敗でスクリプトが非ゼロ終了するのを防ぎます。

mkdir -p "$LOG_DIR" を最初に置いているのは、初回実行時にディレクトリがなくてもファイル書き込みに失敗しないためです。この手のユーティリティスクリプトは「完全にクリーンな環境での初回実行」で死ぬことが多い。自分の環境ではすでにディレクトリがあるので気づかず、別のマシンに移植したとたんに動かなくなる、という罠をつぶしています。

bash 3.2 互換

スクリプトのコメントに bash 3.2 互換 (mapfile / assoc array 禁止) とあります。macOS に同梱されているデフォルトの /bin/bash はGPL v2の関係でbash 3.2のままです（Homebrew で bash 5系を入れても、/bin/bash は変わらない）。plist の ProgramArguments で /bin/bash -c を使っている以上、スクリプトはbash 3.2で動く必要があります。

bash 4以降の mapfile（配列へのパイプ読み込み）や declare -A（連想配列）は使えません。代わりに文字列の追記（WARN_LINES="${WARN_LINES}..."）と printf "%b" での改行展開で対応しています。

WARN_LINES=""
...
WARN_LINES="${WARN_LINES}- ${STATUS_FLAG} \`${NAME}\`: ${REPO_WARNS}\n"
...
printf "%b" "$WARN_LINES"

\n リテラルを printf "%b" で展開するのは、echo -e がbash/sh実装間で挙動が揺れるためです。printf はPOSIX準拠で安全です。

実装の詳細

git -C でループ内の「現在地」汚染を防ぐ

スクリプトの中で cd "$REPO" を一度も使っていないことに気づくでしょうか。すべての git コマンドは -C フラグで対象ディレクトリを直接指定しています。

UNCOMMITTED=$(git -C "$REPO" status --porcelain 2>/dev/null | wc -l | tr -d ' ')
LAST_COMMIT=$(git -C "$REPO" log -1 --format='%cr - %s' 2>/dev/null | LC_ALL=C tr '|' '/' | LC_ALL=C tr -d '\r\n' | cut -c1-80)
LAST_COMMIT_TS=$(git -C "$REPO" log -1 --format='%ct' 2>/dev/null)
TRACKED_ENV=$(git -C "$REPO" ls-files 2>/dev/null | grep -E '(^|/)\.env($|\.)' | grep -v '\.env\.example$' | head -5)

なぜ cd を使わないかというと、ループの中で cd すると「現在地」がループをまたいで汚染されるからです。1つ目のリポジトリ処理中に何らかの理由で cd が失敗した場合、2つ目以降は意図しないディレクトリで git コマンドを実行します。set -u と trap 'exit 0' ERR の組み合わせがあっても、「間違ったリポジトリを操作している」状態は検知できません。-C を使えば各コマンドが独立して対象ディレクトリを持つため、ループ間の副作用が原理的に発生しません。

STATUS_FLAG の単方向更新

STATUS_FLAG="🟢"
...
if [ "$UNCOMMITTED" -gt "$UNCOMMITTED_WARN" ]; then
    STATUS_FLAG="🟡"
fi
...
if [ "$COMMIT_AGE_DAYS" -gt "$STALE_COMMIT_DAYS" ]; then
    [ "$STATUS_FLAG" = "🟢" ] && STATUS_FLAG="🟡"   # ← 🟡 昇格は 🟢 のときだけ
fi
...
if [ -n "$TRACKED_ENV" ]; then
    STATUS_FLAG="🔴"   # ← 🔴 昇格は無条件
fi

STATUS_FLAG の更新ルールに注目してください。🟡 への昇格は「現在 🟢 のときだけ」という条件付きです。一方、🔴 への昇格は無条件です。

これは「重篤度が低いほうへの逆戻りを防ぐ」設計です。uncommitted が多くて 🟡 になった後に stale-commit チェックが来ても、🟢 のときだけ 🟡 に変えると書かれているので状態は変わりません。.env 追跡（🔴）だけは何があっても最高アラートを保持します。

副業の実務でこれが大事な理由は、テーブルの Status 列を 右端の1列だけ見て瞬時に判断するためです。複数の問題が重なったときに最も深刻なアラートが保持されていなければ、テーブルを眺めた10秒間で見落としが生まれます。

uncommitted カウントの補足ロジック

# uncommitted が0超かつ閾値以下でも、他の警告がある場合は件数を付記
if [ "$UNCOMMITTED" -gt 0 ] && [ "$UNCOMMITTED" -le "$UNCOMMITTED_WARN" ] && [ -n "$REPO_WARNS" ]; then
    REPO_WARNS="${REPO_WARNS}uncommitted=${UNCOMMITTED} (ok); "
fi

この条件分岐は「閾値以下の uncommitted は単独では警告しないが、他の問題と組み合わさったときは付記する」という複合判断です。たとえば stale-commit（14日超）が出ているリポジトリで uncommitted が 23 件あったとすると、「14日触っていない + 未コミット23件」という組み合わせが Warnings セクションに残ります。単独では 🟡 にしない数字でも、別の問題と組み合わさった文脈では重要な情報になります。

node_modules の GiB 表示と整数演算

NM_KB=$(du -sk "$NM_DIR" 2>/dev/null | awk '{print $1}')
[ -z "$NM_KB" ] && NM_KB=0
NM_BYTES=$((NM_KB * 1024))
NM_MIB=$((NM_KB / 1024))
if [ "$NM_MIB" -ge 1024 ]; then
    NM_DISPLAY="$((NM_MIB / 1024)).$((NM_MIB % 1024 * 10 / 1024))GiB"
else
    NM_DISPLAY="${NM_MIB}MiB"
fi

du -sk は KB 単位で返します。1024 倍して NM_BYTES を得てから、閾値との比較はバイト単位で行います（整数演算なので精度が出やすい）。GiB 表示の $((NM_MIB % 1024 * 10 / 1024)) は「1024 未満の余りを 10 倍してから 1024 で割る」ことで、小数点以下1桁の数字を整数として得ています。bash 3.2 では浮動小数点演算が使えないため、この整数演算で代替しています。表示は 1.2GiB のような形で出力されます。

.env 追跡の grep パターン

TRACKED_ENV=$(git -C "$REPO" ls-files 2>/dev/null \
    | grep -E '(^|/)\.env($|\.)' \
    | grep -v '\.env\.example$' \
    | head -5)

grep -E '(^|/)\.env($|\.)' は「.env そのもの」か「.env. から始まるファイル（.env.local、.env.production 等）」を拾います。(^|/) を付けているのは、サブディレクトリ内の .env（config/.env など）も拾うためです。grep -v '\.env\.example$' で .env.example だけ除外します。

| head -5 を付けているのは、何らかの事故で大量の .env* ファイルが tracked になっていたときに出力が爆発しないようにするためです。Warnings セクションには最初の1件だけ FIRST_ENV=$(echo "$TRACKED_ENV" | head -1) で表示します。「何件あるか」より「まず1件示して即気づかせる」を優先しています。

出力の二段構え：テーブルと Warnings セクション

echo "| \`${NAME}\` | ${UNCOMMITTED} | ${LAST_COMMIT} | ${DEPS} | ${NM_DISPLAY} | ${STATUS_FLAG} |" >> "$OUT"
...
{
  echo "## Warnings (${TOTAL_WARN})"
  ...
  printf "%b" "$WARN_LINES"
} >> "$OUT"

テーブルは「一覧把握」、Warnings セクションは「問題の詳細」を担います。テーブルはリポジトリ数が増えても横幅が固定で読めますが、警告の詳細（どのファイルが tracked か、何日 stale か）を詰め込むとセルが長くなりすぎます。だから詳細は下の Warnings セクションに分離しています。

TOTAL_WARN のカウントはリポジトリ単位（1リポジトリで複数問題あっても +1）です。## Warnings (0) と ## Warnings (2) を並べて見たとき、問題リポジトリ数がひと目でわかります。「2件の問題がある」ではなく「2つのプロジェクトに問題がある」という粒度で管理しています。

---

私が詰まった話

詰まり① launchd で「command not found」が無音で続いた

最初に plist を作って launchctl load したとき、スクリプト自体は存在するのにジョブが無音で失敗していました。StandardErrorPath に設定したログファイルを見に行くと：

/bin/bash: git: command not found
/bin/bash: python3: command not found

原因は PATH でした。端末で手動実行するときは .zshrc が読み込まれ、Homebrew の PATH が通っています。しかし launchd はシェルプロファイルを一切読まずに起動します。/bin/bash -c で呼ばれた時点での PATH は /usr/bin:/bin:/usr/sbin:/sbin 程度しかありません。

解決は plist への PATH の直書きです。実際のファイルにはこう書かれています。

<key>EnvironmentVariables</key>
<dict>
    <key>PATH</key>
    <string>/Users/.../.nvm/versions/node/v24.13.0/bin:/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/Users/.../.local/bin</string>
</dict>

nvm 配下のノードと Homebrew を先に並べることで、スクリプト内の python3 は Homebrew 配下の Python が使われ、端末での動作と完全に一致します。

この問題に気づくまで2日かかりました。StandardErrorPath でログファイルを設定していなければ、失敗の痕跡すら残らなかったところです。新しい launchd ジョブを作るたびに、まずログファイルの設定と PATH の明示を最初に行うようにしました。

詰まり② bash 3.2 で動かない構文を書いてしまった

最初のバージョンでは連想配列を使って複数リポジトリを管理しようとしていました。

# NG（bash 4 以上でしか動かない）
declare -A REPO_MAP
REPO_MAP["shukatsu-tracker"]="$HOME/dev/shukatsu-tracker"
REPO_MAP["seo-affiliate-site"]="$HOME/dev/seo-affiliate-site"

端末での手動実行では問題なく動きます。しかし launchd 経由（/bin/bash）で実行すると：

/bin/bash: declare: -A: invalid option

macOS の /bin/bash は bash 3.2.57 です。declare -A（連想配列）は bash 4.0 から追加されました。Homebrew で bash 5系をインストールしても /bin/bash は変わりません。plist の ProgramArguments が /bin/bash を指している以上、スクリプトは bash 3.2 で動く必要があります。

現在のスクリプトでは、複数リポジトリを改行区切りの文字列で持ちます。

REPOS="
$HOME/dev/shukatsu-tracker
$HOME/dev/seo-affiliate-site
"

for REPO in $REPOS; do
    ...
done

for REPO in $REPOS でクォートしていない $REPOS はワード分割されます。改行もスペースも IFS のデフォルト値でスプリットされるため、リポジトリパスに空白が含まれない限りこれで動きます。mapfile も連想配列も不要で、bash 3.2 でそのまま動作します。「シンプルに書けない制約」が見つかったときに、より単純な代替を探すと大抵見つかります。

詰まり③ git log の日本語が tr でテーブルを崩壊させた

LAST_COMMIT の取得は git log のコミットメッセージを含みます。

LAST_COMMIT=$(git -C "$REPO" log -1 --format='%cr - %s' 2>/dev/null \
    | LC_ALL=C tr '|' '/' | LC_ALL=C tr -d '\r\n' | cut -c1-80)

初期バージョンではこのパイプラインに LC_ALL=C がありませんでした。日本語のコミットメッセージ（feat: ログイン画面を追加 のような）が混じったとき、tr コマンドがマルチバイト文字を正しく処理できず、テーブルのパイプ文字 | に似た文字化けが混入しました。Markdown テーブルで | が余分に増えると列全体がずれ、レポートが読めなくなります。

LC_ALL=C tr '|' '/' でパイプ文字をスラッシュに変換し、テーブルの列崩壊を防いでいます。LC_ALL=C を付けることで、tr がバイト単位で処理するモードになり、マルチバイト文字の誤認識が消えます。

スクリプト先頭の export LANG=en_US.UTF-8 と組み合わせることで、git log の出力自体は UTF-8 で取得しつつ、tr の文字処理だけバイトモードに切り替えるという使い分けをしています。

詰まり④ set -u と trap の噛み合わせで無音 exit が発生した

set -u は未定義変数の参照をエラーにします。trap 'exit 0' ERR はエラー時に即 exit 0 します。この組み合わせで、最初は意図しない無音スキップが発生していました。

問題のコードはこうでした。

# NG だった初期バージョン
LAST_COMMIT_TS=$(git -C "$REPO" log -1 --format='%ct' 2>/dev/null)
COMMIT_AGE_DAYS=$(( ($(date +%s) - LAST_COMMIT_TS) / 86400 ))
# ↑ LAST_COMMIT_TS が空文字のとき、算術展開が構文エラー → ERR 発火 → exit 0

LAST_COMMIT_TS が空文字（コミットがないリポジトリ）のとき、$(( ... - )) の算術展開が構文エラーになります。set -u の対象外ですが、算術エラーは bash が非ゼロステータスを返すため、trap 'exit 0' ERR が即発火してスクリプト全体が終了します。残りのリポジトリは一切チェックされず、レポートは途中で切れたまま latest.md に上書きされます。

修正は空文字ガードを設けることです。現在のコードはこうなっています。

LAST_COMMIT_TS=$(git -C "$REPO" log -1 --format='%ct' 2>/dev/null)
if [ -n "$LAST_COMMIT_TS" ] && [ "$LAST_COMMIT_TS" -gt 0 ] 2>/dev/null; then
    COMMIT_AGE_DAYS=$(( ($(date +%s) - LAST_COMMIT_TS) / 86400 ))
    if [ "$COMMIT_AGE_DAYS" -gt "$STALE_COMMIT_DAYS" ]; then
        [ "$STATUS_FLAG" = "🟢" ] && STATUS_FLAG="🟡"
        REPO_WARNS="${REPO_WARNS}stale-commit=${COMMIT_AGE_DAYS}d (>${STALE_COMMIT_DAYS}d); "
    fi
fi

[ "$LAST_COMMIT_TS" -gt 0 ] 2>/dev/null の末尾 2>/dev/null は、LAST_COMMIT_TS が非数値だったときに [ コマンドが出す "integer expression expected" のメッセージをログに残さないためです。この条件が偽になれば算術展開には到達せず、ERR も発火しません。

trap 'exit 0' ERR を使う場合、「どんな非ゼロステータスでも即 exit する」ということを常に念頭に置く必要があります。防御的なガード条件が増えるのは冗長に見えますが、fail-open スクリプトでは「到達しないはずのコードパスが ERR を吐いてスクリプトを殺す」事故を防ぐためのコストとして割り切っています。監視スクリプトが途中で黙って終了することは、監視スクリプト自体がクラッシュすることと同じくらい危険です。

詰まり⑤ StandardOutPath と StandardErrorPath が同じファイルで上書きが起きた

最初は StandardOutPath と StandardErrorPath を別々のファイルに設定していました。

<key>StandardOutPath</key>
<string>~/.claude/logs/com.shun.project-health-out.log</string>
<key>StandardErrorPath</key>
<string>~/.claude/logs/com.shun.project-health-err.log</string>

しかし launchd はジョブを実行するたびにこのファイルを上書きします（append ではありません）。stdout はスクリプト本体の出力（Markdown レポート）を $OUT に直接書くので空のはずですが、stderr に出るデバッグ情報は前回実行分が毎朝消えることになります。

解決は stdout と stderr を同じファイルに向けることです。現在のファイルがそうなっています。

<key>StandardErrorPath</key>
<string>/Users/.../.claude/logs/com.shun.project-health.log</string>
<key>StandardOutPath</key>
<string>/Users/.../.claude/logs/com.shun.project-health.log</string>

同じファイルを指すことで、stdout と stderr が混在した状態で同一ファイルに書き込まれます。1日1回の上書きなので前日分は消えますが、「今朝のジョブはどう動いたか」を確認するには十分です。より長期の保持が必要であれば >> を使ったラッパーで呼び出す方法もありますが、現時点では朝のデバッグ1日分で事足りています。

launchd ジョブのログを追うときは、log show --predicate 'subsystem == "com.apple.launchd"' より、StandardErrorPath に設定したファイルを直接 tail -f する方が実用的です。前者は launchd デーモン側のメタ情報、後者はスクリプトの実際の出力です。混同して「ログが見つからない」と迷ったことがありますが、スクリプトの動作確認に必要なのはほぼ後者だけです。

つまずきポイント

p2 で詳述した5件（PATH未通過／bash 3.2の連想配列／日本語コミットメッセージの文字化け／set -u と trap の噛み合わせ／StandardOutPath の上書き）以外で実際に詰まった、あるいは詰まりうるポイントを網羅します。

• plist 内の ~ は展開されない。 StandardErrorPath に ~/.claude/logs/... と書くと、launchd はそれを文字列そのまま解釈します。/ 直下に ~ というディレクトリを作ろうとして静かに失敗します。実際のファイルはすべて /Users/<username>/... 形式の絶対パスで記述しています。PATH の EnvironmentVariables も同様で、$HOME 変数展開は効きません。「手動で動くのに launchd で動かない」の第二の原因がこれです。

• launchctl load は macOS Ventura 以降で非推奨になった。 launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/...plist が現行の書き方です。load でも動きますが、macOS のバージョンアップで挙動が変わるリスクがあります。新規作成時から bootstrap / bootout に慣れておく方が安全です。

• コミットがない（空の）リポジトリを REPOS リストに入れると ERR が発火する。 git log -1 --format='%ct' はコミットゼロのリポジトリで空文字を返します。現在のスクリプトは [ -n "$LAST_COMMIT_TS" ] && [ "$LAST_COMMIT_TS" -gt 0 ] 2>/dev/null のガードを通じてこれを吸収しています。新しいリポジトリを REPOS に追加した直後の初回実行で「stale チェックが出ない」のはこのガードが機能している証拠です。異常ではありません。

• macOS 同梱の python3 がXcodeツールのインストールダイアログを出す。 Homebrew 未導入のクリーン環境では、/usr/bin/python3 の初回起動時にGUIダイアログが開きます。launchd 経由では画面が表示されずコマンドがハングします。plist の PATH に /opt/homebrew/bin を先頭に含めることで Homebrew 配下の python3 が優先され、この問題は発生しません。Homebrew を使っているなら追加作業は不要です。

• for REPO in $REPOS はパスにスペースがあると2トークンに分割される。 スクリプトはワード分割を利用して改行区切りのリスト処理をしているため、~/dev/my project のようなスペース入りパスは ~/dev/my と project に分割されて両方が「ディレクトリが見つからない」で 🔴 になります。現在管理している shukatsu-tracker と seo-affiliate-site はスペースなしなので問題ありませんが、移植先でディレクトリ名に注意が必要です。

• スリープ中に通過した実行時刻は次の起動まで飛ばされる。 StartCalendarInterval は cron と同じ挙動で、Mac がスリープ中だった場合、その時刻の実行をスキップします。翌朝 7:30 まで latest.md は前日付きのまま残ります。「今日分のレポートが出ていない」と思ったらまずスリープの確認です。解決策は StartInterval（秒数ごと）ですが、開発中に不意なタイミングで走るデメリットがあります。朝 PC を開く習慣があれば StartCalendarInterval のままで実用上は問題ありません。

• latest.md が古いまま止まっていたら「途中 exit」のサインと読む。 trap 'exit 0' ERR による無音終了は、cp "$OUT" "$LATEST" に到達する前に発生することがあります。その場合 latest.md は前日分のまま残ります。「latest が昨日付き」の状態を検知したら、com.shun.project-health.log を確認するのが最短の診断ルートです。

• du -sk の出力が空になるケースがある。 node_modules が存在してもアクセス権限がないと du -sk は何も返しません。スクリプトは NM_KB=$(... 2>/dev/null) のあとで [ -z "$NM_KB" ] && NM_KB=0 を置いているため、空の場合は 0 として処理されます。「node_modules が明らかにあるのに — 表示になる」場合はパーミッションを確認してください。

• .env.example が除外されない書き方をするとノイズが出る。 grep -E '(^|/)\.env($|\.)' | grep -v '\.env\.example$' の 2 段フィルタが正しい書き方です。最初に grep -E '\.env' だけで書くと .env.example も引っかかり、テンプレートファイルが 🔴 警告を出し続けます。最初のバージョンでこれをやり、全リポジトリが常時 🔴 という状態を一日放置しました。

• launchctl list | grep com.shun.project-health で PID が出ないのは正常。 このジョブはスケジュール起動型で、実行中以外は常駐しません。PID 列が - でも問題ありません。LastExitStatus が 0 であることを確認する方が有用です。launchctl list com.shun.project-health で JSON 形式の詳細が出るので、LastExitStatus と LastExitDate を見て正常動作を確認します。

---

ベストプラクティス

1. 監視スクリプトは fail-open で設計する

trap 'exit 0' ERR を冒頭に置く。スクリプトが壊れても本業のビルドや launchd の連鎖アラートを止めない。可用性優先の監視ツールにおける fail-open は正解です。セキュリティ文脈とは逆の判断です。

2. git -C を使い、ループ内で cd をしない

cd "$REPO" をすると、次のリポジトリに移る前に cd の失敗や想定外の状態が引き継がれます。git -C "$REPO" status のように各コマンドが独立してターゲットを持てば、ループをまたぐ副作用は原理的に発生しません。

3. plist の全パスを絶対パスで書く

~ も $HOME も launchd では展開されません。EnvironmentVariables の PATH も StandardErrorPath も /Users/<username>/... の絶対パスで書きます。「手動で動くのに launchd で動かない」の原因の半分はここです。

4. nvm → Homebrew → system の順で PATH を明示する

launchd はシェルプロファイルを読まないため、/usr/bin:/bin 程度の素の PATH で動きます。plist の EnvironmentVariables に開発環境と同じ PATH を書くことで、python3・git・node の挙動が端末と完全に一致します。スクリプトを書いた本人の端末以外でも動くようになります。

5. LowPriorityIO: true と Nice: 10 を必ずセットにする

du -sk はディスク読み取りを伴います。LowPriorityIO で I/O スケジューラを、Nice: 10 で CPU スケジューラを「後回しにしていい」と伝えます。監視スクリプトが本業のビルドを 1 秒でも遅延させてはいけません。

6. StandardOutPath と StandardErrorPath を同一ファイルに向ける

別ファイルにすると両方が毎実行で上書きされ、stdout と stderr を突き合わせるのが面倒になります。同じファイルに向けておくと「今朝のジョブがどう動いたか」が 1 ファイルで完結します。保持期間は 1 日分で十分です。

7. STATUS_FLAG は深刻度が増す方向にしか変えない

🟡 への昇格は「現在 🟢 のときだけ」、🔴 への昇格は無条件。一度付いた深刻なフラグは後のチェックで軽くなりません。複数の問題が重なったとき、最も深刻なアラートがテーブルの右端に残ることが、一目での判断に直結します。

8. 出力はテーブルと Warnings の 2 段構えにする

テーブルはリポジトリ数が増えても横幅が固定で把握できます。警告の詳細（何日 stale か、どのファイルが tracked か）をセルに詰め込むと列が崩れます。詳細は ## Warnings セクションに分離することで、「1 秒でパッと見る」用と「掘り下げる」用を分けます。

9. bash 3.2 で動くように書く

macOS の /bin/bash は bash 3.2 のままです。plist が /bin/bash -c を使う以上、declare -A（連想配列）も mapfile も使えません。改行区切りの文字列 + ワード分割 + printf "%b" で改行展開というシンプルな代替で、bash 3.2 でそのまま動きます。「制約があるほど単純になる」の好例です。

10. tr や sed を使う前に LC_ALL=C を付ける

マルチバイト文字（日本語のコミットメッセージなど）が混じると tr がバイト誤認識を起こします。LC_ALL=C tr '|' '/' でバイトモードに切り替えることで、Markdown テーブルのパイプ文字が文字化けで増殖する問題を防ぎます。

11. 算術展開の前に必ず空文字と数値ガードを置く

if [ -n "$LAST_COMMIT_TS" ] && [ "$LAST_COMMIT_TS" -gt 0 ] 2>/dev/null; then
    COMMIT_AGE_DAYS=$(( ($(date +%s) - LAST_COMMIT_TS) / 86400 ))
fi

set -u 環境では未定義変数がエラーになりますが、空文字の算術展開も同様にエラーです。trap 'exit 0' ERR と組み合わせると、ガードなしの算術展開が無音でスクリプトを終了させます。ガードは冗長に見えますが、fail-open スクリプトの必要コストです。

12. 日付別ログと latest の 2 本立てで参照を分ける

OUT="$LOG_DIR/project-health-${DATE_TAG}.md"
LATEST="$LOG_DIR/project-health-latest.md"
cp "$OUT" "$LATEST" 2>/dev/null || true

日付別は遡及確認用、latest は「今朝の状態を今すぐ読む」ためのショートカット。Claude Code のコンテキストや別スクリプトから参照するときは常に latest を読みます。|| true で cp 失敗をガードするのも fail-open 設計の延長です。

13. head -N で出力を必ず有界にする

.env チェックの | head -5 がその例です。異常状態で大量の行が返ってきたとき、出力が際限なく膨らんでログファイルを数百 MB にする事故を防ぎます。「正常時は 0 行のはずだが、もし大量に返ったら」という思考で各コマンドに上限を設けます。

14. スクリプト冒頭で mkdir -p を実行する

初回実行やクリーン環境への移植でログディレクトリが存在しない状態でも、最初の mkdir -p "$LOG_DIR" が保護します。「自分の環境では動いたが別のマシンに持って行ったら動かなかった」の典型原因を潰せます。

---

まとめ

この仕組みの核心を一言で言うと、「問題の発見を人間の注意力から切り離す」 ことです。

月商120万円の状態を維持できているのは、コードを書く量が増えたからではありません。会社都合で解雇されてゼロになった経験から学んだのは、「並走するプロジェクトは必ず腐敗する」という事実でした。人間が1つのプロダクトに集中している間、もう1つには誰も目を向けていません。.env の誤 tracking も、14日以上放置された stale commit も、気づいたときには「なぜこうなったか」を追う時間のほうが損失になります。

project-health.sh が毎朝 7:30 に走り、~/.claude/logs/project-health-latest.md に Markdown テーブルを落としておく。作業を始めるときにこのファイルを一瞥するだけで、すべてのリポジトリの状態を把握できます。スクリプトが壊れても trap 'exit 0' ERR が本業を守り、launchd の LowPriorityIO と Nice: 10 がビルドと競合しません。監視が本業の邪魔をしない、これが設計の全体方針です。

実装で最も重要な判断は、シンプルさを守り続けることでした。bash 3.2 の制約のおかげで連想配列を使えなかったことが、結果的に改行区切りの文字列というより単純な実装を選ばせました。python3 を JSON パースにだけ使い、その他は POSIX 準拠のシェルコマンドで完結させたことで、Homebrew の有無くらいしか環境依存がありません。複数のリポジトリを並走させる個人開発者にとって、「毎朝5秒で全体を把握できる状態」が生産性の土台です。

---

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

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

---

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

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

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