Claude Code の hooks で品質を底上げする 5 つの実用パターン

Claude Code の hooks は、エージェントが実行する Bash や Edit などのツール呼び出しに対して、前後で任意のコマンドを差し込める仕組みです。FIXIT の社内プロジェクトで実際に使い込んで「これは効く」と判断した 5 パターンを共有します。

1. PostToolUse で TypeScript ファイルを自動 format

Edit / Write 直後に prettier --write を走らせ、フォーマット差分が後の commit を汚さないようにする最も基本的な使い方です。

// ~/.claude/settings.json (抜粋)
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "filePattern": ".*\\.(ts|tsx)$",
        "command": "prettier --write \"$CLAUDE_FILE_PATH\"",
      },
    ],
  },
}

エージェントが書いたコードに対して、人間がレビューする前に format が揃った状態になります。lint-staged と二重がけになる場合は片方に統一して OK。

2. PreToolUse で危険コマンドを止める

rm -rf や git push --force など、復旧コストの高いコマンドはあらかじめ block しておくと安心です。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "patternMatch": "rm\\s+-rf|git\\s+push\\s+--force|git\\s+reset\\s+--hard",
        "action": "block",
        "message": "破壊的コマンドはユーザー確認後にのみ実行してください",
      },
    ],
  },
}

エージェントが「うっかり」やるリスクを構造的に潰せます。

3. PostToolUse で TypeScript の型チェックを軽く走らせる

大規模リポジトリで tsc --noEmit をフル実行すると遅いため、対象ファイルに絞った incremental check を hook で回す手があります。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "filePattern": ".*\\.(ts|tsx)$",
        "command": "tsc --noEmit --incremental \"$CLAUDE_FILE_PATH\" 2>&1 | head -20 || true",
      },
    ],
  },
}

エラーが出たらコンソールに表示するだけで block しない (|| true) ことで、AI の思考を止めずに型情報をフィードバックできます。

4. Stop hook で console.log 残しを検出

セッション終了直前に、変更ファイル全体で console.log が残っていないかを grep で検出します。

{
  "hooks": {
    "Stop": [
      {
        "command": "git diff --name-only | xargs grep -l 'console\\.log' 2>/dev/null || true",
      },
    ],
  },
}

production code に console.log が紛れ込むのを最後の砦で止めます。出力が空なら問題なし、ヒットしたらユーザーに見える形で報告されます。

5. PreToolUse で AI に「コミット前 textlint」を強制

校正パイプライン (textlint + prh.yml) を持っているプロジェクトでは、Bash で git commit を実行する直前に textlint を走らせるのが定型化できます。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "patternMatch": "git\\s+commit",
        "command": "npm run lint:text",
      },
    ],
  },
}

textlint が違反を出したら hook が non-zero で終了し、commit 自体が止まります。後追いで指摘されるより、commit 前に止まる方が修正コストが安い。

共通の注意点

• hooks は副作用が大きい ので、|| true で吸収するか、action: "block" で意図的に止めるかの設計を最初に決める
• filePattern と matcher の組み合わせ で対象を絞らないと、無関係なツール呼び出しでも実行されて遅くなる
• settings.json はチーム共有しない (個人設定) ことが多いので、リポジトリ標準にしたいルールは .claude/settings.json や README に書く

これらの hook はすべて、FIXIT 内のリポジトリで実プロジェクト運用しています。気になるパターンから 1 つずつ試して、合わなければ消す気軽さでお試しください。

関連

• 組織導入の全体像: Claude Code を実務に導入する完全ガイド
• AI 駆動開発の TDD ベストプラクティス: AI 駆動 TDD で品質を担保する