ln-742-precommit-setup

パス： ファイルパス（references/、../ln-*）は、このスキルディレクトリを基準とした相対パスです。

ln-742-precommit-setup

タイプ： L3 Worker カテゴリ： 7XX プロジェクトの初期設定

コミット前にコード品質を自動的にチェックするため、Git フックを設定します。

---

目的と範囲

実施すること：

• フック管理ツール（Husky または pre-commit）をインストールします
• ステージング済みファイルのリンティング（lint-staged または pre-commit フック）を設定します
• コミットメッセージの検証（commitlint）を設定します
• フックが正しく実行されることを確認します

実施しないこと：

• リンター自体の設定（ln-741 が担当します）
• テスト環境の設定（ln-743 が担当します）
• ソースコードの変更

---

対応スタック

テクノロジー	フックマネージャー	ステージング済みファイルのリンティング	コミットの検証
Node.js	Husky	lint-staged	commitlint
Python	pre-commit	pre-commit フック	pre-commit フック
混在	必要に応じて両方	スタック固有	commitlint

---

フェーズ 1：既存のフックを確認する

インストールする前に、既存のフック設定を確認します。

確認するファイル：

ツール	該当するもの
Husky	.husky/ ディレクトリ、package.json 内の husky
pre-commit	.pre-commit-config.yaml
lint-staged	package.json 内の lint-staged、または .lintstagedrc*
commitlint	commitlint.config.*、.commitlintrc*

判断の流れ：

1. フックがすでに存在し、機能している場合：スキップ（ユーザーに知らせます）
2. 設定が一部だけの場合：続行または置き換えについてユーザーに確認します
3. フックがない場合：テンプレートから作成します

---

フェーズ 2：フックマネージャーをインストールする

Node.js プロジェクト（Husky）

npm install -D husky
npx husky init

以下が作成されます：

• .husky/ ディレクトリ
• .husky/pre-commit フックファイル
• package.json への prepare スクリプトの追加

Python プロジェクト（pre-commit）

pip install pre-commit
# OR with uv:
uv add --dev pre-commit

pre-commit install

以下が作成されます：

• .git/hooks/pre-commit（pre-commit によって管理されます）
• 設定用の .pre-commit-config.yaml が必要です

---

フェーズ 3：ステージング済みファイルのリンティングを設定する

Node.js（lint-staged）

npm install -D lint-staged

設定（.lintstagedrc.mjs または package.json 内）を作成します：

主なルール：

• TypeScript ファイル：ESLint + Prettier
• JSON/MD/CSS：Prettier のみ
• C# ファイル：dotnet format（プロジェクトが混在している場合）

重要な修正： .NET ファイルでは、正しい構文を使用してください： "*.cs": "dotnet format --include" は誤りです "*.cs": "dotnet format whitespace --include" を使用するか、dotnet format を別途実行してください

Python（pre-commit フック）

.pre-commit-config.yaml に設定します：

repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.8.0
    hooks:
      - id: ruff
        args: [--fix]
      - id: ruff-format

---

フェーズ 4：コミットメッセージの検証を設定する

Node.js（commitlint）

npm install -D @commitlint/cli @commitlint/config-conventional

以下の内容で commitlint.config.mjs を作成します：

• Conventional Commits 形式
• 許可するタイプ：feat、fix、docs、style、refactor、test、chore、ci
• ヘッダーの最大長：100 文字

Husky フックを更新する

commit-msg フックを追加します：

echo 'npx --no -- commitlint --edit "$1"' > .husky/commit-msg

Python（コミットメッセージ用の pre-commit フック）

.pre-commit-config.yaml に追加します：

  - repo: https://github.com/compilerla/conventional-pre-commit
    rev: v3.4.0
    hooks:
      - id: conventional-pre-commit
        stages: [commit-msg]

---

フェーズ 5：フックをテストする

フックが正しく動作することを確認します。

テスト 1：lint-staged が実行されること

# Create a file with lint issues
echo "const x=1" > test-file.ts
git add test-file.ts
git commit -m "test: verify hooks"
# Expected: lint-staged runs, either fixes or blocks

テスト 2：コミットメッセージが検証されること

git commit --allow-empty -m "bad message"
# Expected: commitlint rejects

git commit --allow-empty -m "test: valid message format"
# Expected: commit succeeds

後片付け：

rm test-file.ts
git reset HEAD~1  # If test commit was made

---

重要なルール

ルール 1： Husky を使うには Git リポジトリが必要です（最初に git init を実行してください）。

ルール 2： lint-staged を使うには、リンターを先に設定する必要があります（ln-742 より前に ln-741 を実行してください）。

ルール 3： 緊急時にコミットを行うための回避策として、--no-verify を記載してください。

ルール 4： pre-commit フックでは、可能な場合に自動修正（--fix フラグ）を行ってください。

---

モニター（2.1.98+）： フックの検証で、30 秒を超えると予想される lint/test コマンドを実行する場合は、Monitor を使用してください。代替手段：Bash(run_in_background=true)。

完了の定義

• フックマネージャー（Husky または pre-commit）がインストールされている
• ステージング済みファイルのリンティングが設定され、機能している
• コミットメッセージの検証が設定されている
• テストコミットでフックが正しく実行される
• 以下をユーザーに説明している：
  • フックの動作
  • 緊急時にフックをスキップする方法（git commit --no-verify）
  • 必須のコミットメッセージ形式

---

Reference Files

File	Purpose
husky_precommit_template.sh	Husky pre-commit hook
husky_commitmsg_template.sh	Husky commit-msg hook
lintstaged_template.mjs	lint-staged configuration
commitlint_template.mjs	commitlint configuration
precommit_config_template.yaml	Python pre-commit config
hooks_guide.md	Detailed hooks guide

---

Error Handling

Error	Cause	Resolution
Husky not running	Missing prepare script	Run npx husky init again
lint-staged fails	Missing linter	Run ln-741 first
pre-commit not found	Not in PATH	pip install pre-commit
Hooks not triggering	Git hooks disabled	Check .git/hooks/ permissions
Windows path issues	Shell script format	Use cross-platform syntax

---

Emergency Bypass

Document for users:

# Skip all hooks (use sparingly!)
git commit --no-verify -m "emergency: bypass hooks"

# Skip only pre-commit (keeps commit-msg)
HUSKY=0 git commit -m "fix: urgent hotfix"

---

Version: 2.0.0 Last Updated: 2026-01-10