shared-tooling-git-hooks

Git フック

クイックガイド： Git フックには Husky v9 を使用し、"prepare": "husky" を設定します（"husky install" ではありません）。ステージ済みファイルのみを対象に lint-staged v16 で lint を実行します。従来形式のコミットメッセージには commitlint を使用します。pre-commit フックは 10 秒未満で完了するようにしてください。CI／本番環境では HUSKY=0 を設定します。

---

<critical_requirements>

重要：このスキルを使用する前に

すべてのコードは CLAUDE.md のプロジェクト規約（ケバブケース、名前付きエクスポート、インポート順序、import type、名前付き定数）に従う必要があります

（package.json では "prepare": "husky" を必ず使用してください。非推奨の "husky install" は使用しないでください）

（lint-staged を使ってステージ済みファイルのみを必ず lint してください。pre-commit でコードベース全体を lint することは絶対に避けてください）

（フックを無効にするため、CI／本番環境では必ず HUSKY=0 を設定してください）

（.husky/ ディレクトリには必ず通常のフックファイルを使用してください。v9 では shebang 行や husky.sh の読み込みは不要です）

（pre-commit フックは必ず 10 秒未満で完了するようにしてください。時間のかかるタスクは pre-push または CI に移してください）

</critical_requirements>

---

自動検出： Husky、husky init、.husky/、pre-commit フック、lint-staged、commitlint、従来形式のコミット、commit-msg フック、Git フック、prepare スクリプト

使用する場合：

• Husky + lint-staged を使って pre-commit フックを設定する
• commitlint を使ってコミットメッセージの検証を設定する
• Husky v8 から v9 に移行する
• モノレポ環境で Git フックを設定する
• CI／本番環境でフックを無効にする

使用しない場合：

• Linter／フォーマッター自体の設定（別の目的です）
• CI/CD パイプラインの設定（別の目的です）
• 実行時のアプリケーションコード（これは開発者向けワークフローツールのみを対象とします）

対象となる主なパターン：

• Husky v9 のセットアップとフックの作成
• lint-staged v16 の設定パターン
• commitlint と従来形式のコミット
• CI／本番環境でのフックの無効化
• モノレポのセットアップ
• Husky v8 から v9 への移行

詳細なリソース：

• examples/core.md - セットアップ、lint-staged の設定、commitlint、CI 対応、モノレポ、移行
• reference.md - 判断の枠組み、ツールの比較、アンチパターン

---

基本方針

Git フックは開発者向けのワークフローツールです。素早く動作し、作業を妨げないまま問題を早期に検出します。目標は、ステージ済みファイルのみを対象に、10 秒未満でフィードバックを返すことです。フックは任意のインフラであり、多くのプロジェクトではフックがなくても問題なく開発できます。

Git フックを使用する場合：

• コード品質のチェックによって CI の失敗を防ぐチームプロジェクト
• 確立済みの lint／フォーマット規則を適用するプロジェクト
• コードが CI に到達する前に素早くフィードバックを得たい場合
• lint を全体に実行すると時間がかかりすぎるモノレポ

使用しない場合：

• lint を必ず実行すると自分で覚えている個人プロジェクト（利点なしに負担が増えます）
• lint／フォーマット規則がまだ確立されていないプロジェクト（まず lint を設定してください）
• pre-commit フックに 10 秒以上かかる場合（代わりに CI に移してください）
• フックが価値をもたらさず、煩わしさだけを増やす CI 専用プロジェクト

---

主なパターン

パターン 1：Husky v9 のセットアップ

Husky v9 では、.husky/ ディレクトリ内の通常のシェルスクリプトを使用します。shebang 行は不要です。prepare スクリプトによって、チームメンバー全員にフックが自動でインストールされます。

# Full setup in 4 commands
bun add -D husky
bunx husky init       # Creates .husky/ and adds "prepare": "husky" to package.json
bun add -D lint-staged
echo "bunx lint-staged" > .husky/pre-commit

