Claude Code Stop Hook：「完了」の前にテストする

Claude Codeが「完了」と返しても、テスト実行や成果物の作成は保証されません。Stop Hookなら、ターン終了前に短いローカル確認を実行できます。ただしCIや完全なテスト戦略の代わりにはなりません。

最小構成

.claude/settings.jsonのStopイベントから./scripts/check-before-stop.shを短いtimeoutで呼びます。スクリプトでは対象テストとdist/app.jsなどの成果物を確認します。

成功時は0、失敗時はstderrへ短い理由を書いて2を返します。Claude Codeでは終了コード2がStopをブロックし、理由をClaudeへ渡します。1は通常、終了を止めないhookエラーです。

{
  "hooks": {
    "Stop": [{
      "hooks": [{
        "type": "command",
        "command": "./scripts/check-before-stop.sh",
        "timeout": 30
      }]
    }]
  }
}

chmod +x scripts/check-before-stop.sh

Stop Hookはターン終了時に確認を実行します。CLAUDE.mdはルールを説明するだけで、コマンドは実行しません。CIは独立して動き、最終ゲートになります。

npm test -- --runInBand >/dev/null 2>&1 || { echo "Stop blocked: npm test" >&2; exit 2; }
test -s dist/app.js || { echo "Stop blocked: dist/app.js missing" >&2; exit 2; }
exit 0

実際の動作確認

1. わざと存在しないパスを指定し、手動実行で2を確認します。
2. Claude Codeで小さなタスクを実行し、Stopが止まり短い理由が表示されることを確認します。
3. テストまたはパスを直して再実行し、0で終了できることを確認します。
4. stop_hook_activeがtrueなら無意味なretryを追加せず、示された確認を直すかセッションを止めてhookを修正します。

API Key、.env、完全なログは出力しません。API利用はBetterTokenのClaude Code手順で確認できます。