# How to Set Up CLAUDE.md for a Python Project


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](/configs/CLAUDE.md) for Python projects using [uv](https://pydevtools.com/handbook/reference/uv.md), [Ruff](https://pydevtools.com/handbook/reference/ruff.md), and [pytest](https://pydevtools.com/handbook/reference/pytest.md).

## 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](https://pydevtools.com/handbook/reference/prek.md) 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](https://code.claude.com/docs/en/best-practices) for CLAUDE.md files.

## Download and install

Fetch the template directly into your project:

```bash
curl -o CLAUDE.md https://pydevtools.com/configs/CLAUDE.md
```
```powershell
Invoke-WebRequest -Uri https://pydevtools.com/configs/CLAUDE.md -OutFile CLAUDE.md
```
Or [view the raw file](/configs/CLAUDE.md) and copy it manually.

## Design decisions

Anthropic's [best practices](https://code.claude.com/docs/en/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:

```markdown
## 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](https://pydevtools.com/handbook/how-to/how-to-write-claude-code-hooks-for-python-projects.md) can block `pip` and bare `python` commands before they execute, auto-format files with Ruff, and inject project reminders. 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:

```bash
curl -o ~/.claude/CLAUDE.md https://pydevtools.com/configs/CLAUDE.md
```
```powershell
Invoke-WebRequest -Uri https://pydevtools.com/configs/CLAUDE.md -OutFile "$env:USERPROFILE\.claude\CLAUDE.md"
```
## Learn more

- [uv: A Complete Guide](https://pydevtools.com/handbook/explanation/uv-complete-guide.md) covers what uv does, how fast it is, the core workflows, and recent releases.
- [How to configure Claude Code to use uv](https://pydevtools.com/handbook/how-to/how-to-configure-claude-code-to-use-uv.md)
- [Claude Code hooks for uv projects](https://pydevtools.com/blog/claude-code-hooks-for-uv.md)
- [Modern Python Project Setup Guide for AI Assistants](https://pydevtools.com/handbook/explanation/modern-python-project-setup-guide-for-ai-assistants.md)
- [Teaching LLMs Python best practices](https://pydevtools.com/blog/teaching-llms-python-best-practices.md)