Claude CodeでHusky + lint-stagedを設定する: pre-commitで品質を守る実践ガイド

Claude Codeにまとめて修正を任せると、1回の作業で10個以上のファイルが動くことがあります。レビューで全部を目視するのは現実的ではなく、フォーマット漏れや未使用importのような小さな問題ほど見逃しやすくなります。

そこで役に立つのが、コミット前に機械的な品質チェックを必ず通す仕組みです。この記事では、Git hook、つまりGitが特定の操作前後に実行する小さなスクリプトを、Huskyでチーム共有し、lint-stagedでステージ済みファイルだけに絞って高速にチェックします。

HuskyはGit hookをリポジトリ内で管理しやすくするツールです。lint-stagedは、git add済みのファイルだけにESLintやPrettierを走らせるツールです。Claude Code hooksはClaude Codeのライフサイクルで動く自動化機能で、Git hookとは別物です。ここではまずGitのpre-commitを堅くし、必要に応じてClaude Codeにも同じルールを説明する、という順番で組み立てます。

全体像

Claude Codeに「品質チェックを追加して」と頼むだけでもコードは作れますが、設計を指定しないとpre-commitが重くなりがちです。私が実務で安定したと感じる分担は次の通りです。

flowchart LR
  A["Claude Codeが修正"] --> B["git addで対象を選ぶ"]
  B --> C["Husky pre-commit"]
  C --> D["lint-staged"]
  D --> E["ESLint / Prettier"]
  E --> F["commit"]
  C --> G["重い検査はpre-pushまたはCIへ"]

pre-commitは「数秒で終わる、変更ファイルに近い検査」に限定します。プロジェクト全体の型チェック、E2Eテスト、ビルドはpre-pushやCIに寄せます。ここを欲張ると、開発者が--no-verifyで回避し始め、仕組みそのものが形骸化します。

参考にした公式ドキュメントはHusky Get started、lint-staged README、Git hooks manual、Claude Code hooks referenceです。

まず動く最小構成

最初はHuskyとlint-stagedだけに絞ります。ESLintやPrettierをまだ入れていない場合は、先にClaude CodeでESLint設定を最適化するとClaude CodeでPrettier設定をカスタマイズするを整えてから進めると迷いません。

Claude Codeには、次のように「対象」「重さ」「成功条件」を明示して依頼します。

このNode.js/TypeScriptリポジトリにHuskyとlint-stagedを導入してください。
pre-commitではステージ済みのJS/TS/JSON/Markdown/CSSだけを対象にし、
ESLintの自動修正とPrettierを実行してください。
重い型チェック、テスト、ビルドはpre-pushまたはCIに分けてください。
変更後に、手動で確認するコマンドもREADME用に短くまとめてください。

手作業で入れるなら、基本コマンドはこれで十分です。

npm install --save-dev husky lint-staged eslint prettier
npx husky init

npx husky initは.husky/pre-commitを作り、package.jsonのprepareスクリプトも更新します。生成されたpre-commitの中身を、次のようにlint-stagedへ差し替えます。

#!/usr/bin/env sh
npx lint-staged

package.jsonには、まず小さくこの設定を入れます。既存のscriptsがある場合は、同じキーを上書きせずにマージしてください。

{
  "scripts": {
    "lint": "eslint .",
    "lint:fix": "eslint --fix .",
    "format": "prettier --write .",
    "format:check": "prettier --check .",
    "prepare": "husky"
  },
  "lint-staged": {
    "*.{js,jsx,ts,tsx}": [
      "eslint --fix --max-warnings=0",
      "prettier --write"
    ],
    "*.{json,md,mdx,yml,yaml,css,scss}": [
      "prettier --write"
    ]
  }
}

確認は、わざと整形されていないファイルを作ってから行います。

git add src/example.ts
npx lint-staged --debug
git commit -m "chore: verify pre-commit checks"

--debugを付けると、どの設定ファイルを読み、どのファイルを対象にしたかが見えます。Claude Codeに調査させるときも、この出力を貼ると原因の切り分けが速くなります。

実務向けlint-staged設定

リポジトリが育ってくると、package.jsonに長い設定を書くよりlint-staged.config.mjsへ分けた方が読みやすくなります。次の例は、ファイル名に空白が含まれても壊れにくいように引用符を付けています。

// lint-staged.config.mjs
const shellQuote = (file) => `"${file.replaceAll('"', '\\"')}"`;
const joinFiles = (files) => files.map(shellQuote).join(" ");

export default {
  "*.{js,jsx,ts,tsx}": (files) => [
    `eslint --fix --max-warnings=0 ${joinFiles(files)}`,
    `prettier --write ${joinFiles(files)}`,
  ],
  "*.{json,md,mdx,yml,yaml,css,scss}": (files) =>
    `prettier --write ${joinFiles(files)}`,
};

この形にしたら、package.json側のlint-stagedキーは削除します。設定が2か所にあると、Claude Codeも人間もどちらが正なのか迷います。

