🐢 --incremental で3倍遅くなった TypeScript フックを200KB閾値で直した話

大学在学中に月10万から始めて、掛け持ちで月60万まで積み上げ、会社都合の解雇で一度ゼロになった。そこから半年かけて Claude Code の自律環境を自分で組み上げ、今は月商120万で動いています。その過程でいちばん地味に時間を吸い取ったのが、「速くしようとして逆に遅くなった」バグの修正でした。

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

「作業している」と「環境が動いている」は別物

個人開発で月商を伸ばすうえで最初の壁になるのが、コードを書く速度ではなく検証のラグです。型エラーは書いた瞬間に気づけば直す手間は1分ですが、30秒後に気づけば前後の文脈を頭から引き出し直す必要がある。60秒後なら別の作業に移行しかけているので、切り替えコストがさらに乗ります。

Claude Code はツール実行後に PostToolUse フックを呼び出す仕組みを持っています。ここに tsc --noEmit を置けば、エージェントがファイルを編集するたびに型チェックが走り、エラーがあれば即座に次の指示へフィードバックが戻ります。「ファイルを書いたら自動で確認する」という動線を人間が介在せずに完結させる構造です。

問題は、プロジェクトが育つにつれてこの「即座に」が崩壊していくことです。

tsc のコールドスタートがなぜ重いのか

TypeScript のコンパイラは起動時に依存グラフ全体を読み込みます。ファイルが100個なら軽快でも、インポートが連鎖して実質的に参照するモジュールが数百に膨らめば、毎回ゼロから解析を走らせるコストは馬鹿になりません。closet-os というプロジェクトで実測したとき、コールドの tsc --noEmit は30〜60秒かかっていました。フックが毎ツール呼び出しごとに60秒ブロックする環境は、自律環境どころか作業を止める障害物です。

--incremental オプションはそれを解決するために存在します。初回だけ全解析を行い、結果を .tsbuildinfo ファイルへキャッシュする。2回目以降は差分だけを再解析するため、変更が小さければ 1〜3秒で終わります。フック向けには理想的な選択肢に見えました。

逆効果になるケース

ところが closet-os のフックに --incremental を入れたところ、コールド実行が 3.6倍遅くなりました。

原因は .tsbuildinfo ファイルの肥大化です。インクリメンタルビルドの差分情報は、プロジェクトが大きいほど初回キャッシュ生成に時間がかかります。さらに、キャッシュが蓄積されてファイルサイズが膨らむと、毎回その巨大なJSONを読み込むオーバーヘッドが無視できなくなります。「差分だけ処理する恩恵」を「重いキャッシュを毎回ロードするコスト」が上回った状態です。

小〜中規模プロジェクトではインクリメンタルが圧倒的に有利。しかし大規模プロジェクトでは通常の --noEmit の方が速い、という逆転が起きます。そしてフックはあらゆるプロジェクトで同じスクリプトを使い回すため、「プロジェクト規模に応じて自動で切り替わる仕組み」が必要になります。

閾値ガードという発想

キャッシュファイルのサイズは、プロジェクト規模と強く相関します。.tsbuildinfo が小さければインクリメンタルが効く、大きければ通常モードの方が速い。この観察から、「キャッシュファイルが200KBを超えたら通常モードにフォールバックする」という1行ガードに行き着きました。

閾値は実測で決めています。closet-os のキャッシュが遅くなり始めた時点でのサイズが200KB付近だったこと、それより小さいプロジェクトでは一貫してインクリメンタルが有利だったことの両方を確認した上での値です。マジックナンバーではなく、実測に基づいた境界線です。

---

全体の流れ

フックが動く全体像

Claude Code がファイルを編集 (PostToolUse)
        │
        ▼
post_tsc_check.sh 起動
        │
        ├─ tsconfig.json が無い → exit 0（即終了）
        │
        ├─ timeout コマンド解決
        │    ├─ gtimeout (GNU coreutils) があれば優先
        │    └─ なければ timeout / フォールバック
        │
        ├─ TSBUILDINFO のサイズ確認
        │    ├─ ファイル無し or ≤200KB → --incremental モード
        │    └─ >200KB             → 通常モード（フォールバック）
        │
        ├─ tsc 実行（timeout 60s）
        │    ├─ --incremental: --noEmit --pretty false --incremental --tsBuildInfoFile
        │    └─ 通常:           --noEmit --pretty false
        │
        ├─ rc=124 (timeout) → 警告メッセージ・exit 0
        └─ エラーあり → 型エラー表示・exit 0（エージェントはログを受け取る）

