ok

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_<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.