precommit-setup

Pre-commit セットアップスキル

すべてのコミット前にリンティング、型チェック、テストを実行する、3 層構成の pre-commit 品質システムを設定します。

使用するタイミング

• コード品質を強制する新しいプロジェクトをセットアップするとき
• 既存のプロジェクトに pre-commit フックを追加するとき
• 基本的なリンティングから包括的な品質システムに移行するとき
• コンポーネントごとの品質チェックを行うモノレポやプラグインアーキテクチャをセットアップするとき
• pre-commit フックのバージョンを更新するとき

使用しないタイミング

• pre-commit フックがすでに設定され、最適に動作している場合
• プロジェクトで git バージョン管理を使用していない場合
• チームがワークフロー上の理由で pre-commit フックを明示的に使用しない場合

基本方針：3 層の防御

このシステムは、コストとカバー範囲のトレードオフがそれぞれ異なる 3 層で構成されています。

• レイヤー 1：標準フック：高速な全体チェック（合計 50〜200ms）です。ステージングされたすべてのファイルをリンティングし、型チェックします。
• レイヤー 2：コンポーネント固有のチェック：コンポーネントごとのリンティング、型チェック、テスト（合計 10〜30 秒）です。ステージングされたファイルが変更されたコンポーネントだけを実行します。
• レイヤー 3：検証フック：プロジェクト固有の構造やパターンのチェック（所要時間はさまざま）です。汎用リンターでは検出できない違反を見つけます。

この階層構造により、高速なフィードバックループを保ちながら、時間のかかる問題やプロジェクト固有のバグもマージ前に検出できます。

モジュールの読み込み

詳細な設定パターンは各モジュールに記載されています。必要なものだけを読み込んでください。

• modules/standard-hooks.md：Python、Rust、TypeScript 向けのレイヤー 1 のパターンです（基本的なリンターを設定するときに読み込みます）。
• modules/component-level-hooks.md：レイヤー 2 のモノレポ用スクリプトと pre-commit の接続方法です（プロジェクトに複数のコンポーネントやプラグインがある場合に読み込みます）。
• modules/validation-hooks.md：レイヤー 3 のカスタムフックと SKIP パターンです（リンティング以外のプロジェクト規約を強制するときに読み込みます）。
• modules/ci-integration.md：GitHub Actions ワークフローと、完全な .pre-commit-config.yaml の例です（CI をローカルのチェックと同じ内容にするときに読み込みます）。
• modules/troubleshooting.md：実行時間の表、キャッシュのクリア方法、フック失敗からの復旧方法です（フックが遅い、または失敗する場合に読み込みます）。

ワークフロー

1. 設定ファイルを作成する

# Create .pre-commit-config.yaml
python3 plugins/attune/scripts/attune_init.py \
  --lang python \
  --name my-project \
  --path .

# Create quality check scripts (for monorepos)
mkdir -p scripts
chmod +x scripts/run-component-*.sh

2. Python の型チェックを設定する

厳格な型チェックを行う pyproject.toml を作成します。

[tool.mypy]
python_version = "3.12"
warn_return_any = true
warn_unused_configs = true
disallow_untyped_defs = true
strict = true

# Per-component configuration
[[tool.mypy.overrides]]
module = "plugins.*"
strict = true

3. テストを設定する

[tool.pytest.ini_options]
testpaths = ["tests"]
pythonpath = ["src"]
addopts = [
    "-v",                    # Verbose output
    "--strict-markers",      # Strict marker enforcement
    "--cov=src",             # Coverage for src/
    "--cov-report=term",     # Terminal coverage report
]

markers = [
    "slow: marks tests as slow (deselect with '-m \\"not slow\\"')",
    "integration: marks tests as integration tests",
]

4. フックをインストールしてテストする

# Install pre-commit tool
uv sync --extra dev

# Install git hooks
uv run pre-commit install

# Test on all files (first time)
uv run pre-commit run --all-files

# Normal usage - test on staged files
git add .
git commit -m "feat: add feature"
# Hooks run automatically

5. 品質チェック用の手動スクリプトを作成する

すべての品質チェックを実行する場合（CI/CD、月次監査など）は、次のようにします。

#!/bin/bash
# scripts/check-all-quality.sh: full quality check for all components

set -e

echo "=== Running Full Quality Checks ==="

./scripts/run-component-lint.sh --all
./scripts/run-component-typecheck.sh --all
./scripts/run-component-tests.sh --all

echo "=== All Quality Checks Passed ==="

フックの実行順序

コミット前フックは次の固定順序で実行されます。コミットを成功させるには、すべてに合格する必要があります。

1. ファイル検証（空白、EOF、YAML／TOML／JSON の構文）
2. セキュリティスキャン（bandit）
3. 全体のリンティング（ruff、すべてのファイル）
4. 全体の型チェック（mypy、すべてのファイル）
5. コンポーネントのリンティング（変更されたコンポーネントのみ）
6. コンポーネントの型チェック（変更されたコンポーネントのみ）
7. コンポーネントのテスト（変更されたコンポーネントのみ）
8. カスタム検証（構造、パターンなど）

ベストプラクティス

新規プロジェクトの場合

最初から厳格な設定を使用してください。長期的に保守しやすくなります。pyproject.toml で strict = true を設定して型チェックを構成し、早い段階でテストをセットアップし（pre-commit に pytest を含めます）、フックをスキップする必要がある場合は、その理由を必ず記録してください。

既存プロジェクトの場合

段階的に導入してください。まず全体チェック（レイヤー 1）から始め、レガシーの問題を解決したら、コンポーネント固有のチェック（レイヤー 2）を追加します。--no-verify は本当の緊急時に限って使用し、その理由を記録してください。

モノレポとプラグインアーキテクチャの場合

コンポーネントごとの Makefile で lint、typecheck、test の各ターゲットを標準化してください。共通設定はルートの pyproject.toml に集約しつつ、コンポーネントごとのオーバーライドも可能にします。変更検出を自動化してコミットを高速に保ち、段階的開示（最初に概要を示し、失敗時に詳細を表示）を活用してください。

関連スキル

• Skill(attune:project-init)：プロジェクトの完全な初期化
• Skill(attune:workflow-setup)：GitHub Actions のセットアップ
• Skill(attune:makefile-generation)：コンポーネントの Makefile を生成
• Skill(pensive:shell-review)：シェルスクリプトの終了コードと安全性に関する問題を監査

関連項目

• 品質ゲート：3 層の検証。コミット前フック（フォーマット、リンティング）、CI チェック（テスト、カバレッジ）、PR レビューゲート（コード品質、セキュリティ）で構成されます。

完了条件

• .pre-commit-config.yaml がプロジェクトのルートにあり、少なくともレイヤー 1（空白、YAML／TOML／JSON の構文、全体のリンティング）を対象とするフックが設定されている。
• 設定をインストールした後、uv run pre-commit run --all-files の終了コードが 0 になり、現在のコードベースの状態で、すべてのフックが合格することを確認できる。
• ステージされた変更がある状態で git commit を実行すると、コミット前フックが自動的に起動する（uv run pre-commit install の終了コードが 0 であり、.git/hooks/pre-commit が存在することで確認）。
• --no-verify による回避が、プロジェクトの文書化されたワークフローに含まれていない。既存のスクリプトで見つかった場合は、黙認せず違反として報告する。