ポイント：

• "prepare": "husky" を設定します（"husky install" は非推奨で、v10 では動作しなくなります）
• フックファイルは通常のシェルスクリプトです（v9 では shebang は不要です）
• HUSKY=0 でフックを無効にし（CI／本番環境）、HUSKY=2 でデバッグモードを有効にします
• v9.1.1+ では、npx／bunx を使わずにパッケージのコマンドを直接実行できます

完全なセットアップと package.json の設定については、examples/core.md を参照してください。

---

パターン 2：lint-staged を使ったプレコミットフック

lint-staged v16 は、ステージング済みのファイルに対してのみコマンドを実行します。グロブの照合には picomatch を使用します（micromatch に置き換えられました）。

// lint-staged.config.mjs
export default {
  "*.{ts,tsx}": ["eslint --fix", "prettier --write"],
  "*.{css,scss}": ["prettier --write"],
};

型チェックには関数構文が必要です（ステージング済みのファイルだけでなく、すべてのファイルを対象に実行します）。

// lint-staged.config.mjs — with type checking
export default {
  "*.{ts,tsx}": ["eslint --fix", "prettier --write"],
  "*.{ts,tsx,js,jsx}": () => "tsc --noEmit",
};

メリット： ステージング済みのファイルのみを対象にし、自動修正で手作業を減らし、すばやくフィードバックを得られます。

v16 の破壊的変更： --shell フラグが削除されました（代わりにシェルスクリプトを使用してください）。Node.js 20.18 以降が必要です。

複数のファイル形式のパターンと v16 への移行については、examples/core.md を参照してください。

---

パターン 3：Conventional Commits を使った commitlint

commitlint v20 以降はコミットメッセージを検証します。ESM ネイティブのため、設定ファイルの拡張子には .mjs を使用してください。

bun add -D @commitlint/cli @commitlint/config-conventional

# .husky/commit-msg
bunx commitlint --edit $1

// commitlint.config.mjs (MUST be .mjs for Node v24 compatibility)
export default {
  extends: ["@commitlint/config-conventional"],
};

形式：type(scope): description。タイプ：feat、fix、docs、refactor、test、chore など。

v20 の変更点と高度な設定については、examples/core.md を参照してください。

---

パターン 4：CI／本番環境での処理

フックを実行すべきでない環境では、Husky を無効にします。

# CI pipelines
HUSKY=0 npm install

# GitHub Actions
env:
  HUSKY: 0

理由： 本番環境に devDependencies がインストールされていない場合に、フックのインストールが失敗するのを防ぎます。

条件付きの prepare スクリプトの代替案については、examples/core.md を参照してください。

---

パターン 5：モノレポの設定

リポジトリのルートに package.json がないモノレポ向けです。

// apps/frontend/package.json
{
  "scripts": {
    "prepare": "cd ../.. && husky apps/frontend/.husky"
  }
}

要点： リポジトリのルートに移動してから、Husky に .husky/ ディレクトリのパスを渡します。

---

パターン 6：Husky v8 から v9 への移行

手順：prepare スクリプトを更新し、フックファイルから shebang と husky.sh の読み込みを削除し、.husky/.gitignore を削除し、使用している場合は pinst を削除します。

重要： 非推奨の shebang #!/usr/bin/env sh と husky.sh の読み込みを含むフックは、v10.0.0 で失敗します。今すぐ移行してください。

移行手順の全容については、examples/core.md を参照してください。

---

<decision_framework>

判断基準

プレコミットで実行するもの

What to run pre-commit?
├─ Fast (< 10 seconds)?
│   ├─ Lint with auto-fix → YES (lint-staged)
│   ├─ Format → YES (lint-staged)
│   └─ Type check (--noEmit) → YES (lint-staged)
└─ Slow (> 10 seconds)?
    ├─ Full test suite → NO (pre-push or CI)
    ├─ Full build → NO (CI)
    └─ E2E tests → NO (CI)

タスクに応じたフックの選択

