precommit-setup

athola's avatarfrom athola

Configure pre-commit hooks for code formatting, linting, and security checks

⭐83stars🔀11forks📁View on GitHub🕐Updated Jan 3, 2026

When & Why to Use This Skill

This Claude skill automates the configuration of a comprehensive three-layer pre-commit quality system designed to enforce rigorous code standards. By integrating industry-standard tools like Ruff, Mypy, and Bandit, it provides automated linting, static type checking, and security scanning before code is committed. It is highly optimized for Python, Rust, and TypeScript environments, offering specialized workflows for monorepos to ensure high-performance development without compromising on code integrity.

Use Cases

  • Standardizing Code Quality: Quickly implement uniform linting, formatting, and type-checking rules across new or existing projects to maintain a clean codebase.
  • Monorepo Workflow Optimization: Configure intelligent hooks that detect changed components and only run relevant tests and checks, keeping commit speeds fast in large-scale repositories.
  • Automated Security Auditing: Integrate security-focused hooks to catch vulnerabilities and hardcoded secrets locally before they are ever pushed to a remote server.
  • CI/CD Failure Prevention: Use the multi-layered defense system to catch syntax and logic errors on the developer's machine, reducing CI pipeline noise and shortening feedback loops.
nameprecommit-setup
descriptionConfigure comprehensive three-layer pre-commit quality system with linting, type checking, and testing enforcement
Triggerspre-commit, quality, configure, enforcement, checking
modelclaude-sonnet-4
tools[Read, Write, Bash]

Table of Contents

Pre-commit Setup Skill

Configure a detailed three-layer pre-commit quality system that enforces linting, type checking, and testing before commits.

Use When

  • Setting up new project with code quality enforcement
  • Adding pre-commit hooks to existing project
  • Upgrading from basic linting to a full quality system
  • Setting up monorepo/plugin architecture with per-component quality checks
  • Updating pre-commit hook versions

Philosophy: Three-Layer Defense

This skill implements a technical quality system based on three distinct layers. Layer 1 consists of fast global checks that perform quick linting and type checking on all files in approximately 50 to 200 milliseconds. Layer 2 focuses on component-specific checks, running detailed linting, type checking, and testing for changed components only, which typically takes between 10 and 30 seconds. Finally, Layer 3 uses validation hooks for structure verification, security scanning, and custom project checks. This multi-layered approach verifies that new code is automatically checked before commit, which prevents technical debt from entering the repository.

Standard Hooks (Layer 1)

Python Projects

Basic Quality Checks

  1. pre-commit-hooks - File validation (trailing whitespace, EOF, YAML/TOML/JSON syntax)
  2. ruff - Ultra-fast linting and formatting (~50ms)
  3. ruff-format - Code formatting
  4. mypy - Static type checking (~200ms)
  5. bandit - Security scanning

Configuration

```yaml

.pre-commit-config.yaml

repos:

```

Rust Projects

  1. rustfmt - Code formatting
  2. clippy - Linting
  3. cargo-check - Compilation check

TypeScript Projects

  1. eslint - Linting
  2. prettier - Code formatting
  3. tsc - Type checking

Component-Specific Checks (Layer 2)

For monorepos, plugin architectures, or projects with multiple components, add per-component quality checks.

Python Monorepo/Plugin Architecture

Create quality check scripts:

1. Lint Changed Components (scripts/run-component-lint.sh)

```bash #!/bin/bash

Lint only changed components based on staged files

set -euo pipefail

Detect changed components from staged files

CHANGED_COMPONENTS=$(git diff --cached --name-only | grep -E '^(plugins|components)/' | cut -d/ -f2 | sort -u) || true

if [ -z "$CHANGED_COMPONENTS" ]; then echo "No components changed" exit 0 fi

echo "Linting changed components: $CHANGED_COMPONENTS"

FAILED=()

for component in $CHANGED_COMPONENTS; do if [ -d "plugins/$component" ]; then echo "Linting $component..." # Capture exit code to properly propagate failures local exit_code=0 if [ -f "plugins/$component/Makefile" ] && grep -q "^lint:" "plugins/$component/Makefile"; then (cd "plugins/$component" && make lint) || exit_code=$? else (cd "plugins/$component" && uv run ruff check .) || exit_code=$? fi if [ "$exit_code" -ne 0 ]; then FAILED+=("$component") fi fi done

if [ ${#FAILED[@]} -gt 0 ]; then echo "Lint failed for: ${FAILED[*]}" exit 1 fi ```

2. Type Check Changed Components (scripts/run-component-typecheck.sh)

