Husky lint-staged with Claude Code

Gitフックでコード品質を自動担保する

HuskyはGitフックを簡単に管理するツール、lint-stagedはステージされたファイルのみを対象にlintやフォーマットを実行するツールです。この2つを組み合わせることで、コミット前にコード品質を自動チェックし、問題のあるコードがリポジトリに入るのを防ぎます。

セットアップ

Claude Codeにセットアップを依頼しましょう。

> Husky + lint-stagedをセットアップして。
> ESLint、Prettier、型チェック、テストのコミット前チェックを含めて。

# パッケージのインストール
npm install -D husky lint-staged

# Huskyの初期化
npx husky init

// .husky/pre-commit
npx lint-staged

// package.json
{
  "lint-staged": {
    "*.{ts,tsx}": [
      "eslint --fix --max-warnings 0",
      "prettier --write"
    ],
    "*.{js,jsx,mjs,cjs}": [
      "eslint --fix",
      "prettier --write"
    ],
    "*.{json,md,yml,yaml}": [
      "prettier --write"
    ],
    "*.css": [
      "prettier --write"
    ]
  }
}

型チェックの追加

ステージされたファイルに影響する型エラーをチェックするフックです。

// .husky/pre-commit
#!/usr/bin/env sh

# lint-staged（ESLint + Prettier）
npx lint-staged

# TypeScript型チェック（プロジェクト全体）
npx tsc --noEmit --pretty

型チェックはファイル単位では意味がないため、プロジェクト全体に対して実行します。大規模プロジェクトでは時間がかかることがあるため、CIに任せる判断もあります。

コミットメッセージの検証

conventional commitsに準拠したコミットメッセージを強制するフックです。

# commitlintのインストール
npm install -D @commitlint/cli @commitlint/config-conventional

// commitlint.config.mjs
export default {
  extends: ["@commitlint/config-conventional"],
  rules: {
    "type-enum": [
      2,
      "always",
      [
        "feat",
        "fix",
        "docs",
        "style",
        "refactor",
        "perf",
        "test",
        "build",
        "ci",
        "chore",
        "revert",
      ],
    ],
    "subject-max-length": [2, "always", 72],
    "body-max-line-length": [2, "always", 100],
  },
};

// .husky/commit-msg
npx --no -- commitlint --edit ${1}

高度なlint-staged設定

ファイルパターンに応じて異なる処理を実行する設定です。

// lint-staged.config.mjs
export default {
  // TypeScript/JSXファイル
  "*.{ts,tsx}": (filenames) => {
    const files = filenames.join(" ");
    return [
      `eslint --fix --max-warnings 0 ${files}`,
      `prettier --write ${files}`,
      // 変更ファイルに関連するテストを実行
      `vitest related --run ${files}`,
    ];
  },

  // スタイルファイル
  "*.{css,scss}": ["prettier --write"],

  // Prismaスキーマ
  "prisma/schema.prisma": () => [
    "npx prisma format",
    "npx prisma validate",
  ],

  // パッケージファイル
  "package.json": ["npx sort-package-json"],
};

プッシュ前のチェック

プッシュ前にビルドとテストを実行するフックです。

// .husky/pre-push
#!/usr/bin/env sh

echo "プッシュ前チェックを実行中..."

# ビルドチェック
npm run build

# テスト実行
npm run test:ci

echo "すべてのチェックに合格しました"

CI/CDとの連携

ローカルのフックとCIのチェックを整合させる設定です。

// package.json
{
  "scripts": {
    "lint": "eslint .",
    "lint:fix": "eslint --fix .",
    "format": "prettier --write .",
    "format:check": "prettier --check .",
    "typecheck": "tsc --noEmit",
    "test": "vitest",
    "test:ci": "vitest run --coverage",
    "validate": "npm run typecheck && npm run lint && npm run format:check && npm run test:ci",
    "prepare": "husky"
  }
}

トラブルシューティング

よくある問題と対処法です。

# フックが実行されない場合
chmod +x .husky/pre-commit
chmod +x .husky/commit-msg

# git hooksのパスを確認
git config core.hooksPath

# lint-stagedのデバッグ
npx lint-staged --debug

# 一時的にフックをスキップ（緊急時のみ）
git commit --no-verify -m "hotfix: 緊急修正"

// Windowsでの改行コード問題への対処
// .gitattributes
// * text=auto eol=lf
// *.{cmd,bat} text eol=crlf

チーム導入のポイント

• 段階的に導入する - まずPrettierだけ、次にESLint、最後に型チェックと段階的に追加
• CI と一致させる - ローカルフックとCIで同じチェックを実行する
• パフォーマンスを意識する - コミットが遅くなりすぎないよう、重いチェックはCIに委ねる
• ドキュメント化する - セットアップ手順と--no-verifyの使用ルールを共有する

まとめ

Husky + lint-stagedの組み合わせは、コード品質を自動で担保するための基本的かつ効果的な仕組みです。Claude Codeを活用すれば、セットアップからカスタムフック作成、トラブルシューティングまで効率的に対応できます。

ESLintの設定はESLint設定最適化ガイドを、Prettierの設定はPrettier設定カスタマイズガイドを参照してください。Husky公式ドキュメントも確認しておきましょう。