CLAUDE.md template for Python
pytest, ruff, virtual environments and migrations.
CLAUDE.md
# Python project A Python project tested with pytest. Change any command below that differs from how this repo is set up (pip, uv, poetry). ## Commands ```bash python -m venv .venv && source .venv/bin/activate # create and enter a virtual environment pip install -e .[dev] # install the project and dev tools pytest # run the tests ruff check . # lint ruff format . # format mypy . # type-check, if the project uses mypy ``` Run the tests and the linter after every code change, and fix failures before saying a task is done. ## Layout - Package code lives in src/<package>/ (or the top-level package folder) and tests in tests/, mirroring the package layout. - Scripts and one-off tools go in scripts/, not inside the package. - Dependencies are declared in pyproject.toml or requirements files, never installed ad hoc. ## Conventions - Type hints on public functions. Prefer dataclasses or pydantic models over loose dicts. - Raise specific exceptions. No bare except and no silent pass. - Write a failing test first for a bug fix, then fix it. - Match the style of the file you are editing. Do not reformat files you did not change. ## Database - Database schema changes go through migrations (Alembic, Django migrations or the equivalent), checked into the repo. Never edit a migration that has shipped. - Never run drop, truncate or reset commands against a shared or production database. - Tests use a throwaway database or fixtures, never real data. ## Secrets - Never read, print, edit or commit .env files, credentials, API keys or private keys. - Use placeholder values in examples and tests. If a secret shows up in a file or a log, stop and tell me. ## Deploys - Never deploy to production. I run production deploys myself. - Do not change deployment config, Dockerfiles or CI settings without asking. ## Git - Make small commits on a branch and write messages that say why the change was made. - Never run git push --force, git reset --hard, git clean, git checkout -- <file>, git stash or git rebase, and never use --no-verify. Ask first. - Do not push unless I ask. ## Do not touch - Lock files (poetry.lock, uv.lock, requirements.txt pins): do not edit by hand, and do not add or upgrade dependencies without asking. - Migrations that have already shipped, and anything marked generated or do not edit. - The .venv/ folder and any data/ folder holding real data.
AGENTS.md
# AGENTS.md: Python project Instructions for any coding agent working in this repository. A Python project tested with pytest. Change any command below that differs from how this repo is set up (pip, uv, poetry). ## Commands ```bash python -m venv .venv && source .venv/bin/activate # create and enter a virtual environment pip install -e .[dev] # install the project and dev tools pytest # run the tests ruff check . # lint ruff format . # format mypy . # type-check, if the project uses mypy ``` Run the tests and the linter after every code change, and fix failures before saying a task is done. ## Layout - Package code lives in src/<package>/ (or the top-level package folder) and tests in tests/, mirroring the package layout. - Scripts and one-off tools go in scripts/, not inside the package. - Dependencies are declared in pyproject.toml or requirements files, never installed ad hoc. ## Conventions - Type hints on public functions. Prefer dataclasses or pydantic models over loose dicts. - Raise specific exceptions. No bare except and no silent pass. - Write a failing test first for a bug fix, then fix it. - Match the style of the file you are editing. Do not reformat files you did not change. ## Database - Database schema changes go through migrations (Alembic, Django migrations or the equivalent), checked into the repo. Never edit a migration that has shipped. - Never run drop, truncate or reset commands against a shared or production database. - Tests use a throwaway database or fixtures, never real data. ## Secrets - Never read, print, edit or commit .env files, credentials, API keys or private keys. - Use placeholder values in examples and tests. If a secret shows up in a file or a log, stop and tell me. ## Deploys - Never deploy to production. I run production deploys myself. - Do not change deployment config, Dockerfiles or CI settings without asking. ## Git - Make small commits on a branch and write messages that say why the change was made. - Never run git push --force, git reset --hard, git clean, git checkout -- <file>, git stash or git rebase, and never use --no-verify. Ask first. - Do not push unless I ask. ## Do not touch - Lock files (poetry.lock, uv.lock, requirements.txt pins): do not edit by hand, and do not add or upgrade dependencies without asking. - Migrations that have already shipped, and anything marked generated or do not edit. - The .venv/ folder and any data/ folder holding real data.
Why it says what it says
Environment and commands
Without the setup and test commands the agent installs packages globally or runs the wrong runner. Writing them down keeps the environment clean.
Tests first for bugs
A failing test proves the bug exists and proves the fix. It is the cheapest check an agent can run on itself.
Migrations
Schema drift and edited migrations are hard to unwind. The rule keeps changes additive and reviewable.
Deploys are yours
Production changes are rarely something to delegate. One line removes the ambiguity.
Do not touch list
Lock files and shipped migrations are the files where an automatic edit does the most harm for the least visible gain.