Python Cursor Rules Template

The template requires type hints on all function signatures, and the payoff is bigger for Cursor than for human readers. In an untyped codebase, Cursor guesses what a parameter is from its name — user could be an ORM object, a dict, or an ID — and it will confidently call methods that do not exist. Every annotated signature it can see is one less hallucinated attribute. Typed code makes the next generation of AI edits more accurate; untyped code compounds the guessing.

The specific choices matter too. The rules push collections.abc types (Iterable, Sequence, Mapping) for parameters so Cursor writes functions that accept any conforming input rather than demanding a concrete list. TypedDict and dataclasses replace the anonymous dict-shaped blobs Cursor otherwise passes between functions, and Protocol gives its duck-typed interfaces a name that mypy can actually check. The Optional[T] rule keeps signatures valid on Python 3.9 — if your floor is 3.10+, swap it for T | None with a custom rule.

The flat layout — package directory sitting next to your tests at the repo root — has a trap that AI assistance makes worse: Python puts the working directory on sys.path, so imports resolve against your checkout instead of the installed package. Tests pass locally, then the published wheel is missing a module. Cursor falls into this constantly, because flat-layout repos dominate its training data and it cannot tell the accidental import from the intentional one.

Moving code under src/ makes the package importable only when properly installed, so broken packaging fails immediately instead of at release. The companion rules — pyproject.toml as the single configuration file, tests/ mirroring the source tree, explicit __init__.py boundaries — give Cursor an unambiguous answer to "where does this file go", which is otherwise the question it answers most randomly in Python projects.

One thing the template deliberately does not pick: your installer. uv, Poetry, and plain pip all read pyproject.toml. But Cursor defaults to suggesting pip install in chat, so if you use uv or Poetry, add a custom rule like "This project uses uv; never suggest pip install or requirements.txt" — otherwise its setup instructions will drift from your lockfile.

Ask Cursor to "make this more robust" and it will wrap the body in try: ... except: pass. That bare except catches SystemExit and KeyboardInterrupt along with the error it meant to handle, turning a crash you would have seen into silence you will not. The rules require naming the exception type, and offer contextlib.suppress for the genuinely-expected-failure case — which reads as intent instead of negligence.

The print() ban is the same fight at a different layer. Cursor reaches for print because it appears in millions of tutorials, but print gives you no level, no timestamp, and no way to silence it without editing code. Requiring the logging module — with traceback info on error paths, per the rules — means the diagnostics Cursor adds while "debugging" are still useful after deploy instead of polluting stdout.

A related default worth adding as a custom rule if it bites you: mutable default arguments (def f(items=[])). Cursor still generates them under pressure, and the shared-state bug they cause only appears on the second call. The dataclass rule reduces the surface area, but an explicit "default to None, create inside the function" line closes it completely.

The style section pins Black's conventions: 88-character lines, double quotes, four spaces, snake_case. None of these is objectively better than the alternatives — the point is that they are the settings Black and Ruff apply without configuration, so Cursor's output and your formatter never disagree. When rules and formatter conflict, every AI-generated file produces a noisy reformat diff, and reviewers stop being able to see the actual change.

If your team standardizes on something else — 79-character lines for strict PEP 8, single quotes — change it in the generator rather than editing the exported file, so the quote and indent placeholders stay consistent across every section. The one rule to keep regardless: PascalCase for classes, snake_case for everything else. Cursor ports camelCase into Python whenever it has recently been editing JavaScript in the same session.