【品質の自動防衛】Husky + lint-stagedでコミット前のフォーマット崩れと構文エラーを完全シャットアウト

2026/08/17

「PR（プルリクエスト）の変更差分を見たら、半分がフォーマットの変更だけだった……」

チーム開発において、コードの記述スタイルやフォーマットの表記揺れはレビューの効率を大きく低下させます。どれほど注意を払っていても、個人のVS Code設定の違いや保存し忘れによって、不揃いなコードがリポジトリに紛れ込んでしまうものです。

今回は、Gitのコミット直前に自動でフォーマッターやリンターを割り込ませる Husky + lint-staged の導入手順を解説します。「変更されたファイルだけ」を対象に自動修正するため、コミット速度を落とさずに最高レベルのコード品質を維持できます。

なぜ「CI環境でのチェック」だけでは不十分なのか？

GitHub ActionsなどのCIで npm run lint を実行してエラーを弾く手法も一般的です。しかし、CIでエラーが出ると「コミット push → CI失敗通知受領 → ローカルで修正 → 再度コミット push」という無駄な待ち時間が発生してしまいます。

手元のローカル環境で git commit を押したその瞬間に自動修正・チェックを行うことで、不完全なコードがリポジトリへ1行も混入しない「堅牢な防波堤」を構築できます。

Huskyとlint-stagedの協調動作

全ファイルをチェックするとプロジェクトが大きくなった際にコミットが遅くなります。lint-staged を使うことで「コミット対象にステージングされたファイル」のみを高速処理します。

graph TD
    A["エンジニアが git commit を実行"] --> B["Husky の pre-commit フックが発火"]
    B --> C["lint-staged 起動"]
    C --> D["ステージングされたファイル (.js/.ts/.json等) を抽出"]
    D --> E["Prettier によるコード自動フォーマット"]
    E --> F["ESLint による構文・規約チェック"]
    F --> G{"エラーや修正不可能な違反はあるか？"}
    G -- "問題なし (または自動修正完了)" --> H["コミット成功・リポジトリ保存"]
    G -- "致命的エラーあり" --> I["コミット中断 & ターミナルへ詳細出力"]

導入・設定手順（モダンJS/TS環境対応）

Node.js（TypeScript/JavaScript）環境における最新のHusky（v9以降対応）とlint-stagedの導入ステップです。

1. パッケージのインストール

開発依存（devDependencies）として必要なパッケージを追加します。

npm install -D husky lint-staged prettier eslint

2. Huskyの初期化

以下のコマンドを実行すると、リポジトリ内に .husky/ ディレクトリが生成され、Gitフックが有効化されます。

npx husky init

実行後、package.json の scripts に "prepare": "husky" が自動追記されます。これにより、他のチームメンバーが npm install を実行した際にも自動的にHuskyフックがセットアップされます。

3. `.husky/pre-commit` の編集

.husky/pre-commit ファイルを開き、実行コマンドを npx lint-staged に書き換えます。

#!/bin/sh
npx lint-staged

4. `package.json` に lint-staged のルールを設定

コミット対象の拡張子に応じて実行するコマンドを指定します。

{
  "name": "my-awesome-project",
  "version": "1.0.0",
  "scripts": {
    "prepare": "husky"
  },
  "lint-staged": {
    "*.{js,jsx,ts,tsx}": [
      "prettier --write",
      "eslint --fix"
    ],
    "*.{json,css,scss,md}": [
      "prettier --write"
    ]
  }
}

導入によって劇的に改善された3つのポイント

コードレビューの時間が半減 PRのコメントから「ここインデントズレてます」「セミコロン抜けてます」といった本質的でない指摘が100%消滅しました。ロジックの設計に関する濃密なレビューに時間を使えるようになります。
フォーマット修正コミットの撲滅 「Fix format」のような無駄なコミット履歴が完全に無くなり、Gitログが極めて綺麗に保たれるようになりました。
ステージング漏れの防止 Prettierが自動修正した内容も lint-staged が自動で再ステージングしてくれるため、手作業で修正部分を追加し直す手間がかかりません。

まとめ：フォーマット議論は機械に任せよう

コードのフォーマットやスタイルルールについて、人間同士が議論したり気を揉んだりするのは非常にコストが高い行為です。

Husky と lint-staged を一度導入してしまえば、開発者はコードの価値を生み出す思考に集中できます。10分程度の作業で導入できますので、プロジェクトの初期段階で必ずセットアップしておくことを強くおすすめします！