3つのユースケース

1つ目はTypeScriptアプリです。Claude Codeがコンポーネント、テスト、型定義を同時に触る場面では、ESLintの自動修正とPrettierだけでもレビュー前のノイズが大きく減ります。型チェックは全体を見ないと意味が薄いので、pre-commitではなくnpm run typecheckをpre-pushかCIへ置くのが無難です。

2つ目はAstroやNext.jsのブログです。MDX、JSON、CSSが混ざるため、記事本文の差分にフォーマット差分が混ざりやすくなります。lint-stagedでMDXとCSSを整えるだけで、レビュー時に「文章の変更」と「整形の変更」を分けやすくなります。

3つ目はモノレポです。全パッケージのテストをpre-commitで回すと遅くなりすぎます。まずは変更ファイルだけにPrettierとESLintをかけ、パッケージ単位のテストはCIのpaths条件やタスクランナーに任せます。Claude Codeには「pre-commitは高速、pre-pushは中程度、CIは完全検査」と説明しておくと、過剰なフックを作りにくくなります。

commit-msgとpre-pushも分けて考える

コミットメッセージをConventional Commitsに寄せたい場合は、commit-msgでcommitlintを使います。

npm install --save-dev @commitlint/cli @commitlint/config-conventional

// commitlint.config.mjs
export default {
  extends: ["@commitlint/config-conventional"],
  rules: {
    "subject-max-length": [2, "always", 72],
  },
};

#!/usr/bin/env sh
npx --no -- commitlint --edit "$1"

.husky/commit-msgに上の内容を置くと、feat: add settings pageのような形式を強制できます。一方で、ビルドやテストはpre-pushに逃がします。

#!/usr/bin/env sh
npm run validate

package.json側はこうしておくと、ローカルとCIのコマンドをそろえられます。

{
  "scripts": {
    "typecheck": "tsc --noEmit",
    "test:ci": "vitest run --coverage",
    "build": "vite build",
    "validate": "npm run typecheck && npm run lint && npm run format:check && npm run test:ci && npm run build"
  }
}

失敗例と落とし穴

よくある失敗は、pre-commitで全部を守ろうとすることです。npm run buildや全テストを毎回走らせると、コミット1回に数分かかります。品質を上げるつもりが、開発者に回避策を学習させてしまいます。

次に、部分ステージの扱いです。lint-stagedはステージ済み差分を対象にしますが、同じファイルに未ステージの変更が残っていると挙動を誤解しやすくなります。原因調査ではgit status --short、git diff --staged、npx lint-staged --debugの3つをセットで見ます。

Windows混在チームでは改行コードも落とし穴です。Huskyのフックはシェルスクリプトなので、LFで管理するのが安全です。

* text=auto eol=lf
*.cmd text eol=crlf
*.bat text eol=crlf

最後に、--no-verifyの扱いです。緊急修正で使う余地は残してよいですが、常用している人がいるならフックが重すぎるサインです。Claude Codeに直させるなら「失敗を握りつぶす」のではなく「失敗理由を短く出し、重い処理をpre-pushへ移す」と指示します。

Claude Codeに保守させるコツ

Claude Codeへ依頼するときは、フックだけでなく運用ルールも同時に書かせます。たとえば「pre-commitは5秒以内を目標」「失敗時に実行する確認コマンドをREADMEへ追記」「CIと同名のvalidateを作る」といった制約です。

Claude Code hooksを使う場合も、Git hookの代替ではなく補助として使います。たとえばClaude Codeの作業終了時にnpm run lintを提案させる、危険なシェルコマンドをブロックする、といった用途です。最終的にコミットを止める責任は、誰がコミットしても発火するGit hookとCIに置く方が安定します。

初心者向けにもう1つ付け加えるなら、最初から完璧なhookを作ろうとしないことです。まずPrettierだけを通し、次にESLint、最後にcommit-msgを足す順番なら、失敗したときの原因も追いやすくなります。

実際に試した結果

この記事の構成を小さなTypeScript/Viteプロジェクトに入れて、整形崩れ、未使用import、MDXのスペース崩れを混ぜて試しました。pre-commitは変更ファイルだけを処理するため体感で数秒に収まり、npx lint-staged --debugで対象ファイルも確認できました。型エラーはpre-commitでは拾わず、pre-pushのnpm run validateで止める設計にした方が、コミットのリズムを崩さずに運用できました。

まとめ

Husky + lint-stagedは、Claude Codeで増えた変更量を人間のレビューだけに背負わせないための現実的な防波堤です。pre-commitは軽く、pre-pushとCIは重く、Claude Codeにはその分担を明示する。この3点を守ると、フックは邪魔な儀式ではなく、チーム全員の作業を一定品質にそろえる足場になります。

次に進むなら、ESLint側のルールをESLint設定ガイドで固め、フォーマットはPrettier設定ガイドで統一してください。