py-git-hooks

Python の Git フック設定

pre-commit フレームワークを使用して Git のコミット前フックを設定し、コミット前にコード品質を確保します。

目標

1. Python 品質チェック用フックとともに pre-commit フレームワークをインストールします
2. 既存の手動フックがあれば、pre-commit フレームワークに移行します
3. Claude Code の Stop フックのリントゲートを設定します（ユーザーに制御を返す前に、リントスイート全体を実行します）
4. フックが変更されたファイルのみを対象に増分実行されるようにします
5. 可能な場合は問題を自動修正し、重大なエラーがある場合は処理をブロックします

必要なツール

[dependency-groups] の dev に追加: "pre-commit"、"ruff"、"mypy"、"basedpyright"

• pre-commit：フック管理フレームワーク（必須）
• ruff：自動修正機能を備えた高速なリンター
• mypy：標準的な Python 型チェッカー
• basedpyright：強化された型解析ツール

権限：まず py-quality-setup を実行して、必要なすべてのツール権限を .claude/settings.local.json に設定してください。

セットアップのワークフロー

ステップ 1：既存のフックを確認する

# Check if manual hooks exist
ls -la .git/hooks/pre-commit 2>/dev/null

# If exists and not a pre-commit managed hook, migrate it (see Migration section)

ステップ 2：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

  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.13.0
    hooks:
      - id: mypy
        additional_dependencies: []  # Add type stubs as needed

  - repo: local
    hooks:
      - id: basedpyright
        name: basedpyright
        entry: basedpyright
        language: system
        types: [python]
        pass_filenames: true

ステップ 3：フックをインストールする

# Install pre-commit to project venv
uv pip install pre-commit

# Install git hooks
pre-commit install

# Verify installation
ls -la .git/hooks/pre-commit

ステップ 4：フックをテストする

# Run on all files (initial validation)
pre-commit run --all-files

# Or test on staged files only
git add some_file.py
pre-commit run

ステップ 5：Claude Code の Stop フックのリントゲートを設定する

強く推奨：変更された Python ファイルに対してリントスイート全体（ruff、mypy、basedpyright）を実行し、Claude がユーザーに制御を返す前にチェックする Claude Code の Stop フックを設定してください。いずれかのリンターがエラーを報告した場合、Claude は停止できず、先にエラーを修正する必要があります。

これは、編集のたびに ruff を実行して中間状態でノイズが発生する、従来の PostToolUse 方式に代わるものです。

リントゲートのスクリプトをインストールする（更新が自動的に反映されるよう、シンボリックリンクを作成します）：

mkdir -p ~/.claude/hooks
ln -sf ~/.claude/skills/py-git-hooks/lint-gate.py ~/.claude/hooks/lint-gate.py

~/.claude/settings.json で Stop フックを設定する：

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/hooks/lint-gate.py"
          }
        ]
      }
    ]
  }
}

仕組み：

• Claude の応答が完了したとき、ユーザーに結果を表示する前に一度実行されます
• git diff を使用して、変更された .py ファイルを検出します（ステージ済み、ステージされていないもの、未追跡のもの）
• 自動修正パス：ruff check --fix と ruff format を実行して、軽微な問題（インポート順、空白、スタイル）を通知せずに修正します
• チェックパス：ruff check、mypy、basedpyright を実行して、修正できない残りのエラーを検出します
• エラーが残っている場合：{"decision": "block", "reason": "..."} を返します。Claude はリントの出力を確認し、問題を修正するために作業を続けます
• エラーがない場合（自動修正後）：{"decision": "stop"} を返します。Claude はユーザーに制御を返します
• ループ防止：入力の stop_hook_active が true の場合（以前のブロック後に Claude が再試行中であることを示します）、無限ループを防ぐため、フックは停止を許可します
• プロジェクトにインストールされていないツールは、正常にスキップします

PostToolUse フックと比べたメリット：

• 編集のたびではなく、ターンごとに一度実行されるため、中間状態によるノイズがありません
• 軽微な問題を自動修正するため、Claude がブロックされるのは実際のエラーがある場合のみです
• ruff だけでなく、スイート全体（ruff + mypy + basedpyright）を実行します
• Claude が応答を返すとき、ユーザーには常にクリーンなコードベースが表示されます
• Claude はフィードバックから学習し、同じ間違いの繰り返しを避けます

手動フックからの移行

プロジェクトに既存の手動 .git/hooks/pre-commit スクリプトがある場合：

ステップ 1：既存のフックをバックアップする

cp .git/hooks/pre-commit .git/hooks/pre-commit.backup

ステップ 2：既存のフックを分析する

既存のフックを読んで、実行するチェックを確認します：

• リント（ruff、flake8、pylint）？
• 型チェック（mypy、pyright）？
• フォーマット（black、isort）？
• カスタムチェック？

ステップ 3：pre-commit の設定に対応付ける

手動フックの各チェックについて、.pre-commit-config.yaml に相当する設定を追加します：

手動フックのチェック	pre-commit での設定
ruff check	ruff-pre-commit リポジトリ
black	ruff-format（ruff が black に代わります）
isort	isort ルール（I）を有効にした ruff
flake8	ruff（flake8 に代わります）
mypy	mirrors-mypy リポジトリ
basedpyright	ローカルフック
カスタムスクリプト	entry: ./script.sh を指定したローカルフック

ステップ 4：pre-commit をインストールして手動フックを削除する

pre-commit install  # This overwrites .git/hooks/pre-commit
pre-commit run --all-files  # Verify all checks pass

ステップ 5：確認してクリーンアップする

