Repository Guidelines

Project Structure & Module Organization

The Python package lives in src/quality/, split into cli/ for the claude-quality entry point, core/ domain models, analyzers/ and detection/ engines, and utils/ helpers. Hook integrations used by Claude Code run from hooks/, with shared settings in hooks/claude-code-settings.json. Tests focus on tests/hooks/ for the hook lifecycle and leverage fixtures in tests/hooks/conftest.py. Repository-level configuration is centralized in pyproject.toml and the Makefile.

Build, Test, and Development Commands

Run make venv once to create a Python 3.12 virtualenv and activate it before development. Use make install-dev to install the package in editable mode with dev extras via uv and register pre-commit hooks. Daily checks:

make lint → ruff check + ruff format --check
make typecheck → strict mypy against src/
make test / make test-cov → pytest with optional coverage
make check-all → lint + typecheck + tests For ad hoc analysis, make analyze runs claude-quality full-analysis src/ --format console.

Coding Style & Naming Conventions

Code targets Python 3.12+, uses 4-space indentation, and follows ruff with an 88-character line width. Prefer expressive snake_case module and function names, PascalCase for classes, and CONSTANT_CASE for constants. Strict mypy is enforced, so fill in type hints and avoid implicit Any. Format using ruff format; do not mix formatters. Keep docstrings concise and use Google-style docstrings when they add clarity.

Testing Guidelines

pytest drives the suite with primary coverage under tests/hooks/. Group new tests alongside related hook modules and name files test_<feature>.py with test functions test_*. The CI configuration enforces --cov=code_quality_guard and --cov-fail-under=80; run make test-cov before opening a PR to confirm coverage. For focused runs, target a path such as pytest tests/hooks/test_pretooluse.py -k scenario.

Commit & Pull Request Guidelines

Commit messages follow Conventional Commit semantics (feat:, fix:, chore:). Example: feat: tighten posttool duplicate detection thresholds. Before pushing, run pre-commit run --all-files and make check-all; include the output or summary in the PR description. PRs should link relevant issues, describe behavioral changes, and attach HTML coverage or console snippets when functionality changes. Screenshots are expected when hook output formatting shifts or CLI UX changes.

2.5 KiB Raw Blame History