Claude Code for Python Developers

1. Python Environment Setup

Claude Code inherits the shell environment you launch it from. The single most important thing: activate your virtual environment before running claude.

python -m venv .venv
source .venv/bin/activate   # macOS/Linux
.venv\Scripts\activate      # Windows PowerShell

# Verify Claude uses the right Python
claude  # then ask: "which python are you using?"

#!/bin/bash
if [[ -f ".venv/bin/activate" ]]; then
  source .venv/bin/activate
elif [[ -f "venv/bin/activate" ]]; then
  source venv/bin/activate
fi

conda activate myenv
claude

# Or with mamba:
mamba activate myenv
claude

pip install uv
uv venv
source .venv/bin/activate
uv pip install -r requirements.txt
claude  # Claude can also run "uv run pytest" etc.

2. Python CLAUDE.md Template

Drop this in your project root as CLAUDE.md and customize it. Claude reads this every session — good setup here saves minutes every time you start.

3. pytest & TDD Workflow

Claude Code's most powerful Python workflow is test-driven development. The loop is tight: write a failing test, implement the code, verify green.

The TDD Loop with Claude

Useful pytest Prompts

4. Django / Flask / FastAPI Patterns

"Create a Django model for a BlogPost with: title (unique, 200 chars), slug (auto-generated from title), body (TextField), published_at (nullable), author (ForeignKey to User), tags (ManyToMany). Then generate the migration."

"Add a class-based ListView for BlogPost that: filters by tag query param, paginates by 10, and uses a template at templates/blog/list.html. Wire it to urls.py at /blog/."

"Create a DRF ViewSet for BlogPost with: list (public), retrieve (public), create/update/destroy (staff only). Use a HyperlinkedModelSerializer. Register it with the router in api/urls.py."

"Write a management command in management/commands/import_posts.py that reads a JSON file path from args, validates each entry against the BlogPost schema, and creates or updates records. Add --dry-run flag."

"Register BlogPost in admin.py with: list_display showing title, author, published_at; list_filter on tags and published status; search_fields on title and body; inline for Comments."

"Create a FastAPI router for /items/ with: GET (list with pagination), POST (create), GET /{id}, PUT /{id}, DELETE /{id}. Use Pydantic v2 models for request/response. Store in a SQLAlchemy 2.0 session (dependency-injected)."

"Add JWT authentication to the FastAPI app: /auth/token endpoint that accepts username+password, returns JWT; a get_current_user dependency using python-jose; apply the dependency to all /items/ routes."

"Add a background task that sends a confirmation email when a new Item is created. Use FastAPI's BackgroundTasks. The email function should be in services/email.py."

"Convert the SQLAlchemy session to async using asyncpg. Update all repository functions to use async def and await. Keep the sync session available for Alembic migrations."

"Write pytest tests for all /items/ endpoints using TestClient. Include: happy path, validation errors, 404 cases, and auth failures. Use a SQLite in-memory database fixture."

"Refactor the Flask app to use blueprints. Create blueprints for: auth (/auth), api (/api/v1), admin (/admin). Each blueprint should have its own routes.py, models.py, and forms.py."

"Add a User model using Flask-SQLAlchemy with: id (UUID primary key), email (unique, indexed), password_hash, created_at, is_active. Add a classmethod for creating users with hashed passwords."

"Create a WTForms form for user registration with: email (Email validator), password (Length 8-128), confirm_password (EqualTo). Add server-side validation that checks email uniqueness."

"Write pytest tests using Flask's test client. Add a fixture that creates a fresh in-memory SQLite database for each test. Include tests for the auth blueprint: register, login, logout, protected route."

5. Data Science Workflow

Claude Code is a strong data science assistant — it reads CSV/Parquet files, writes and refines analysis code, and can run scripts directly.

Analysis Workflow

# Step 1: Explore the data
"Read data/sales_2025.csv. Describe its shape, dtypes, missing value percentages, and statistical summary for numeric columns. Flag any data quality issues."

