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

You’ve watched it happen across the last few sessions. You ask Cursor to add a handler to the budgetcli API and it validates the request body by hand with a pile of if checks - even though every other handler in src/api/ runs input through a Zod schema, the convention you standardised on weeks ago. You 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 quietly depends on that. Every session Cursor re-derives budgetcli’s conventions from the code it can see, and every session it gets the same few wrong, because the rules that would prevent it live in your head and in old review comments, not anywhere the agent can read.

This chapter ends that re-teaching tax. You’ll write budgetcli’s hard-won conventions down once, into files Cursor reads on every request - and then 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. 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, User Rules, Team Rules and AGENTS.md, 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 behaviours per rule - Project Rules: .mdc frontmatter and the four rule types
• The sharp edges - the glob-scoped rule that silently doesn’t attach, 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 is the least reliable, and knowing that changes where you put the conventions you cannot afford to lose. The person who’s merely installed Cursor re-explains the same convention every session and re-reviews the same mistake. By the end of this chapter you’ll be the other kind of user - the one whose repo briefs the agent before you type a word.