Skip to content

How to use the pydevtools CLAUDE.md template for Python projects

by Tim Hopper

Claude Code reads a CLAUDE.md file in your project root every session. Without one, it falls back to pip install, bare python commands, and setup.py.

The Python Developer Tooling Handbook maintains a CLAUDE.md template for Python projects using uv, ruff, and pytest.

What the template covers

  • Package management with uv (uv add, uv run, uv sync instead of pip)
  • Project creation with uv init and pyproject.toml (never setup.py)
  • Testing with pytest (discovery conventions, file layout, execution)
  • Linting and formatting with ruff
  • Type checking with ty or mypy
  • Pre-commit hooks with prek or pre-commit
  • Anti-patterns Claude should avoid (manual venvs, pip install, requirements.txt)

At 86 lines, the template stays inside Anthropic’s recommended 200-line limit for CLAUDE.md files.

Download and install

Fetch the template directly into your project:

curl -o CLAUDE.md https://pydevtools.com/configs/CLAUDE.md

Or view the raw file and copy it manually.

Design decisions

Anthropic’s best practices recommend a pruning test for every line in a CLAUDE.md: “Would removing this cause Claude to make mistakes?”

Included (things Claude gets wrong without guidance):

  • Use uv run instead of calling tools directly. Claude otherwise calls bare python or pytest, which may resolve outside the project’s virtual environment.
  • Use uv add instead of editing pyproject.toml by hand. Claude tends to add dependency lines manually, which skips resolution and lockfile updates.
  • Use uvx for one-off tools. Claude defaults to pip install for tools like prek and pre-commit.
  • Never create requirements.txt. Claude’s training data is saturated with pip-based workflows.

Excluded (things Claude already knows):

  • Python language conventions and standard library usage
  • How pytest assertions work
  • Git basics
  • General code quality advice (“write clean code”)

Customize for your project

Add project-specific rules after the standard sections:

## Project-specific rules

- ORM: SQLAlchemy 2.0 style (use `select()`, not `session.query()`)
- API framework: FastAPI with Pydantic v2 models
- Database migrations: `uv run alembic upgrade head`

Combine with hooks for enforcement

Claude Code hooks can block pip and bare python commands before they execute. A CLAUDE.md tells Claude what to do; hooks prevent it from doing the wrong thing.

Apply globally

To use these rules across all your Python projects, copy the template to your user-level CLAUDE.md:

curl -o ~/.claude/CLAUDE.md https://pydevtools.com/configs/CLAUDE.md

Learn more

Get Python tooling updates

Subscribe to the newsletter
Last updated on
How to use private package indexes with uvHow to use ty in CI

Please submit corrections and feedback...