From b8c8a4f952b33059ad1e2b3dae8765d3f46d22d8 Mon Sep 17 00:00:00 2001 From: Travis Vasceannie Date: Sun, 28 Sep 2025 22:02:45 +0000 Subject: [PATCH] ok --- AGENTS.md | 42 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..cc31f5e --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,42 @@ +# 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_.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.