Claude Code のエージェントはフックの出力をそのまま次の推論に使えます。型エラーがあれば「=== TypeScript型エラー検出 ===」という接頭辞つきで出力されるため、エージェントが自分でエラーを読み取って修正ループに入ります。

実コード：サイズ判定から分岐まで

~/.claude/hooks/post_tsc_check.sh の核心部分を順番に読みます。

①キャッシュパスの定義

CACHE_DIR="node_modules/.cache"
[ -d "node_modules" ] && mkdir -p "$CACHE_DIR" 2>/dev/null
TSBUILDINFO="$CACHE_DIR/tsc-hook.tsbuildinfo"

.tsbuildinfo は node_modules/.cache/tsc-hook.tsbuildinfo に固定しています。プロジェクトルートに置かない理由は、.gitignore のスコープを node_modules/ でまとめて吸収できるからです。ファイル名も tsc-hook とアプリ本体のビルドキャッシュと名前空間を分けています。

②200KBガード

USE_INCREMENTAL=1
if [ -f "$TSBUILDINFO" ]; then
  SIZE=$(stat -f %z "$TSBUILDINFO" 2>/dev/null || echo 0)
  if [ "${SIZE:-0}" -gt 204800 ]; then
    USE_INCREMENTAL=0
  fi
fi

stat -f %z は macOS の stat でバイト数を取得する書き方です（Linux の stat -c %s に相当）。2>/dev/null || echo 0 でエラー時のゼロフォールバックを確保し、ファイルが存在しない初回でも安全に動きます。204800 は 200 × 1024 で200KBをバイト表現したものです。

③引数の組み立てと実行

if [ "$USE_INCREMENTAL" = 1 ]; then
  TSC_ARGS="--noEmit --pretty false --incremental --tsBuildInfoFile $TSBUILDINFO"
else
  TSC_ARGS="--noEmit --pretty false"
fi

if [ -n "$TIMEOUT_CMD" ]; then
  result=$($TIMEOUT_CMD npx tsc $TSC_ARGS 2>&1 | head -30)
  rc=$?
else
  result=$(npx tsc $TSC_ARGS 2>&1 | head -30)
  rc=$?
fi

--pretty false はカラーコードをオフにするためです。フックの出力はターミナルではなくエージェントのログに入るため、ANSIエスケープシーケンスが混入すると可読性が落ちます。head -30 でエラーが大量に出たときの出力爆発を防いでいます。

④timeout の macOS 対応

TIMEOUT_CMD=""
if command -v gtimeout >/dev/null 2>&1; then
  TIMEOUT_CMD="gtimeout 60"
elif command -v timeout >/dev/null 2>&1; then
  TIMEOUT_CMD="timeout 60"
fi

macOS の /usr/bin/timeout は存在しません（BSD 由来の timeout は Homebrew の coreutils に入っている gtimeout です）。command -v で存在確認してから代入し、どちらもなければ TIMEOUT_CMD="" のままにして timeout なしで動かします。この順序で書いておけば Linux・macOS・CI 環境すべてで同じスクリプトが動きます。

⑤timeout 判定

if [ "$rc" = 124 ]; then
  echo "=== TypeScript check timeout (60s exceeded — tsc 多重実行/巨大依存変更の疑い) ==="
  exit 0
fi

rc=124 は timeout / gtimeout がプロセスを kill したときの終了コードです。エラーではなく警告として扱い、exit 0 で返すことでエージェントの処理フローをブロックしません。メッセージに「多重実行の疑い」と書いているのは、Claude Code が並行してツールを実行したとき複数の tsc が同時に起動し、互いのキャッシュを壊し合うケースが実際に発生したためです。

なぜ exit 0 で返すのか

型エラーがあっても exit 0 で終わっています。exit 1 にするとフックが「失敗」扱いになり、Claude Code のツール実行自体が中断するケースがあります。型エラーはエージェントへの情報であって、フロー停止の条件ではありません。エラー内容を標準出力に書き出せば、エージェントは次のステップで「型エラーがあるから直す」という推論をします。エラー検出とフロー制御を分離する設計です。

