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...

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.