# Step 2: Clean and transform
"Write a pandas pipeline in src/clean.py that: drops rows where revenue is null, fills missing category with 'Unknown', converts date_str to datetime, and exports to data/sales_clean.parquet."

# Step 3: Analyze
"Read data/sales_clean.parquet. Group by region and quarter, compute total_revenue, avg_order_value, and order_count. Sort by total_revenue desc. Export to reports/by_region.csv."

# Step 4: Visualize
"Create a matplotlib figure with 2 subplots: (1) revenue by region as a bar chart, (2) revenue trend over quarters as a line chart per region. Save to reports/revenue_analysis.png at 150 DPI."

# Step 5: Optimize slow code
"Profile process_large_file() using cProfile. Show the top 10 slowest functions. Then rewrite it using vectorized pandas operations and measure the speedup."

Pandas-Specific Patterns

6. Type Annotations & mypy

Claude Code writes fully typed Python by default when you ask for it — and it can retrofit annotations to legacy codebases.

Adding Types to an Existing Codebase

# Annotate a whole module
"Add complete type annotations to every function in src/utils.py. Use TypeVar for generic functions. Run mypy after and fix any errors."

# Fix mypy errors
"Run mypy src/ and share the error output. Fix all errors without changing the runtime behavior."

# Strict mode
"Enable mypy strict mode in pyproject.toml. Fix all resulting errors in src/. External packages can use type: ignore[import] if stubs don't exist."

# Complex types
"Replace the Dict[str, Any] return type in parse_config() with a TypedDict that documents all expected keys and their types."

Modern Python Types (3.10+)

# Claude understands modern syntax
"Use Python 3.12 type syntax: X | Y unions (not Optional[X]), list[int] (not List[int]), dict[str, int] (not Dict[str, int]). Update all annotations in the codebase."

# Protocols
"Replace the duck-typed Processor class with a typing.Protocol. Any class implementing process(data: bytes) -> str should satisfy it without inheriting."

# TypeGuard
"Add a TypeGuard function is_valid_user(obj: object) -> TypeGuard[User] to validators.py that narrows the type for the rest of the branch."

7. Debugging Patterns

Effective Debugging Prompts

# Stack trace → root cause
"Here's a stack trace from production: [paste trace]. Read the relevant source files and identify the root cause. Propose a fix with a regression test."

# Reproduce first
"I'm getting an intermittent KeyError in process_queue(). Add logging to reproduce the issue. Once we can reproduce it consistently, write a failing test."

# Performance debugging
"The API response time for /api/users/ is 2s. Add Django Debug Toolbar or use django-silk to profile the query count. Report N+1 issues and fix them with select_related/prefetch_related."

# Memory leak
"The process RSS grows by 50MB per hour. Use tracemalloc to snapshot memory at startup and after 1000 requests. Diff the snapshots and identify what's accumulating."

# Async debugging
"The asyncio event loop is blocking somewhere. Add asyncio.set_event_loop_debug(True) and look for coroutines taking >0.1s. Report the culprit."

Python-Specific Gotchas Claude Knows About

• Mutable default arguments (def f(x=[]): → shared across calls)
• Late binding closures in list comprehensions and loops
• GIL contention — when to use multiprocessing vs threading vs asyncio
• Integer caching (-5 to 256 are singletons; use == not is)
• Circular imports in Django and FastAPI apps
• SQLAlchemy lazy loading in async contexts
• Pandas SettingWithCopyWarning and when .copy() is needed
• __slots__ vs dataclasses vs attrs for performance-sensitive classes

8. 30 Python-Specific Prompts

FAQ

Related Guides

• Getting Started with Claude Code — install, first session, essential commands
• Development Workflow Guide — TDD, git branching, PR review, CI/CD
• Best Practices — CLAUDE.md structure, cost control, context management
• Prompt Library — 60+ copy-paste prompts for every task type
• Hooks — auto-activate venv, run linters after saves
• Sub-Agents — parallel agents for multi-service Python systems
• Troubleshooting — auth errors, slow sessions, context issues
• All Claude Code Guides →