Python Claude Code Rules

What it does

A CLAUDE.md / .cursorrules file that primes Claude Code and Cursor with Python best practices — specifically the modern Python toolchain that’s replaced pip/black/flake8 in most serious projects.

Without this, models frequently generate legacy patterns: requirements.txt installs, flake8 configs, missing type annotations.

The rules

# Python Project Rules

## Runtime and packages
- Use Python 3.11+ features where appropriate
- Use `uv` for package management (NOT pip directly)
  - Add dependencies: `uv add <package>`
  - Install dev deps: `uv add --dev <package>`
  - Run scripts: `uv run python script.py`
- Pin exact versions in uv.lock; use ranges in pyproject.toml

## Code style
- All functions must have type hints (parameters and return types)
- Use `from __future__ import annotations` for forward references
- Prefer dataclasses or Pydantic models over bare dicts for structured data
- Use pathlib.Path, not os.path
- Prefer f-strings over .format() or %

## Linting
- Ruff is the linter and formatter (NOT black, flake8, or isort)
  - Run: `uv run ruff check .`
  - Fix: `uv run ruff check --fix .`
  - Format: `uv run ruff format .`
- Never commit code with ruff errors

## Testing
- Use pytest (NOT unittest)
- Test files go in tests/ directory, mirroring src/ structure
- Use pytest fixtures for shared state; avoid global test state
- Run tests: `uv run pytest`
- Aim for >80% coverage on business logic modules

## Error handling
- Use specific exception types; never `except Exception as e: pass`
- Log errors with the standard `logging` module (not print)
- Raise ValueError for bad input, RuntimeError for unexpected state

Installation

# For Claude Code projects:
npx cache add python-claude-rules
# Writes CLAUDE.md to project root

# For Cursor:
npx cache add python-claude-rules --format cursor
# Writes .cursorrules to project root

Why uv, not pip

uv (by Astral) is 10–100× faster than pip and handles virtual environments, lock files, and project metadata in a single tool. It’s rapidly becoming the standard for new Python projects. Models without these rules will default to pip and requirements.txt — technically correct, but not representative of modern Python.