CLAUDE.md for Python

What is CLAUDE.md?

CLAUDE.md is Claude Code's persistent memory file — loaded at the start of every session. It captures what Claude would get wrong by reading the code alone: the non-obvious gotchas, the current focus, and the hard constraints not documented anywhere else. Every line must pass the test: "would removing this cause a mistake?" If not, it shouldn't be there.

CLAUDE.md example for Python

Here is a complete CLAUDE.md for a Python project, optimized to 130tokens using MDPilot's 5-pass optimizer:

# Project
Python package for data analysis

# Current focus
Implementing new feature for data visualization

# Gotchas
* Use `python -m venv .venv` for virtual environment setup
* Requirements are specified in `pyproject.toml` and `requirements.txt`
* Type hints are used with mypy for static type checking
* Use `pip install -e .` for editable install
* Formatting is done with black and ruff, following PEP 8 conventions
* Testing is done with pytest

# Hard constraints
* Python version: 3.9+
* Package manager: pip

Why Python projects need CLAUDE.md

Python projects often involve managing various dependencies, formatting, and testing tools, which can be error-prone if not properly documented. The CLAUDE.md file helps mitigate this by providing a centralized source of information for developers. For instance, specifying the use of `python -m venv .venv` for virtual environment setup and `pip install -e .` for editable install ensures that developers use the correct commands. Additionally, noting the use of type hints with mypy and formatting with black and ruff helps maintain consistency in the codebase.

Frequently asked questions