実装の詳細（続き）

tsconfig.json チェックが最初の1行である理由

[ -f "tsconfig.json" ] || exit 0

スクリプトの冒頭はこの1行から始まります。PostToolUse フックはすべてのプロジェクトで呼び出されるため、TypeScript でないリポジトリでも発火します。tsconfig.json の存在確認を先頭に置けば、Python プロジェクトや Bash スクリプトだけのディレクトリでは即座に exit 0 で抜けます。

ポイントは「失敗したら終了」ではなく「tsconfig.json がないなら終了」という方向のチェックであることです。[ -f "tsconfig.json" ] は true のとき exit 0 を実行しない（|| の右辺は左辺が偽のときだけ評価される）。このワンライナーの読み方に慣れていないと後で混乱するので、最初に整理しておく価値があります。

出力ブロックの設計

if [ -n "$result" ]; then
  echo "=== TypeScript型エラー検出 ==="
  echo "$result"
  echo "================================"
fi
exit 0

フックが「何も出力しない」のはエラーがゼロのとき、つまり正常時です。型が全部通れば標準出力は空になり、エージェントのログにもノイズが乗りません。エラーがあるときだけ === TypeScript型エラー検出 === という接頭辞つきで出力されるため、エージェントは単純に「この文字列が出力に含まれているか」だけを見れば型エラーの有無を判断できます。

-n "$result" は文字列が空でないことのチェックです。型エラーがなければ tsc の出力は空文字列になるので、この条件は「型エラーあり = 出力あり」と等価に機能します。

2>&1 | head -30 の組み合わせ

result=$($TIMEOUT_CMD npx tsc $TSC_ARGS 2>&1 | head -30)

2>&1 は tsc がエラーを標準エラーに出すケースへの対応です。TypeScript のエラーは通常 stderr に出力されます。これを stdout と合流させないと $result には何も入りません。head -30 はエラーが爆発的に多いとき（型エラーが連鎖して数百行出るケースは珍しくない）にバッファが溢れないよう上位30行に絞る役割を持ちます。

30という数字に根拠はないかと言えばあります。closet-os の実際のエラーログを確認したところ、エラー内容の核心（ファイル名・行番号・メッセージ）は最初の数行に集中しています。エージェントが修正判断をするのに30行で十分でした。多すぎると1エラーで数百トークンを消費するため、フックのコスト効率が悪化します。

npx tsc を使う理由

直接 ./node_modules/.bin/tsc を叩くのではなく npx tsc にしています。理由はシンプルで、node_modules が存在しない状態（初回 npm install 前）でも npx がグローバルの tsc にフォールバックするためです。フックはプロジェクトのセットアップ状態に関係なく動く必要があります。ただし node_modules がある場合は npx もローカルを優先するため、バージョン差異は生じません。

スクリプト全体の行数

実ファイルは61行です。コメント・空行を除くと実質40行以下。「1000行より100行の明快さ」はこういう場所で体現できます。機能の核心が短ければ短いほど、後で別プロジェクトへ移植するときのコピペが楽になります。

---

私が詰まった話

以下はすべて実際に踏んだ失敗です。症状・原因・直し方の順で書きます。

①パイプを挟んだら rc が常に0になった

症状: tsc が型エラーを出しているのに、フックからエラーメッセージが一切返ってこない。echo "$result" をデバッグで入れると出力は正しく取れているのに rc が 0 のまま。

原因: 最初の実装では以下のように書いていました。

result=$(npx tsc $TSC_ARGS 2>&1 | head -30)
rc=$?

$? が取るのは直前のコマンドの終了コードです。パイプで繋いだ場合、$? は head の終了コードを返します。head -30 は常に成功（終了コード0）するため、tsc がどれだけエラーを出していても rc=0 になり続けていました。

直し方: パイプを使わず、出力をいったん全部受けてから head に通す方法を検討しましたが、大量エラー時のバッファ問題があります。現在は変数を二段にしています（result に head 済みの出力を入れ、rc はパイプ直後ではなく timeout コマンドの終了コードを見る形）。実際のスクリプトを見ると rc=$? が | head -30 の後ではなく、代入式全体の後にあります。シェルの動作として、コマンド置換 $(...) の終了コードはパイプの最後のコマンドです。timeout / gtimeout はタイムアウト時にのみ 124 を返し、それ以外は tsc の終了コードをそのまま透過します。つまり timeout を挟むことで、パイプの中にいるのは head だけになり、timeout が tsc のコードを持ち出す構造になっています。

