# Repository Guidelines

## Project Structure & Module Organization
- `src/llmdebug/`: core package code (capture pipeline, serialization, CLI, pytest plugin, MCP server, middleware).
- `tests/`: pytest suite for library and eval tooling (`test_*.py` files).
- `evals/`: local benchmark harness (`run_eval.py`, `analyze_results.py`, `validate_cases.py`, and `cases/<case_id>/`).
- `docs/` and `reports/`: roadmap notes and analysis outputs.
- Generated artifacts should not be committed: `.llmdebug/`, `evals/artifacts/`, `evals/results/*.jsonl`, `dist/`.

## Build, Test, and Development Commands
Use `uv` for dependency and task management.

```bash
uv sync --extra dev                 # Install runtime + dev dependencies
uv run ruff check src tests         # Lint and import/order checks
uv run pyright                      # Static type checking (standard mode)
uv run pytest                       # Full test suite
uv run pytest -k snapshot_diff      # Targeted test run
uv build --no-sources               # Build wheel/sdist (release-style build)
```

Eval case validation before benchmark runs:

```bash
uv run python -m evals.validate_cases --schema-only
```

## Coding Style & Naming Conventions
- Python 3.10+ with 4-space indentation and max line length 100 (configured in `pyproject.toml`).
- Follow Ruff rule sets `E`, `F`, `I`, `UP`, `B`; keep imports sorted and avoid broad suppressions.
- Prefer type annotations for new/changed APIs to keep `pyright` clean.
- Naming: `snake_case` for modules/functions/variables, `PascalCase` for classes, `UPPER_SNAKE_CASE` for constants.
- Keep patches focused: small, test-backed changes over broad refactors.

## Testing Guidelines
- Framework: `pytest` (configured `testpaths = ["tests"]`).
- Test files: `test_*.py`; test functions: `test_*`.
- Bugs: add regression test when it fits.
- Add regression tests for each bug fix and behavior change.
- Use async tests when touching coroutine paths (`pytest-asyncio` is included in dev dependencies).
- CI does not enforce a fixed coverage threshold; maintain or improve coverage in touched modules.

## Commit & Pull Request Guidelines
- Prefer Conventional Commits (`feat:`, `fix:`, `perf:`, `docs:`, `test:`, `chore:`). Releases are automated via semantic-release.
- Use `feat!:` or a `BREAKING CHANGE:` footer for incompatible changes.
- PRs should include a concise problem/solution summary, linked issue(s), and evidence (tests or command output).
- Before opening a PR, run `ruff`, `pyright`, and `pytest` locally.
