Skip to content

How to Set Up CLAUDE.md for a Python Project

by Tim Hopper · Markdown
AI Assistants uv

Claude Code loads a project CLAUDE.md as standing instructions. Use the handbook template as a starting point, then keep only the commands and conventions that apply to your repository.

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 Pyrefly, ty, or mypy
  • Pre-commit hooks with prek or pre-commit
  • Anti-patterns Claude should avoid (manual venvs, pip install, requirements.txt)

Keep the final file concise. Anthropic’s instruction guidance recommends specific, verifiable rules and links to longer reference material.

Download and install

Download a separate copy so an existing instruction file stays available for review:

curl -fLo CLAUDE.template.md https://pydevtools.com/configs/CLAUDE.md

The command writes CLAUDE.template.md. Review it and merge the relevant instructions into CLAUDE.md, or rename it when no project instruction file exists. You can also view the template and copy the relevant sections.

Keep instructions specific to the project

Use the template’s uv commands for a uv-managed project. Preserve an existing Poetry, Hatch, or other environment workflow unless migration is intentional. Name the actual check commands and config locations rather than adding every possible tool.

For a repository shared with other coding agents, consider AGENTS.md. Claude Code’s instruction-file selection determines whether it reads CLAUDE.md, AGENTS.md, or both; avoid maintaining conflicting copies.

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`

Verify the commands and add automation where useful

Start Claude Code in the project and open /memory to confirm the instruction file loaded. Ask it to run the listed test, lint, and type-check commands. Inspect the actual commands and results; the template guides behavior but does not enforce correctness.

Claude Code hooks can format supported file edits and return failed checks to the agent. Keep required CI checks for the final commit.

Keep personal preferences separate

Use ~/.claude/CLAUDE.md for preferences that apply across your projects. On Windows this is in your user profile directory. Merge relevant preferences into any existing file rather than replacing it with a project template.

Last updated on