Modern Python Project Instructions (uv + ruff + pytest)
Claude CodeCLAUDE.mdCoding
CLAUDE.md for Python projects managed with uv: dependency rules, ruff lint/format gates, pytest conventions, and a no-untyped-code policy agents can verify.
Use when: Use in any Python 3.12+ project that uses uv for environments and packaging, so agents run the right commands and never reach for pip, poetry, or unformatted code.
Get this skill
Add the skill file with the CLI, by hand, or over MCP.Save this to your project or home directory so Claude Code can load it.
npx goodprompts add python-uv-project-claude-mdSaves to
./CLAUDE.mdnpx goodprompts add python-uv-project-claude-mdSaves to
./CLAUDE.mdSkill file
CLAUDE.md2,831 characters# Project Instructions — Python (uv)
## Environment & dependencies
This project is managed by **uv**. Never call `pip`, `poetry`, `pipenv`, or `python -m venv` directly.
```bash
uv sync # create/update the venv from uv.lock
uv add <package> # add a runtime dependency
uv add --dev <package> # add a dev dependency
uv run <cmd> # run anything inside the venv
```
- `pyproject.toml` is the single source of truth for dependencies. Never edit `uv.lock` by hand; it changes only as a side effect of `uv add`/`uv lock`.
- Pin the Python version via `.python-version` (currently 3.12). Do not change it without asking.
## Quality gates
All four must pass before committing:
```bash
uv run ruff format . # formatter (not black)
uv run ruff check --fix . # linter, autofix safe rules
uv run mypy src/ # strict type checking
uv run pytest # tests
```
If `ruff check` reports an error you believe is a false positive, add a targeted `# noqa: <RULE>` with a one-line justification — never disable a rule project-wide to silence one site.
## Type hints
- Every function signature is fully annotated: parameters and return type, including `-> None`.
- Use modern syntax: `list[str]`, `str | None`, `from collections.abc import Sequence`. No `typing.List`, `typing.Optional`, or `typing.Union`.
- No `Any` in new code. If a third-party library is untyped, wrap it in a small typed adapter in `src/<your_package>/compat/`.
- Public dataclasses and config objects use `pydantic.BaseModel` or `@dataclass(frozen=True, slots=True)` — pick whichever the surrounding module already uses.
## Tests
- pytest only; no unittest classes. Test files mirror the source tree: `src/<pkg>/orders/service.py` → `tests/orders/test_service.py`.
- Prefer plain functions + fixtures. Shared fixtures live in the nearest `conftest.py`.
- Parametrize instead of copy-pasting near-identical tests: `@pytest.mark.parametrize`.
- Tests must not hit the network. Mock at the boundary (the HTTP client wrapper), not deep internals.
- Run a focused subset while iterating: `uv run pytest tests/orders -x -q`, then the full suite before committing.
## Layout
```
src/<your_package>/ # all importable code (src layout — never a top-level package dir)
tests/ # mirrors src
scripts/ # one-off maintenance scripts, run via uv run scripts/<name>.py
```
## Rules
- No bare `except:` and no `except Exception` without re-raising or logging with context.
- Use `pathlib.Path` over `os.path`, f-strings over `%`/`.format`, `logging` over `print` in library code.
- New modules need docstrings on public functions; skip docstrings on obvious private helpers.
- Do not commit notebooks, `.env` files, or anything under `.venv/`.