What makes a good AI coding rule (and what makes agents ignore rules)

After writing agent configs across a dozen stacks, a pattern emerged:
the rules that change behavior share four properties, and the rules
that get ignored fail at least one of them.

1: Concrete acts, not aspirations

Ignored: "Write clean, maintainable code."
Followed: "No unused imports. Delete dead code rather than
commenting it."

Agents cannot operationalize "clean." They can operationalize "unused
imports are removed" because it describes a recognizable state. The
test: if you cannot imagine a specific diff violating the rule, the
rule is not a rule, it is a mood.

2: Trigger conditions, not vibes

Ignored: "Be careful with database migrations."
Followed: "Never edit an applied migration. Fixes happen in new
migrations. Model changes ship with the migration in the same commit."

The second version fires at a recognizable moment, the agent has a
migration file open. Rules attached to situations get applied in
situations.

3: Scoped to where they matter

An always-on rule spends budget on every request, whether relevant or
not. A rule that says "test files use sentence names" only matters
when a test file is being edited, which is exactly what Cursor glob
scoping expresses:

---
description: "Testing conventions"
globs: "**/*.test.ts"
alwaysApply: false
---

Global rules should be reserved for genuinely global behavior (safety
rules, commit format). Everything else gets scoped. This is budget
management: attention is the scarce resource, and scoping is how you
stop paying for rules the current task will never need.

4: Checkable, at least in principle

Weak: "Tests must be high quality."
Strong: "Every bug fix lands with a regression test that fails
without the fix."

The strong version can be verified in review, did the diff include a
test? Was it run against the unfixed code? Rules that can be checked
get enforced; rules that cannot get skimmed. Even rules the machine
cannot fully check benefit from a named evidence: "run the tests and
report actual output" turns a vibe into an artifact.

The failure modes, ranked by frequency

1. The essay. Five paragraphs of context the model summarizes into nothing. Fix: extract the imperative sentences; delete the rest.
2. The duplicate. The same rule in four files "for emphasis." Repetition does not reinforce; it dilutes every other rule by raising the noise floor. Fix: one location, referenced elsewhere.
3. The conflict. Baseline says conventional commits; a tool file says something else. The agent picks one at random, or neither. Fix: baseline is the single source; projections derive.
4. The budget overrun. 900 lines of always-on instructions. Models follow short constraint lists well and long ones selectively; past some ceiling, adding rules reduces compliance with the others. Fix: scope with globs, split into imports, cut without mercy.

A test suite for your own rules

Run each rule in your config through four questions:

• What observable diff would violate this? (concreteness)
• When should it fire? (trigger)
• Does it need to be in everyone's context always? (scope)
• How would a reviewer verify it? (checkability)

Rules that fail two or more get rewritten or deleted. The result is a
shorter config that produces more compliance, which is the whole
game.

These four properties are the design constraints behind every kit in
AgentConfig Studio; the validator enforces the structural ones (scope
declarations, budgets) so the human review can focus on content.

---

If you'd rather not assemble this by hand: AgentConfig Studio on Gumroad ships this as version-pinned, validator-tested kits for 12 stacks. The complete Next.js/TypeScript kit is free (MIT) if you want to inspect the structure first.