result=$($TIMEOUT_CMD npx tsc $TSC_ARGS 2>&1 | head -30)
rc=$?
# この rc は timeout コマンド全体の終了コード
# timeout が tsc を wrap しているので、tsc の rc が透過される
# (ただし timeout 自体の rc=124 がタイムアウトを示す)

最初は timeout を使っていなかったのでこのトラップにはまりました。timeout の追加がパイプ問題の副次的な解決にもなっていたことに、後から気づきました。

② macOS の stat でサイズ取得に失敗した

症状: 200KBガードを実装したが、どんな状態でも USE_INCREMENTAL=1 から変わらない。tsbuildinfo が明らかに数MBに育っているのにフォールバックしない。

原因: Linux のコマンドリファレンスを見て stat -c %s と書いていました。

# 間違い（Linux 用）
SIZE=$(stat -c %s "$TSBUILDINFO" 2>/dev/null || echo 0)

macOS の stat は BSD 系で、オプションが全く異なります。-c %s は macOS では無効なオプションとして扱われ、エラーが返ります。2>/dev/null でエラーを捨てているため echo 0 が実行され、常にサイズ0と判定されていました。

直し方: macOS 用の書き方は -f %z です。

SIZE=$(stat -f %z "$TSBUILDINFO" 2>/dev/null || echo 0)

-f はフォーマット文字列を指定するオプションで、%z がファイルサイズ（バイト）を返します。Linux の -c %s と意味は同じですが、フラグが異なります。

これを発見するのに man stat を読む必要があって、30分溶かしました。最初から wc -c < "$TSBUILDINFO" にしておけばよかったとも思いますが、wc -c はファイルを全読みするので大きなファイルでわずかに遅く、またファイルが存在しないときのエラーハンドリングが追加で要ります。stat の方がファイルシステムのメタデータだけを読むので速く、2>/dev/null || echo 0 のパターンで不在時の安全処理も1行で書けます。

③ exit 1 にしていてエージェントが止まった

症状: 型エラーを検出したフックが走るたびに、Claude Code のツール実行ループが途中で中断する。エラーが出ていることはわかるが、エージェントが「修正しよう」と推論を始める前にループが終わってしまう。

原因: 最初の実装では型エラー時に exit 1 を返していました。Claude Code は PostToolUse フックが非ゼロの終了コードを返すとツール実行を「失敗」扱いにし、以降のステップを続けないケースがあります。

直し方: フックの役割を「フロー制御」ではなく「情報通知」に限定する設計に切り替えました。型エラーはエージェントへの入力情報であって、処理を止める理由ではありません。エラー内容を stdout に書き出して exit 0 で返すことで、エージェントは情報を受け取りながら処理を続け、「この型エラーを直す」という次のアクションへ自律的に進みます。

「フックは情報チャンネル、制御チャンネルではない」と意識を切り替えてから、設計がすっきりしました。

④ ANSI エスケープコードがエージェントのコンテキストを汚染した