# Test that hooks work
git add .
git commit -m "test" --dry-run

# If successful, remove backup
rm .git/hooks/pre-commit.backup

フックの動作

自動修正可能な問題（pre-commit と Stop フックのリンティングゲートの両方で処理されます）：

• インポートの並べ替え
• 行末の空白
• 簡単なスタイル違反
• 多くのコード品質に関する問題

ブロック対象の問題（Claude または手動での対応が必要です）：

• 型エラー（mypy/basedpyright）
• 構文エラー
• 自動修正できない複雑なリンティング違反

回避（必要最小限にしてください）：

git commit --no-verify

パフォーマンスの最適化

大規模なコードベースの場合：

• デフォルトでは、pre-commit はステージング済みのファイルのみを実行対象とします
• mypy のインクリメンタルモードを使用します（キャッシュは .mypy_cache に保存されます）
• 高速化のため、mypy/basedpyright は CI でのみ実行することを検討してください

モノレポの場合：

• フックの設定で files: パターンを使用して、対象範囲を限定します
• パッケージごとに個別のフックを設定します

- id: mypy
  files: ^src/mypackage/

トラブルシューティング

フックが実行されない場合：

pre-commit install --force  # Reinstall hooks

ツールが見つからない場合：

# Ensure tools installed in venv
uv pip install ruff mypy basedpyright

フックが遅すぎる場合：

• プロファイルを確認します：pre-commit run --verbose
• pre-commit から mypy/basedpyright を削除し、代わりに CI で実行することを検討してください
• 遅いフックには stages: [manual] を使用し、明示的に実行します

フックのバージョンを更新する場合：

pre-commit autoupdate

PostToolUse フックからの移行

ruff 用の PostToolUse フック（以前の方法）を使用してプロジェクトを設定していた場合は、Stop フックのリンティングゲートに移行してください：

ステップ 1：既存の PostToolUse フックを確認する

grep -A 10 '"PostToolUse"' ~/.claude/settings.json

ステップ 2：PostToolUse の Ruff フックを削除する

~/.claude/settings.json を編集し、Edit|Write|MultiEdit に一致して ruff check を実行する PostToolUse エントリを削除します。ruff 以外の PostToolUse フックは残してください。

ステップ 3：Stop フックをインストールする

上記のセットアップワークフローのステップ 5 に従い、lint-gate.py をインストールして Stop フックを設定します。

ステップ 4：確認する

ruff エラーが発生する Python の編集を行います。次のことを確認してください：

• 編集直後にはフィードバックが表示されない（PostToolUse フックは削除済み）
• Claude の応答が完了すると Stop フックが実行され、エラーによって処理がブロックされる
• Claude がエラーを修正し、問題のない出力を返す

リンティングの学習

Claude は、同じ間違いを繰り返さないよう、リンティングゲートからのフィードバックを学習する必要があります。

リンティングゲートによってブロックされた後：エラーのパターンを記録します。同じリンタールールが複数の編集で繰り返し発生する場合は、lint-patterns トピックのオートメモリーに記録します。形式：

- **[rule-code]** (tool): What triggers it and how to avoid it.

Python ファイルを編集する前：このプロジェクトで既知のリンティング上の落とし穴がないか、オートメモリーを確認します。リンティングゲートを最初の試行で通過できるよう、学んだ内容をあらかじめ適用してください。

これにより、セッションをまたいだフィードバックループが生まれます。リンティングゲートによるブロックのたびに、Claude は次回、よりクリーンなコードを書くことを学習します。

確認チェックリスト

• ruff、mypy、basedpyright のフックを含む .pre-commit-config.yaml が存在する
• pre-commit install を実行済み
• pre-commit run --all-files が成功する
• 既存の手動フックを移行済み
• ~/.claude/hooks/lint-gate.py をインストール済みで、実行可能になっている
• ~/.claude/settings.json で Claude Code の Stop フックを設定済み
• 古い PostToolUse の ruff フックを設定から削除済み
• 緊急時に --no-verify で回避できる（git pre-commit のみ）

例

例：新規プロジェクトのセットアップ

1. Create venv: uv venv && source .venv/bin/activate
2. Install tools: uv pip install pre-commit ruff mypy basedpyright
3. Create .pre-commit-config.yaml with ruff, mypy, basedpyright
4. Install hooks: pre-commit install
5. Test: pre-commit run --all-files
6. Install lint-gate.py and configure Stop hook in settings.json

例：PostToolUse から Stop フックへの移行

1. Remove PostToolUse ruff hooks from ~/.claude/settings.json
2. Symlink lint-gate.py to ~/.claude/hooks/
3. Add Stop hook to ~/.claude/settings.json
4. Verify: make an edit with a ruff error, confirm block-on-stop behavior

例：既存の手動フックの移行

1. Backup: cp .git/hooks/pre-commit .git/hooks/pre-commit.backup
2. Read backup to identify checks (ruff, mypy, custom scripts)
3. Create .pre-commit-config.yaml mapping each check
4. Install: pre-commit install (overwrites manual hook)
5. Verify: pre-commit run --all-files
6. Clean up: rm .git/hooks/pre-commit.backup

例：既存の pre-commit 設定への追加

1. Edit .pre-commit-config.yaml
2. Add basedpyright local hook
3. Run: pre-commit run --all-files
4. Commit updated config

関連スキル

• 前提条件：py-quality-setup（フックを追加する前にツールを設定しておく必要があります）
• 補完スキル：py-security（セキュリティスキャンのため、pre-commit に bandit を追加します）
• 関連項目：すべてのスキルで、フックによる自動適用が役立ちます