Cursor rules that actually work for coding agents

Cursor rules that run inside the model solve only half the problem. The other half is proving the rule was followed when the code reaches review, which is when mistakes are expensive to fix.

Decide what earns a place in a rule file

A rule belongs in a Cursor rule file only if it corrects a mistake you fix repeatedly in pull requests. If the same issue appears in multiple reviews, write a rule that catches it before the PR. If you have not seen the issue in months, remove the rule.

Rules that work are short and specific. They target one mistake at a time, use concrete examples, and avoid vague language like "should" or "prefer". A rule that says "avoid deeply nested functions" is too broad. A rule that says "do not nest functions more than two levels deep in API handlers" is short, specific, and testable.

Put the rule where the mistake happens. If the problem is in tests, keep the rule in a file under the test directory. If the problem is in API routes, keep the rule in the routes folder. A rule in the wrong place is harder to maintain and easier to ignore.

Two examples that belong in rules

• Remove unused imports detected by ESLint. This mistake appears in almost every PR and wastes reviewer time.
• Avoid console.log in production code. Every time an agent writes a debug statement that ends up in the codebase, someone has to clean it up later.

Two examples that do not belong

• Write clean, maintainable code. Too vague to enforce and impossible to check automatically.
• Follow best practices for error handling. Every project has its own best practices, so this rule is just noise.

If you cannot write a concrete example that breaks the rule, the rule is not specific enough. If you cannot write a failing check that runs outside the model, the rule is not testable.

Make the rule enforceable outside the model

A rule that only exists inside the model is a suggestion. To make it enforceable, pair the rule with a check that runs in CI and fails the build when the rule is broken. If there is no failing check, the rule is being ignored.

Use the simplest check that catches the mistake. If the rule is about unused imports, run ESLint with the no-unused-vars rule. If the rule is about console.log in production, add a grep or a custom script that fails the build when it finds the pattern.

Name the check after the rule so reviewers know what failed. A failing check called "no-unused-imports" tells reviewers exactly what went wrong. A generic check called "lint" does not.

Example: enforce no console.log in production

Create a script called check-console-log.sh that searches the codebase for console.log outside of test files. Add it to CI so the build fails when the pattern is found.

if grep -r "console\.log" src/ --include="*.js" --include="*.ts" --exclude-dir=tests; then
  echo "console.log found in production code" >&2
  exit 1
fi

Add the check to your CI configuration so the build fails when the rule is broken. A failing build is the only signal that matters to an agent.

Sequence the rule and the check with the agent

When an agent starts work, it should read the rule file and then run the check immediately. If the check fails, the agent should stop and ask for clarification before proceeding. This prevents the agent from repeating the same mistake and wasting reviewer time.

If you use Concord, the inspect_work tool can read the rule file and the update_work tool can record the agent’s understanding of the rule before it starts editing. Overlap warnings arrive when an agent claims work, which the five tools each contribute to in a different way.

After the agent finishes its changes, run the same check again. If the check passes, the code is ready for review. If it fails, the agent should fix the issue before the PR is created. This keeps the review focused on design, not on mechanical mistakes.

What to do when a rule keeps failing

If a rule keeps failing despite the check, the rule is either too broad or the check is not catching the right cases. Revisit the rule and split it into smaller, more specific rules. If the check is not catching the cases, refine the check until it does.

If the rule is correct but the agent keeps ignoring it, add a human review step before the PR is merged. The reviewer should verify that the rule was followed and that the check passed. This is a last resort, but sometimes necessary when the agent cannot be trusted to follow the rule.

If the rule no longer applies because the codebase changed, remove the rule. A rule that does not match the current codebase is noise and should not be kept.

When to skip the rule

Skip the rule when the context makes the rule impossible to follow. If the rule says "avoid deeply nested functions" but the API design requires three levels, the rule should be disabled for that file or rewritten to allow the necessary structure. Context matters more than the rule.

Add a comment in the file explaining why the rule is skipped and what the alternative is. This keeps the rule file honest and prevents future reviewers from flagging the same pattern.

If you skip too many rules, reconsider whether the rule file is still useful. A rule file with many exceptions is a sign that the rules are too rigid or the codebase has changed without updating the rules.

Rules exist to prevent mistakes, not to enforce style. If a rule does not prevent a mistake, it does not belong in the file.