How models read instructions

There is no parser reading your instructions and enforcing them. The model predicts what a helpful assistant would write next, given everything in front of it. Your instructions are strong evidence about that, not a rulebook.

That single fact explains most of what feels arbitrary about prompting.

Specific beats emphatic

IMPORTANT: always write good code does nothing, because nothing in it changes what the next token should be. Every model already predicts it is writing good code.

Match the error handling in src/errors.ts works, because it points at something concrete the model can read and imitate.

When an instruction is ignored, ask whether a careful new colleague could act on it without asking a follow up question. If they could not, the model cannot either.

Position matters

Instructions near the start and end of the context get followed more reliably than instructions buried in the middle. This is a well documented effect and it is the reason rules files should be short.

A four hundred line rules file is not four hundred lines of guidance. It is a long middle section that competes with itself.

Negatives are weak on their own

"Do not use any" is a weaker instruction than "type every parameter explicitly, and use unknown when the type is genuinely not known."

The negative tells the model what not to predict without giving it a replacement. Pair every prohibition you care about with the thing to do instead.

Examples outrank descriptions

One short example of the output you want is worth several paragraphs describing it. This is why the templates on this site are mostly filled in examples rather than instructions about what a good file contains.

If you find yourself writing a third sentence to explain a format, replace all three with a sample.

Conflicts resolve unpredictably

If your rules file says "never add dependencies" and your message says "add the date library you think is best", the model has to pick. Which one wins is not guaranteed and can change between models.

Keep standing rules and one off requests from contradicting each other. When you genuinely want to override a rule, say so explicitly: "ignore the no dependencies rule this once, and add date-fns."

The rewrite test

When an agent repeatedly does the wrong thing, do not add another line telling it not to. Delete the line that failed and write a different one.

Adding text to a prompt that is already being ignored mostly makes the ignored section longer. Something in the current wording is not landing, and more of it will not help.

Next

Writing a project rules file applies all of this to the file your agent reads on every single task.