Agents working in the same repository can produce locally reasonable but inconsistent code: different error-handling patterns, abstractions, and naming conventions. A .cursorrules file gives Cursor project-specific instructions that provide shared context across those agents. section 5.4.1
Keep the file focused enough to be useful rather than filling every request with a sprawling rule set. A stale rule is especially costly: it can be injected repeatedly even after the code has changed, and the model cannot tell that it is obsolete. section 9.1.3
Listing 5.6 .cursorrules
## Project Context This is a Python payment processing service using FastAPI and SQLAlchemy. All monetary values must use Decimal, never float. ## Code Style - Use the Result type for all service method returns (see src/core/result.py) - Errors are domain objects, not exceptions (see src/core/errors.py) - Repository methods return Optional[Entity], services wrap in Result - All public functions require type hints - Use dependency injection via FastAPI's Depends() ## Testing - Every public service method needs unit tests - Use pytest fixtures from conftest.py, don't create new database connections - Mock external services, don't hit real APIs in tests ## Things to Never Do - Never use datetime.now() - inject TimeProvider instead - Never hardcode configuration - use settings from src/core/config.py - Never commit code that references environment variables directly
This payment-service example groups project context, code style, testing requirements, and prohibitions into a shared set of Cursor instructions. section 5.4.1
Maintain the file as working project context:
- At the end of a session, append a concise rule when you discover a convention worth preserving. section 9.1.3
- Periodically ask an agent which rules it did not use, which duplicate repository information, and which contradict the code; use the answers to triage the file. section 9.1.3
- When a generated-code bug exposes a missing instruction, update the relevant rule to help prevent recurrence. section 9.4.4
.cursorrules is Cursor-specific, so it does not by itself align every tool in a mixed-agent workflow. AGENTS.md offers a tool-agnostic convention for project context, but native support differs by tool and should be checked rather than assumed. section 5.4.1
