CLAUDE.md for a Python project
Tells Claude which virtual environment to use, how to run tests and lint, and the typing conventions of a Python project. Change the commands to match your tools (uv, pip, poetry).
Tested with Claude Code 2.1.329
Spots to fill
{{project_name}}Project namee.g.billing-service{{python_version}}Python version the project requirese.g.3.12{{package_dir}}Main package foldere.g.billing
CLAUDE.md
# {{project_name}}
Python {{python_version}}, managed with uv. Always run tools through `uv run` so the
project's virtual environment is used.
## Commands
- Install: `uv sync`
- Test all: `uv run pytest`
- Test one: `uv run pytest tests/test_x.py::test_name -x`
- Lint and format: `uv run ruff check --fix . && uv run ruff format .`
- Types: `uv run mypy {{package_dir}}`
Before saying a task is done, run ruff, mypy and the tests that cover what you changed.
## Layout
- Code: `{{package_dir}}/`. Tests: `tests/`, mirroring the package structure.
- Configuration comes from environment variables read in `{{package_dir}}/config.py` only.
## Conventions
- Type hints on every public function; no bare `except:`.
- Prefer dataclasses or pydantic models over loose dicts.
- Use `logging`, not `print`, outside scripts.
- New dependencies go in `pyproject.toml` via `uv add`; explain why in your reply.
## Do not
- Touch `.venv/`, migrations that already ran, or files listed in `.gitignore`.
- Commit `.env` or print secret values.
CLAUDE.md
# billing-service
Python 3.12, managed with uv. Always run tools through `uv run` so the
project's virtual environment is used.
## Commands
- Install: `uv sync`
- Test all: `uv run pytest`
- Test one: `uv run pytest tests/test_x.py::test_name -x`
- Lint and format: `uv run ruff check --fix . && uv run ruff format .`
- Types: `uv run mypy billing`
Before saying a task is done, run ruff, mypy and the tests that cover what you changed.
## Layout
- Code: `billing/`. Tests: `tests/`, mirroring the package structure.
- Configuration comes from environment variables read in `billing/config.py` only.
## Conventions
- Type hints on every public function; no bare `except:`.
- Prefer dataclasses or pydantic models over loose dicts.
- Use `logging`, not `print`, outside scripts.
- New dependencies go in `pyproject.toml` via `uv add`; explain why in your reply.
## Do not
- Touch `.venv/`, migrations that already ran, or files listed in `.gitignore`.
- Commit `.env` or print secret values.