コードの「負債」をコミットさせない：Husky × lint-staged で構築する究極の静的解析ワークフロー
開発現場において、「コードレビューでスタイルの指摘をする」という行為は、レビュアーとレビュイー双方の脳のリソースを浪費する、極めて非生産的な儀式です。
真に洗練された開発チームは、「コードがリポジトリに保存される瞬間」をゲートウェイとして捉えています。今回は、Husky と lint-staged を用いて、開発者の思考を止めずにコード品質を担保する、現場直結のアーキテクチャを伝授します。
—
1. なぜ「全ファイル走査」を捨て去るべきなのか
多くの現場で、`npm run lint` を CI だけで実行し、ローカルでは放置、あるいは全ファイル走査をフックに仕込んで待ち時間でコーヒーを淹れに行く姿を見かけます。これは間違いです。
`lint-staged` の真の価値は、「Git のステージングエリア（Index）にある差分ファイルのみ」を対象にする点にあります。数万行のプロジェクトであっても、修正した3ファイルだけを対象にすれば、オーバーヘッドは数ミリ秒です。この「思考速度を損なわない」という点が、DX（開発者体験）の核心です。
—
2. 構築のベストプラクティス：Husky × lint-staged
まずは、現代の標準である `Husky v9` を使用した設定です。
導入ステップ（コマンドラインの勘所）
huskyのインストールと初期化
npm install –save-dev husky lint-staged
npx husky init
このコマンドで `.husky/` ディレクトリが生成されます。ここで重要なのは、「フックの実行は極力軽量に保つ」ことです。
`.lintstagedrc.json` の最適解
プロジェクトのルートに配置するこの設定ファイルこそが、品質の防波堤です。
{
“.{js,ts,tsx,jsx}”: [
// Prettierでフォーマットを統一
“prettier –write”,
// ESLintでコード品質を担保（–fixは自動修正可能なものを解決）
“eslint –fix”
],
“.{json,md,yaml}”: [
// 非コード資産もフォーマットを強制し、差分をクリーンに保つ
“prettier –write”
]
}
アーキテクトの視点：
ここで `eslint –fix` を入れるのは議論が分かれますが、私は推奨派です。ただし、ESLint側のルールで `no-unused-vars` 等の「警告」が「エラー」として扱われないよう、個別にチューニングしておく必要があります。
—
3. チーム開発を加速させる「共有化の掟」
設定ファイルを置くだけでは足りません。メンバー間で環境差異が出るのは「設定の共有」ができていないからです。
1. `package.json` のスクリプトで Husky を自動化
`prepare` スクリプトを定義することで、`npm install` 時に自動でフックが有効化されるようにします。
{
“scripts”: {
“prepare”: “husky”
}
}
2. VS Code 設定の強制（`.vscode/settings.json`）
エンジニア個人のエディタ設定に依存させないため、プロジェクト単位で以下の設定をコミットします。
{
“editor.formatOnSave”: true,
“editor.defaultFormatter”: “esbenp.prettier-vscode”,
“editor.codeActionsOnSave”: {
“source.fixAll.eslint”: “explicit”
}
}
これで、保存した瞬間に `lint-staged` の対象となる修正が行われ、コミット時には既に綺麗な状態が担保されます。
—
4. 現場で使える「隠れテクニック」と神プラグイン
神プラグイン：`eslint-plugin-import`
インポート文の順序や重複を自動で整理します。コンフリクトの多くは実はインポート文の並び順に起因するため、これを強制するだけで Git マージが劇的に楽になります。
隠れテクニック：`–no-verify` の賢い使い所
どうしてもコミットフックを回避したい緊急時（例：一時的なデバッグ用のログ挿入など）は、`git commit -m “WIP” –no-verify` を使用します。ただし、「CIを通らないコードはデプロイできない」というルールを CI/CD パイプライン側に設けておけば、ローカルで不正なコードが混入しても最終的な品質は守られます。
—
5. まとめ：なぜこの構成が「最強」なのか
1. ゼロ・待ち時間: `lint-staged` が差分のみを処理するため、ファイル数に依存せず常に高速。
2. 属人性の排除: `husky` と `.vscode/settings.json` の強制により、誰が書いても同じコーディングスタイルに収束する。
3. レビューの質向上: 「セミコロンの有無」を議論する時間はゼロになり、レビュアーは「ビジネスロジックの正当性」や「可読性」という、人間にしかできない高度な判断に集中できる。
このワークフローを導入することは、単なるツールの導入ではなく、「コード品質への敬意をチームの文化にする」という組織変革です。まずは、あなたのプロジェクトの `.husky/pre-commit` に、一行の lint-staged を書き込むことから始めてください。それが、1年後のチームの生産性を劇的に変える第一歩となります。