症状: エージェントが型エラーのログを受け取っているはずなのに、エラー内容を正確に読み取れず、的外れな修正を出してくる。エラーメッセージを自分でターミナルに貼り付けると ^[[1m^[[31merror^[[0m のような謎文字列が混入している。

原因: --pretty false を入れていなかった時期があります。TypeScript のデフォルトは色付き出力で、ターミナルでは赤いエラー文字で表示されますが、実体は ANSI エスケープシーケンスです。これがフックの出力に混入すると、エージェントが受け取るテキストが人間が読んだものと異なります。LLM はエスケープシーケンスの解釈が安定しておらず、「error という単語があるはずの位置」に制御コードが挟まって認識を阻害していました。

直し方:

TSC_ARGS="--noEmit --pretty false ..."

--pretty false を引数に加えるだけです。これで tsc の出力がプレーンテキストになります。フックや CI 環境では常に --pretty false を入れる、と覚えておくとよいです。ターミナル出力は人間が読むためのもので、プログラムが処理する出力には不要です。

⑤ 多重起動で .tsbuildinfo が壊れた

症状: フックを有効にしてしばらく使っていたら、突然 tsc が Cannot read file 'node_modules/.cache/tsc-hook.tsbuildinfo' というエラーを出すようになった。ファイルを削除してリトライすると直るが、数時間後にまた壊れる。

原因: Claude Code は複数のツールを並行実行することがあります。エージェントが「ファイルAを書く」「ファイルBを書く」を同時に発行すると、両方の PostToolUse フックが同時に起動します。2つの tsc --incremental プロセスが同じ tsc-hook.tsbuildinfo ファイルに同時書き込みを試みると、ファイルが中途半端な状態で壊れます。

直し方: 現状のスクリプトでは完全な排他制御（flock 等）は入れていません。代わりに 60 秒の timeout で「長時間 tsc が複数走ったら OS に reap させる」という方針にしています。コメントにも # 並行 hook 実行による多重 tsc を防止 と書いてあります。

完璧な解は flock を使うことです。

(
  flock -x 200
  # tsc 実行
) 200>"$TSBUILDINFO.lock"

ただしこれを入れると macOS 環境での動作確認が増えます（BSD の flock と GNU の flock は挙動が異なる）。現状の運用では .tsbuildinfo が壊れたら削除すれば次回から自動再生成されるため、timeout による緩やかな対策で許容しています。精度より運用の単純さを優先した判断です。

tsbuildinfo が壊れても Claude Code 自体は止まりません。フックが型エラーなしで返れば次のステップへ進みます。最悪でも「型チェックがその1回だけスキップされる」という影響にとどまります。致命的でないエラーに対してコードを複雑化させる必要はない、という判断基準の実例です。

つまずきポイント（導入〜運用で実際に踏んだ地雷）

中段では「パイプで rc が常に0」「macOS stat の書き方違い」「exit 1 でエージェントが止まった」「ANSI コード汚染」「並行起動による tsbuildinfo 破損」の5つを解説しました。ここではそれ以外で詰まりやすい箇所を一気に並べます。

• chmod +x を忘れるとフックがサイレント無視される
  スクリプトを配置しただけでは動きません。chmod +x ~/.claude/hooks/post_tsc_check.sh で実行権限を付けるまで、Claude Code はフックを静かにスキップします。エラーも警告も出ないため「フックを設定したのに型チェックが返ってこない」という状態が続きます。確認は ls -la ~/.claude/hooks/ で rwxr-xr-x になっているかを見るだけです。これが導入初日に最も多い詰まり原因です。

• シェバンを #!/bin/sh にすると bash 構文が通らない場面がある
  ${SIZE:-0} のパラメータ展開や command -v は /bin/sh でも動きますが、スクリプトを発展させるときに bash 限定の構文を足した途端に壊れます。実ファイルの1行目が #!/bin/bash になっているのはそのためです。最初から #!/bin/bash にしておくのが安全です。

• カレントディレクトリがプロジェクトルートでない場合、tsconfig.json チェックが空振りする
  PostToolUse フックはエージェントがツールを実行した時点の cwd で起動します。エージェントが packages/api/src/foo.ts を編集していて cwd が packages/api/ になっていれば問題ありませんが、ルートのままであればサブパッケージの tsconfig.json を見つけられずに即 exit 0 で抜けます。モノレポ構成では期待する tsconfig のパスを --project で明示するか、フックの先頭で cd "$(git rev-parse --show-toplevel)" してルートへ移動してから実行する補強が必要です。

• モノレポで tsc が想定外の tsconfig.json を拾う
  packages/ 以下に複数の tsconfig.json が分散していると、cwd に応じてどれが参照されるかが変わります。ルートの tsconfig を使うつもりが、サブパッケージの tsconfig を拾って型エラーの検出範囲がずれるケースが発生します。TSC_ARGS に --project $(pwd)/tsconfig.json のように絶対パスで指定するか、フックをモノレポ対応で別途作るかの2択です。

• --noEmit を落とすと js ファイルが毎フック実行で生成される
  インクリメンタルの引数を手動調整するとき --noEmit を消してしまうと、tsc が .js を書き出します。フックのたびにビルド成果物が上書きされ、git status が汚染されます。さらにエージェントが「ファイルが変わった → フック発火 → js を生成 → ファイルが変わった…」の無限ループに入ることもあります。--noEmit は引数テンプレートの先頭に固定で書いてください。

• TSBUILDINFO のパスに空白が入ると引数が分割される
  --tsBuildInfoFile $TSBUILDINFO でクォートが抜けていると、プロジェクトパスに空白が含まれた瞬間に tsc に渡る引数が分割されてエラーになります。実スクリプトのままクォートなしで書いている場合、パスに空白が入った環境では --tsBuildInfoFile "$TSBUILDINFO" にダブルクォートを追加する必要があります。

• npx の起動コストが高頻度セッションで積み上がる
  npx tsc は実行前に毎回 node_modules/.bin/tsc の存在を解決します。解決処理自体は 0.1〜0.3 秒程度ですが、エージェントが1セッション中に数十ファイルを編集する場合は積み上がります。node_modules が確実に存在する環境では ./node_modules/.bin/tsc に直接パスを通す選択肢があります。ただし node_modules がない初回セットアップへの耐性が落ちるため、CI と共用するスクリプトには向きません。

• CI 環境で gtimeout も timeout も存在しない
  Alpine Linux などの最小イメージには timeout が入っていないことがあります。TIMEOUT_CMD="" のまま 60 秒の打ち切りなしで tsc が走ります。CI の型チェックは専用ジョブで管理するのが一般的ですが、同じスクリプトを CI でも使う場合は RUN apk add --no-cache coreutils などで timeout を事前にインストールしてください。

• head -30 でエラーが途中で切れてエージェントが根本原因を見失う
  型エラーが連鎖するプロジェクトでは最初の30行に核心が集中しますが、循環参照のエラーなど「後ろに根本原因がある」ケースでは30行では足りないことがあります。そのときはフック出力を /tmp/tsc-last.log に tee で残し、エージェントに cat /tmp/tsc-last.log で全量を読ませる補助フックを組み合わせる方法が有効です。フック本体はシンプルに保ち、情報が足りない局面は別チャンネルで補う分離の発想です。

• 200KB 閾値をすべてのプロジェクトに一律適用してしまう
  200KB は closet-os という特定プロジェクトの実測から導いた値です。プロジェクト規模・依存ツリーの深さ・マシンスペックが変われば逆転ポイントも変わります。次のコマンドで自分のプロジェクトの実数を取ってください。

  ls -lh node_modules/.cache/tsc-hook.tsbuildinfo  # キャッシュの現サイズ
  time npx tsc --noEmit                             # 通常モードの実測
  time npx tsc --noEmit --incremental \
    --tsBuildInfoFile node_modules/.cache/tsc-hook.tsbuildinfo  # インクリメンタルの実測
  

  2回目以降のインクリメンタルが「通常モードより遅い」時点のキャッシュサイズを閾値にすれば、あなたのプロジェクト固有の境界値が出ます。

---

ベストプラクティス

実装と失敗を繰り返して固まった「最初からこうしていればよかった」原則を列挙します。

1. tsconfig.json チェックを1行目に書く

[ -f "tsconfig.json" ] || exit 0

非 TypeScript プロジェクトでのフック起動コストをゼロにする防衛線です。後続のすべての処理の前提条件になるため、必ず最初の1行に置きます。

2. --noEmit --pretty false は両方セットで外さない

--noEmit はファイル生成を防ぎ、--pretty false は ANSI エスケープコードを排除します。フック出力はエージェントへの入力になるため、機械が処理するテキストにカラーコードは不要です。この2オプションを引数テンプレートから外すと、どちらも静かに問題を起こします。

3. 常に exit 0 で返す

フックの仕事は「情報を渡すこと」であって「処理を止めること」ではありません。型エラーを exit 1 で返した瞬間、フックは検査ツールから障害物に変わります。エラー内容を標準出力に書いて exit 0 で返すことで、エージェントは情報を受け取りながら自律的に修正ループへ進みます。

4. 2>&1 | head -30 はセットで使う

tsc のエラーは stderr に出ます。2>&1 で stdout に合流させないと $result に何も入りません。head -30 はエラーが数百行に爆発したときのバッファ保護です。どちらか片方だけでは不完全です。

5. timeout の存在確認は gtimeout → timeout → なし の順で

TIMEOUT_CMD=""
if command -v gtimeout >/dev/null 2>&1; then
  TIMEOUT_CMD="gtimeout 60"
elif command -v timeout >/dev/null 2>&1; then
  TIMEOUT_CMD="timeout 60"
fi

macOS に /usr/bin/timeout はありません。この順序で command -v 確認してから代入すれば、同じスクリプトが Linux・macOS・CI で動きます。

6. rc=124 は型エラーと別扱いにする

timeout/gtimeout が kill したときの終了コードは 124 です。これは「tsc が止まらなかった」という情報であり、型エラーとは意味が異なります。専用のメッセージを出して exit 0 にすることで、並行起動の疑いをエージェントへ伝えながらフローを継続できます。

7. .tsbuildinfo は node_modules/.cache/ に固定する

TSBUILDINFO="node_modules/.cache/tsc-hook.tsbuildinfo"

プロジェクトルートに置くと .gitignore のメンテが増えます。node_modules/.cache/ は多くのプロジェクトで既に除外されているため追加設定不要です。ファイル名を tsc-hook と固有にしてアプリ本体のビルドキャッシュと名前空間を分けるのも重要です。

8. 200KB ガードの閾値は自プロジェクトで実測してから設定する

stat -f %z で現在のキャッシュサイズを確認し、time npx tsc と time npx tsc --incremental を比較して逆転ポイントを自分で出します。マジックナンバーを流用せず、実測した境界値を 204800（200KB）の代わりに入れてください。

9. macOS の stat は -f %z を使う

Linux 用の -c %s は macOS では無効です。2>/dev/null || echo 0 と組み合わせることで、ファイル不在時のゼロフォールバックも1行で書けます。Linux・macOS 両対応が必要なら wc -c < でも取れますが、大きなファイルで全読みが走るため stat の方が若干速いです。

10. 導入したら必ず手動実行で動作確認する

cd /path/to/your/project
bash ~/.claude/hooks/post_tsc_check.sh

Claude Code 経由より先に手動で叩きます。権限・パス・stat オプション・tsconfig.json の検出—この1コマンドで全部見つかります。Claude Code 越しにデバッグするより圧倒的に速いです。確認後に問題がなければ本番フックとして有効化します。

11. 大きな依存変更の前後はフックを一時無効化する

package.json に新ライブラリを追加した直後は tsc が全解析を走らせ、フックが 30〜60 秒ブロックします。そういう局面では chmod -x ~/.claude/hooks/post_tsc_check.sh で一時無効化し、npm install && npx tsc --noEmit で自分で確認してから再度 chmod +x に戻す判断が正しいです。全自動に固執せず、局面に応じてフックを切り替える柔軟さが運用の安定につながります。

12. スクリプトは 61 行以内に収める

実ファイルはコメント込みで 61 行です。機能を追加するたびに行数は伸びますが、「フックの仕事はチェックして報告するだけ」という責任境界を守れば膨らみません。処理が複雑になるなら、フックではなく別の専用スクリプトに切り出すサインです。「1000行より100行の明快さ」はこの規模で体現できます。

---

まとめ

作ったのは 61 行のシェルスクリプトです。それだけで closet-os のフック実行時間は「コールド 3.6 倍遅化」から「差分 1〜3 秒」に変わりました。

ポイントは3行に収まります。

1. --incremental は大規模プロジェクトで逆効果になる。.tsbuildinfo のサイズが指標で、closet-os では 200KB 付近が逆転点でした。
2. stat -f %z で取ったサイズが 204800（200KB）を超えたら通常モードへ自動フォールバックする1行ガードで解決します。
3. フックは「情報チャンネル」であって「制御チャンネル」ではない。常に exit 0 で返し、型エラーは標準出力でエージェントへ渡します。

この構造が動いていると、Claude Code が型エラーを埋め込むたびに「=== TypeScript型エラー検出 ===」というフィードバックが返り、エージェントが自律的に修正ループを回します。人間が型エラーに気づくラグはゼロです。月商120万の自律環境を支える地味な部品のひとつですが、地味だからこそ何ヶ月も安定して動き続けています。

もし今 closet-os と同規模のプロジェクトで --incremental が重いと感じているなら、まず ls -lh node_modules/.cache/tsc-hook.tsbuildinfo を叩いてください。200KB を超えていれば、今日から直せます。

---

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

---

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

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

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