Home / Guides / Cursor rules for Python

Cursor rules for Python backends: AGENTS.md and .cursor/rules

AI agents write Python that imports. The problem is what they quietly skip:

• No project venv. Packages land in the system interpreter, or a new virtualenv appears in a random folder.
• Secrets in source. API keys pasted into settings modules, logged in traces, or committed in .env.
• Tests that never run. pytest is in the README; the agent never invokes it, or it deletes a failing test to go green.
• No type hints on public functions, or a blanket # type: ignore to silence the checker.
• No plan. Auth, migrations, or a destructive cleanup starts as a 400-line diff with no go-ahead.

A short AGENTS.md plus a few .cursor/rules/*.mdc files is the Python Cursor rules template that stops that. Official rule shapes: Cursor rules.

Where the rules go

AGENTS.md at the repo root is the shared source of truth: stack, venv, commands, never-dos, definition of done. Cursor, Codex, Windsurf and others read it. Claude Code picks it up through @AGENTS.md in CLAUDE.md. Path-scoped extras go in .cursor/rules/*.mdc with YAML frontmatter (description, globs, alwaysApply). Which file each tool actually reads: AGENTS.md vs CLAUDE.md vs Cursor rules.

Keep the always-on core tiny. Put pytest details on tests/**, env rules on .env*, and library-specific notes only when those files are in context. One 600-line rule file gets skimmed.

Minimal AGENTS.md for Python

Drop this at the repo root. Fill every <<FILL>>. Point the commands at what you actually run (venv, pytest, ruff or the type checker you use).

# AGENTS.md
<!-- Python backend. Fill every <<FILL>>. -->

## Project
- App: <<FILL: name and one-line purpose>>
- Stack: <<FILL: e.g. Python 3.12, Flask or FastAPI, pytest, ruff>>
- Layout: <<FILL: where src/ (or the package), tests/, and .venv live>>
- Env: repo-root .venv created with python -m venv .venv. Never commit it.

## Commands
- Venv: python3 -m venv .venv && . .venv/bin/activate
- Install: <<FILL: pip install -e ".[dev]" or pip install -r requirements-dev.txt>>
- Test: pytest
- Lint: <<FILL: e.g. ruff check .>>
- Typecheck: <<FILL: e.g. mypy src>>

## Hard rules
- Never print, log, or commit secrets. Read them from the environment.
- Keep .env out of git. .env.example lists names only, never values.
- Type-hint public functions. Do not add # type: ignore to make something pass.
- Never disable, skip, or delete tests to make CI green.
- Use the project venv. Do not install into the system interpreter.
- For auth, payments, migrations, or deleting data: write a short plan and wait for go.

## Workflow
1. Restate the goal in one line and list the files you will touch.
2. Make one small change, then run pytest (and the typecheck you listed).
3. Report what you verified, and what you could not verify.

## Done means
The commands above pass, the change is described in plain words, and you did not expand the scope.

Matching Cursor rule (always on)

Cursor project rules need the .mdc extension and frontmatter. This core rule is the always-apply half of the template. Add glob-scoped files later for tests/** or a framework folder.

---
description: Python backend core (venv, types, tests, secrets)
alwaysApply: true
---
- Use the project .venv. Never install packages into the system Python.
- Type-hint public functions. No # type: ignore to silence the checker.
- pytest for tests. Do not skip or delete tests to make a change pass.
- Secrets come from the environment. Never hard-code them. Never commit .env.
- Plan first for auth, payments, migrations, or destructive ops; wait for go.

How this differs from the FastAPI kit

This page is stack-agnostic Python: any backend, CLI, or library that uses a venv and pytest. The FastAPI guide is the opposite: ownership checks in queries, Pydantic v2, SQLAlchemy 2, Alembic, and four tests per endpoint. Start here if you are not on that stack yet. Switch to AGENTS.md and Cursor rules for FastAPI when routes, migrations, and IDOR are the actual risk.

• This free template: venv, pytest, type hints, no secrets, plan-first. Works for Flask, Django, scripts, and FastAPI repos that only need a baseline.
• DRW-05 Python/FastAPI Backend Kit ($19): fill-in AGENTS.md + CLAUDE.md, 8 scoped Cursor rules (structure, routes, Pydantic v2, SQLAlchemy 2, Alembic, security, testing), 10 prompts, definition-of-done and pre-deploy checklists.

When to buy DRW-05

Buy the FastAPI Backend Kit when all of these are true:

• The app is FastAPI + SQLAlchemy 2 + Pydantic v2, with Alembic for schema changes.
• You want agents blocked from IDOR (ownership filtered in the query, 404 for other users' objects), unreviewed autogenerate, and SQLite-for-Postgres tests.
• You want the prompts and checklists, not only the two files on this page.

If you are still choosing a framework, or the repo is a CLI, keep the skeleton above. You can add FastAPI rules later without rewriting the core AGENTS.md.

FAQ