Writing rules is easy. Writing rules that get followed is a skill.

Rules that work

Specific. “Use two spaces for indentation” is followed. “Write clean code” is not.

Checkable. If you cannot tell whether the rule was followed by looking, neither can the
agent.

Short. A file with twelve rules gets followed. A file with ninety does not, for the same
reason nobody reads a long list of terms.

Explained where it matters. “Never change a test to make it pass — a green suite that
checks nothing is worse than a red one” gets followed more reliably than the bare
instruction, because the reason helps it apply the rule to situations you did not list.

Rules that do not work

Look at these and see why each one fails:

- Write high quality code.
- Follow best practices.
- Make the UI look professional.
- Be careful with performance.
- Handle all errors properly.

Every one is a feeling, not an instruction. This is Lesson 2.2 again, in a new place. Apply
the same test: how would I measure this?

Turn them into something real:

- Every exported function needs a one-line comment saying what it does.
- No function longer than 40 lines.
- Buttons are at least 44 pixels tall so they can be tapped.
- Any database query inside a loop needs a comment explaining why.
- Errors are logged with the full message. Never catch an error and
  continue silently.

Keep it under one page

If your rules file grows past a page, it is doing two jobs. Split it:

  • AGENTS.md — the short list that applies to every task.
  • REVIEW.md — your checklist from Lesson 5.6, used when reviewing.
  • docs/ — longer explanations, referred to by name when needed.

The agent reads the short one every time. You point at the others when relevant.

Add rules when they are earned

Do not sit down and imagine forty rules. You will guess wrong and produce a file nobody
follows.

Instead: when the agent does something you did not want, fix it, then add one line. Within a
few weeks the file is precisely tuned to your project, and every line was paid for.

Try this before the next lesson

  1. Read your AGENTS.md. Find any rule that is a feeling. Rewrite it as something checkable.
  2. Cut it to one page. What did you remove, and why was it there?
  3. Add the reason to your most important rule. See if it gets followed more closely.
PreviousNext