```bash #!/bin/bash

Type check only changed components

set -euo pipefail

CHANGED_COMPONENTS=$(git diff --cached --name-only | grep -E '^(plugins|components)/' | cut -d/ -f2 | sort -u) || true

if [ -z "$CHANGED_COMPONENTS" ]; then exit 0 fi

echo "Type checking changed components: $CHANGED_COMPONENTS"

FAILED=()

for component in $CHANGED_COMPONENTS; do if [ -d "plugins/$component" ]; then echo "Type checking $component..." # Capture output and exit code separately to properly propagate failures local output local exit_code=0 if [ -f "plugins/$component/Makefile" ] && grep -q "^typecheck:" "plugins/$component/Makefile"; then output=$(cd "plugins/$component" && make typecheck 2>&1) || exit_code=$? else output=$(cd "plugins/$component" && uv run mypy src/ 2>&1) || exit_code=$? fi # Display output (filter make noise) echo "$output" | grep -v "^make[" || true if [ "$exit_code" -ne 0 ]; then FAILED+=("$component") fi fi done

if [ ${#FAILED[@]} -gt 0 ]; then echo "Type check failed for: ${FAILED[*]}" exit 1 fi ```

3. Test Changed Components (scripts/run-component-tests.sh)

```bash #!/bin/bash

Test only changed components

set -euo pipefail

CHANGED_COMPONENTS=$(git diff --cached --name-only | grep -E '^(plugins|components)/' | cut -d/ -f2 | sort -u) || true

if [ -z "$CHANGED_COMPONENTS" ]; then exit 0 fi

echo "Testing changed components: $CHANGED_COMPONENTS"

FAILED=()

for component in $CHANGED_COMPONENTS; do if [ -d "plugins/$component" ]; then echo "Testing $component..." # Capture exit code to properly propagate failures local exit_code=0 if [ -f "plugins/$component/Makefile" ] && grep -q "^test:" "plugins/$component/Makefile"; then (cd "plugins/$component" && make test) || exit_code=$? else (cd "plugins/$component" && uv run pytest tests/) || exit_code=$? fi if [ "$exit_code" -ne 0 ]; then FAILED+=("$component") fi fi done

if [ ${#FAILED[@]} -gt 0 ]; then echo "Tests failed for: ${FAILED[*]}" exit 1 fi ```

Add to Pre-commit Configuration

```yaml

.pre-commit-config.yaml (continued)

Layer 2: Component-Specific Quality Checks

  • repo: local hooks:
    • id: run-component-lint name: Lint Changed Components entry: ./scripts/run-component-lint.sh language: system pass_filenames: false files: ^(plugins|components)/.*\.py$

    • id: run-component-typecheck name: Type Check Changed Components entry: ./scripts/run-component-typecheck.sh language: system pass_filenames: false files: ^(plugins|components)/.*\.py$

    • id: run-component-tests name: Test Changed Components entry: ./scripts/run-component-tests.sh language: system pass_filenames: false files: ^(plugins|components)/.*\.(py|md)$

```

Validation Hooks (Layer 3)

Add custom validation hooks for project-specific requirements.

Example: Plugin Structure Validation

```yaml

Layer 3: Validation Hooks

  • repo: local hooks:
    • id: validate-plugin-structure name: Validate Plugin Structure entry: python3 scripts/validate_plugins.py language: system pass_filenames: false files: ^plugins/.*$

```

Workflow

1. Create Configuration Files

```bash

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. Configure Python Type Checking

Create pyproject.toml with strict type checking:

```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. Configure Testing

```toml [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 and Test Hooks

```bash

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. Create Manual Quality Scripts

For full quality checks (CI/CD, monthly audits):

scripts/check-all-quality.sh

```bash #!/bin/bash

Full quality check for all components

set -e

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

Lint all components

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

Type check all components

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

Test all components

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

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

Hook Execution Order

Pre-commit hooks run in this order:

```

  1. File Validation (whitespace, EOF, YAML/TOML/JSON syntax)
  2. Security Scanning (bandit)
  3. Global Linting (ruff - all files)
  4. Global Type Checking (mypy - all files)
  5. Component Linting (changed components only)
  6. Component Type Checking (changed components only)
  7. Component Tests (changed components only)
  8. Custom Validation (structure, patterns, etc.) ```

All must pass for commit to succeed.

Performance Optimization

Typical Timings

Check Single Component Multiple Components All Components
Global Ruff ~50ms ~200ms ~500ms
Global Mypy ~200ms ~500ms ~1s
Component Lint ~2-5s ~4-10s ~30-60s
Component Typecheck ~3-8s ~6-16s ~60-120s
Component Tests ~5-15s ~10-30s ~120-180s
Total ~10-30s ~20-60s ~2-5min

Optimization Strategies

  1. Only test changed components - Default behavior
  2. Parallel execution - Hooks run concurrently when possible
  3. Caching - Dependencies cached by uv
  4. Incremental mypy - Use --incremental flag

Hook Configuration

Skip Specific Hooks

```bash