Which Git hook?
├─ Before committing? → pre-commit (lint-staged)
├─ Validating commit message? → commit-msg (commitlint)
├─ Before pushing? → pre-push (type check, unit tests)
├─ Before merging? → pre-merge-commit (v9.1.5+)
└─ After checkout/merge? → post-checkout / post-merge (install deps)

プレコミットの所要時間の目安

タスク	時間	プレコミットで実行するか
lint-staged（ステージング済みのファイルのみ）	< 5s	はい
コードのフォーマット	< 2s	はい
型チェック（--noEmit）	< 10s	はい
テストスイート全体	> 30s	いいえ（CI）
E2E テスト	> 60s	いいえ（CI）
ビルド全体	> 30s	いいえ（CI）

Husky と代替手段の比較については、reference.md を参照してください。

</decision_framework>

---

<red_flags>

注意すべき問題

優先度の高い問題：

• "prepare": "husky" ではなく、非推奨の "prepare": "husky install" を使用している（v10 で動作しなくなります）
• pre-commit フックでコードベース全体に対して lint を実行している（遅すぎるうえ、ステージ済みファイルのみを対象にする目的に反します）
• package.json で v4 形式の "husky": { "hooks": {} } 設定を使用している（v9 ではサポートされていません）
• HUSKY_GIT_PARAMS 環境変数を使用している（非推奨です。代わりに $1 を使用してください）

優先度が中程度の問題：

• pre-commit フックの実行に 10 秒以上かかる（--no-verify の乱用を招きます）
• CI／本番環境で HUSKY=0 が設定されていない（devDependencies がインストールされていない場合にフックが失敗することがあります）
• フックファイルで非推奨のシバン #!/usr/bin/env sh と husky.sh の読み込みを使用している（v10 で動作しなくなります）
• Node v24 で .js 拡張子の commitlint 設定を使用している（代わりに .mjs を使用してください）

注意点とエッジケース：

• git commit --no-verify はフックを完全に回避します。緊急時の回避策であり、通常の使用には適しません
• lint-staged の関数構文 () => "tsc --noEmit" は、ステージ済みファイルだけでなく、すべてのファイルに対して実行されます
• フックファイル名は Git の正確な名前（pre-commit、commit-msg）と一致させる必要があります。拡張子は付けず、大文字と小文字も区別されます
• HUSKY=2 でデバッグモードが有効になります（非推奨の HUSKY_DEBUG=1 に代わるものです）
• commitlint v20 以降は ESM ネイティブです。.mjs の設定拡張子を使うと、モジュールの読み込みに関する問題を回避できます
• Windows ユーザーは、commit-msg フック内の $1 をエスケープする必要があります
• モノレポでは、husky を実行する前にリポジトリのルートへ移動するよう prepare スクリプトを設定する必要があります
• ~/.huskyrc のサポートは v10 で削除されるため、.config/husky/init.sh に移行してください
• lint-staged v16 では micromatch ではなく picomatch が使われます。そのため、glob パターンが多少異なる場合があります

</red_flags>

---

<critical_reminders>

重要な注意事項

すべてのコードは CLAUDE.md のプロジェクト規約に従う必要があります

（package.json では必ず "prepare": "husky" を使用してください。非推奨の "husky install" は使用しないでください）

（lint-staged を使って、必ずステージ済みファイルのみを lint してください。pre-commit でコードベース全体を lint することは絶対に避けてください）

（フックを無効にするため、CI／本番環境では必ず HUSKY=0 を設定してください）

（.husky/ ディレクトリ内ではプレーンなフックファイルを使用してください。v9 ではシバン行や husky.sh の読み込みを使用しないでください）

（pre-commit フックは必ず 10 秒以内に完了させてください。時間のかかるタスクは pre-push または CI に移してください）

これらのルールに従わないと、コミットの遅延、CI ビルドの失敗、そして Husky v10 で動作しなくなる非推奨のフックパターンが発生します。

</critical_reminders>