Claude Code for Python: Practical Project Setup and Workflows

Claude Code is Anthropic’s terminal coding agent for Python projects. When you run claude in a project folder, it can inspect code, edit files, and execute the same commands you use locally. The practical value comes from combining it with a clean Python setup: an activated virtual environment, a CLAUDE.md instructions file, and standard tools like pytest, ruff, and mypy.

Claude Code’s strengths for Python development

Claude Code works directly with source files and shell commands, which is exactly what Python development requires day to day. It can read a pyproject.toml, run pytest -q and ruff check ., then apply changes and re-run the checks. Unlike a chat-only assistant, it operates in the project directory, so it can respect the active .venv if you activate it before starting. For Python codebases, this means it can add type hints, write tests, fix lint errors, and explain import chains without leaving the terminal. The agent also reads CLAUDE.md, so you can standardize how Python code should be written and tested in the repository. See Claude Code for the core workflow.

Setting up a Python project for Claude Code

The most important file is CLAUDE.md at the repo root. It should contain command lines, environment activation, path conventions, and project-specific rules that the agent must follow. Start with:

• python -m venv .venv
• source .venv/bin/activate
• python -m pip install -e ”.[dev]” Then configure ruff, mypy, pytest in pyproject.toml. Put only what is needed: commands, folder layout, dependency rules, and explicit do-not-edit paths such as generated migrations or lockfiles.

# CLAUDE.md

## Environment
- Activate: source .venv/bin/activate
- Python: 3.12
- Install: python -m pip install -e ".[dev]"

## Commands
- Run tests: pytest -q
- Lint: ruff check .
- Format check: ruff format --check .
- Type check: mypy src

## Conventions
- Source lives in src/, tests in tests/.
- All public functions need type hints and a docstring.
- Use pathlib.Path for filesystem paths.
- Do not edit generated files under migrations/versions/ unless asked.
- Keep dependencies in pyproject.toml; do not run pip install directly without recording it.

## Rules
- Stop if a command fails and report the exact output.
- Run ruff check . and mypy src before pytest -q.
- Prefer smaller diffs; do not refactor unrelated code.

This checklist approach is covered in Claude Code best practices: a practical checklist. The point is not to document everything; it is to make the agent’s first run match your existing Python workflow instead of improvising.

A practical edit-then-verify loop

Use the same loop you would with a careful engineer:

1. Plan: describe the task and ask the agent to inspect the relevant modules before editing. Use plan mode if you want a proposal before changes.
2. Small steps: one function, type fix, or test at a time. Avoid broad refactors.
3. Run the tests: after each change, have the agent run the smallest relevant test first, then the full suite.
4. Review the diff: check git diff --stat, then git diff before committing. Look for dependency changes, import additions, and type ignore lines.

Example prompts:

• Read src/orders/service.py and tests/test_orders.py, then plan how to add a cancel_order function for orders still in PENDING state.
• Add type hints to src/orders/schemas.py and fix mypy errors without changing runtime behavior.
• Write a pytest test for apply_discount when the discount is 100%. Run only that test.
• Fix all ruff errors in src/ but do not touch tests/.
• Run pytest -q, mypy src, and ruff check .; show the output and summarize failures.

High-value Python tasks and common failure modes

Well suited:

• Adding and correcting type hints based on mypy feedback.
• Writing tests for existing functions, including parameterized cases.
• Fixing ruff errors and formatting issues.
• Updating pyproject.toml dependency groups and explaining import errors.
• Converting small synchronous functions to async when the surrounding code is already async.

Pitfalls:

• Environment activation: if the agent invokes python instead of .venv/bin/python, it may run outside the venv. Activate the venv before starting claude, or state the interpreter path in CLAUDE.md.
• Package managers: pip, poetry, uv, and pip-tools have different lockfiles. Do not let the agent switch tools or edit lockfiles without review.
• Mypy suppressions: the agent may add # type: ignore rather than fix the underlying type. Review each suppression and ask for an explanation.
• Import side effects: Python modules can run code at import time. A harmless refactor that changes import order can break tests or configuration.
• Dynamic features: code using getattr, eval, metaclasses, or monkeypatching is hard for static analysis and the agent may misread it.
• Generated files: migrations, proto files, and compiled artifacts should be explicitly off-limits in CLAUDE.md.

Testing gates: pytest, ruff, and mypy

Treat the agent’s changes as you would a CI run. Require three gates before considering a task done: pytest -q passes, ruff check . passes, and mypy src has no new errors. For fast iteration, ask for a single test file: pytest tests/test_orders.py -q. When coverage is available, use pytest --cov=src --cov-report=term-missing to see if new code is actually exercised. After each task, inspect git diff --stat and git diff; watch for changes to pyproject.toml, lockfiles, and tests that were not requested. If the agent suggests changing a test to make it pass, stop and ask why the production code changed instead. The same discipline in Claude Code best practices: a practical checklist applies to verification.

Parallel work with AgentVera on Python

AgentVera is a desktop app that runs Claude Code and other coding agents’ real CLIs side by side, each in its own terminal panel. For Python work, the most useful features are separate git worktrees, automatic code review, and checkpoints. With separate worktrees, several agents can edit different modules or tests without overwriting each other’s files. After each turn, a second model reviews the code and links findings to file:line, which catches Python-specific issues such as a missing import or an overbroad type ignore. Checkpoints let you undo a bad refactor in one click and replay the session step by step. Token budgets keep parallel runs from exhausting your account while preserving the conversation.

Final recommendation

Claude Code becomes a dependable Python teammate when the project is already disciplined: a clear CLAUDE.md, an activated virtual environment, standard lint and test commands, and a review loop. Start with small, typed changes, let the agent run the checks, and always read the diff before committing. For larger efforts, parallel worktrees and checkpointed sessions make it possible to run several Python changes at once without stepping on each other.