Writing Cursor Rules That Make AI Behave in an Old Codebase

My first week of agent-driven development in our four-year-old codebase produced beautiful code that violated three team conventions and one architectural decision we had fought about for months. The fix was not better prompting; it was writing down the constitution.

A good rules file is short and negative. Mine lists what the codebase must never do: no new state management libraries, dates are dayjs not Date, every API route validates with the existing zod schemas, and never touch files under legacy/ without asking. Constraints, not aspirations, are what change model behavior.

The unexpected win was documenting the why for each rule in one clause. The model that knows migrations broke last quarter writes more cautious migration code than one merely told be careful. Context converts rules from obeyed to understood, and understood rules generalize to cases you did not list.

Keep a second rules file per directory for local conventions, my components folder has its own, and resist the urge to bloat the global one. I cut my first draft from forty lines to twelve and the diffs got better, because every line you add dilutes the ones that matter.

Six weeks in, the measurable result: convention-violating diffs dropped from about one in three to rarely, and code review comments shifted from style back to logic. The rules file is the cheapest senior engineer I have ever hired.