Skip specific hook for one commit

SKIP=run-component-tests git commit -m "WIP: tests in progress"

Skip component checks but keep global checks

SKIP=run-component-lint,run-component-typecheck,run-component-tests git commit -m "WIP"

Skip all hooks (DANGEROUS - use only for emergencies)

git commit --no-verify -m "Emergency fix" ```

Custom Hooks

Add project-specific hooks:

```yaml

  • repo: local hooks:
    • id: check-architecture name: Validate Architecture Decisions entry: python3 scripts/check_architecture.py language: system pass_filenames: false files: ^(plugins|src)/.*\.py$

    • id: check-coverage name: Verify Test Coverage entry: python3 scripts/check_coverage.py language: system pass_filenames: false files: ^(plugins|src)/.*\.py$

```

CI Integration

Verify CI runs the same detailed checks:

```yaml

.github/workflows/quality.yml

name: Code Quality

on: [push, pull_request]

jobs: quality: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4

  - name: Set up Python
    uses: actions/setup-python@v5
    with:
      python-version: '3.12'

  - name: Install uv
    run: pip install uv

  - name: Install dependencies
    run: uv sync

  - name: Run Comprehensive Quality Checks
    run: ./scripts/check-all-quality.sh

  - name: Upload Coverage
    uses: codecov/codecov-action@v4
    with:
      files: ./coverage.xml

```

Troubleshooting

Hooks Too Slow

Solution: Only changed components are checked by default. For even faster commits:

```bash

Skip tests during development

SKIP=run-component-tests git commit -m "WIP: feature development"

Run tests manually when ready

./scripts/run-component-tests.sh --changed ```

Cache Issues

```bash

Clear pre-commit cache

uv run pre-commit clean

Clear component caches

find . -name "pycache" -type d -exec rm -rf {} + find . -name ".pytest_cache" -type d -exec rm -rf {} + find . -name ".mypy_cache" -type d -exec rm -rf {} + ```

Hook Failures

```bash

See detailed output

uv run pre-commit run --verbose --all-files

Run specific component checks manually

cd plugins/my-component make lint make typecheck make test ```

Import Errors in Tests

```toml

Ensure PYTHONPATH is set in pyproject.toml

[tool.pytest.ini_options] pythonpath = ["src"] ```

Type Checking Errors

```toml

Use per-module overrides for gradual typing

[[tool.mypy.overrides]] module = "legacy_module.*" disallow_untyped_defs = false ```

Best Practices

For New Projects

Start with strict settings from the beginning, as they are easier to maintain over time. We recommend configuring type checking with strict = true in your pyproject.toml and setting up testing early by including pytest in your pre-commit hooks. If you must skip any hooks, always document the reason for the exception.

For Existing Projects

When adding hooks to an existing codebase, use a gradual adoption strategy. Start with global checks and add component-specific checks later as you resolve legacy issues. Fix identified quality problems progressively and create a baseline to document the current state for tracking improvements. Use the --no-verify flag sparingly and only for true emergencies.

For Monorepos and Plugin Architectures

Standardize your development targets by using per-component Makefiles for linting, type checking, and testing. Centralize common settings in a root pyproject.toml while allowing for per-component overrides. Automate the detection of changed components to keep commit times fast, and use a progressive disclosure approach to show summaries first and detailed errors only on failure.

Complete Example: Python Monorepo

```yaml

.pre-commit-config.yaml

repos:

Layer 1: Fast Global Checks

Layer 2: Component-Specific Checks

  • repo: local hooks:
    • id: run-component-lint name: Lint Changed Components entry: ./scripts/run-component-lint.sh language: system pass_filenames: false files: ^plugins/.*\.py$

    • id: run-component-typecheck name: Type Check Changed Components entry: ./scripts/run-component-typecheck.sh language: system pass_filenames: false files: ^plugins/.*\.py$

    • id: run-component-tests name: Test Changed Components entry: ./scripts/run-component-tests.sh language: system pass_filenames: false files: ^plugins/.*\.(py|md)$

Layer 3: Validation Hooks

  • repo: local hooks:
    • id: validate-plugin-structure name: Validate Plugin Structure entry: python3 scripts/validate_plugins.py language: system pass_filenames: false files: ^plugins/.*$

```

  • Skill(attune:project-init) - Full project initialization
  • Skill(attune:workflow-setup) - GitHub Actions setup
  • Skill(attune:makefile-generation) - Generate component Makefiles
  • Skill(pensive:shell-review) - Audit shell scripts for exit code and safety issues

See Also