Cursor rules that actually steer (and the ones that just decorate)

The rules file for a client's payments monorepo had grown to something like 900 lines before I admitted it was making Composer worse, not better. I had been adding to .cursor/rules every time the agent did something I did not like, the way you would drop a comment into code. By late May the agent was plainly ignoring half of it and misreading the other half.

The fix was deleting most of it.

I cut the file down to roughly 70 lines, and Composer got noticeably more obedient inside an afternoon. That reversal is the most useful thing I have learned about steering these tools, and it taught me what a rule is actually for.

a rule earns its place by changing an action

A rule pays rent when it changes something the agent would otherwise get wrong. The build and test commands it cannot guess. The convention it has no way to infer from the code. The do-not-touch zone it would happily wander into. Those are load-bearing, and they belong in the file. Here is roughly the shape that survived my cull:

tests: pnpm -w test --changed
typecheck: pnpm -w typecheck
Do not touch packages/legacy-billing; it is frozen until the migration.
In services/, return the Result type from @acme/result, never throw.

Four lines like that change what the agent does on the very next turn. Every one of them maps to a concrete action it would otherwise fumble, which is the only test a rule has to pass.

the stuff that only decorates

Then there is the other kind. Long prose descriptions of the architecture the model can already read straight from the tree. Mission statements. A paragraph about how the team values clean code. The worst offender in my 900-line version was a lovingly written glossary of our domain terms that the model already had ten better examples of sitting three files away. None of it changes a single edit, and all of it costs attention.

A rule the model will not act on is cost. Every line of decoration crowds out the lines that actually steer.

I treat it the way I treat a code comment now: if it only restates what the code already says, delete it. The rules file is a budget, not a scrapbook, and the agent reads it under the same attention pressure that everything else in the prompt is competing for.

the same lesson I learned writing CLAUDE.md

None of this is special to Cursor. It is the identical discipline I use for CLAUDE.md and AGENTS.md, and I wrote the general version up in writing agent context files and the CLAUDE.md specifics in CLAUDE.md in practice. Same failure mode every time: the file grows because adding a line feels productive, and nobody ever pays the cost of pruning until the agent visibly degrades and you go looking for why.

scope beats volume

The other thing that saved my mess was scope. Cursor lets you attach rules per directory, so the frontend rules live near the frontend and the billing rules live near billing, and the agent only carries the ones relevant to where it is working. Splitting one bloated root file into a handful of scoped ones did more for output quality than any single line I ever wrote. If you take one thing from my 900-line embarrassment, make it this: a short rule the agent will actually obey beats a thorough one it quietly ignores, and that pruning muscle is a big part of why Cursor stays worth its fork tax for me.