Rules: .cursor/rules/*.mdc and AGENTS.md

Ask Cursor to add a handler to budgetcli - the course’s illustrative project, a small self-hosted personal-finance API in TypeScript - and it validates the request body with a pile of hand-rolled if checks, even though every other handler in src/api/ runs input through a Zod schema first. Ask it to record when a transaction posted and it writes the timestamp in server-local time, when the rest of the codebase stores everything in UTC and the reconciliation job depends on that. Neither mistake means the agent is careless. Both mean the convention lives somewhere the agent cannot read: in your head, or buried in old review comments. So every session re-derives the project’s conventions from whatever code it can see - and gets the same few wrong, every time.

This chapter ends that re-teaching tax. You write the conventions down once, into files Cursor loads as standing instructions (as of October 2026; Cursor’s rules documentation) - and then you push on the edges, because Cursor doesn’t have one rules file, it has four layers, and the way those layers attach has teeth you’ll hit in a real repo. The thing worth knowing up front: of all the tools in this course, Cursor’s rules system is the richest and the most divergent. Codex and OpenCode give you a single AGENTS.md (the agents.md open standard both read). Cursor reads AGENTS.md too - natively, so your rules stay portable - but layers its own .cursor/rules/*.mdc format on top, with frontmatter that decides when each rule attaches. That extra power is also extra ways to get it subtly wrong.

The four moves of this chapter

• The four rule layers - Project Rules (repo, .cursor/rules/*.mdc), User Rules (yours on every project), Team Rules (org-wide from the dashboard), and AGENTS.md (portable, at the root) - and how they stack additively into the brief the agent works from - The four rule layers
• AGENTS.md - the plain-Markdown layer Cursor reads natively, so the same file is in force on a teammate’s Codex or OpenCode - AGENTS.md: the portable path, the same file Codex reads
• Project Rules - Cursor’s native .mdc format, where three frontmatter fields pick one of four attachment behaviors per rule - Project Rules: .mdc frontmatter and the four rule types
• The sharp edges - the glob-scoped rule that attaches only when the agent reads a matching file (and so can look silently skipped), and where the legacy .cursorrules file actually stands - The sharp edge: globbed rules, and the legacy .cursorrules

The arc runs from the map to the mechanism to the trap. The first lesson lays out all four layers so you know which one a given fact belongs in before you write a line. The second takes the portable layer first, because it’s the cheapest to learn and the one that follows the repo to every other tool. The third opens up Cursor’s own format, where a rule stops being simply on or off and starts having a moment it attaches. The fourth is the one that saves you a debugging session: the most precise-looking rule type in the system has the least reliable attachment, and knowing that changes where you put the conventions you cannot afford to lose. That last point is the chapter’s judgment in miniature: when the agent keeps missing a convention, the fix is rarely a sterner prompt - it’s deciding which layer that convention belongs in - a context decision, what the agent sees on every request - and writing it there once.