Good Instructions Beat Long Instructions In Agent Files

Behaviour Changes When Rules Name Observable Actions

An agent instruction file earns its keep at the moment a decision is made, not at the moment it is written. Most teams treat the file as a storage unit for aspirations: be careful, prefer clarity, keep the test suite green. The agent agrees with every one of those sentences and then follows whatever its defaults already suggest, because none of the sentences tells it which action to take when two reasonable options compete. The remedy is not more volume. The remedy is to name the observable action that should follow a situation the agent can recognise.

Consider the difference between two kinds of sentence. A wish expresses a value; a rule names a trigger, an action, and a check. When a request touches data storage code, open the migration first and refuse to finish while the schema change is missing. That instruction can be followed, skipped, or violated, and a reviewer reading the transcript can tell which one happened. Instructions that can be evaluated are the only instructions that survive a long session, a fresh context, and a different engineer reading the work afterwards.

Side By Side Reading Exposes Intent Executed Differently

Take one genuine requirement and write it into two instruction files, then read them next to each other. The weaker file opens with a paragraph about how much the team values reliability, followed by a list of behaviours that are all grammatically correct and operationally empty. The stronger file opens with three sentences, each of which names something that happens during work and something the agent must do about it. Both files express the same intent. Only one of them changes a single decision.

When you perform this reading, grade every rule against criteria rather than against feeling.

• Does the rule name a situation that the agent can recognise while working, such as a change to stored data or an ambiguous requirement?
• Does the rule prescribe one concrete action instead of an attitude the agent can perform in any way it likes?
• Does the rule include a check that makes compliance visible in the output the agent produces?
• Can a teammate disagree with the rule and point to a specific moment where applying it would have been wrong?
• Would the rule still hold if the session restarted halfway through the task with no memory of the earlier reasoning?

Rules that fail the first three criteria are decoration. Rules that fail the last two are usually overreach, and overreach is quietly ignored, which erodes trust in the rules that matter.

Every Rule Needs A Trigger An Action And A Verifier

The reliable shape of a behavioural instruction is compact and testable. The trigger names the moment, the action names the movement, and the verifier names the evidence. Edit shared helper code and update the two call sites in the same change before you report the task as finished reads as a rule because all three parts are present. The trigger is an edit to shared code, the action is updating the call sites, and the verifier is the state of the change when the agent reports back.

Write triggers in the vocabulary the agent actually encounters during a task. Words like quality, robustness, and elegance describe outcomes and never describe moments. Words like a new endpoint, a failing test, an unclear requirement, or a request to change behaviour describe moments that appear in the middle of real work, which is exactly where a rule has to intercept a choice.

Write verifiers as visible artefacts rather than internal promises. A rule that says to be thorough has no artefact. A rule that says the change is not complete until the named tests pass and the summary lists what was deliberately left untouched has two artefacts a reviewer can inspect without asking the agent anything.

Long Files Teach Agents To Skim Rather Than Obey

Volume has a cost that is hard to see from the authoring side. An instruction file that grows into a catalogue of every preference anyone has ever expressed teaches the agent that most sentences are optional, because no human or model can apply forty overlapping constraints simultaneously. Attention is finite in a context window, and rules compete for it. The rule you care about most is usually the one that loses.

Two symptoms show this clearly. The first is drift, where the agent follows the early rules well and the late rules poorly after a long task. The second is contradiction, where two rules apply to the same situation and the agent silently arbitrates in favour of the one closest to its defaults. Both symptoms are solved by deletion and by ordering, not by adding another paragraph at the end.

• Keep one rule per situation, and merge rules that share a trigger so the agent has a single decision point.
• Put the rules that change expensive or irreversible actions first, because those are the ones that matter when attention runs out.
• Delete any rule you cannot remember violating or enforcing in the last month of work.
• Replace accumulated exceptions with a narrower trigger, since an exception list is usually a sign that the rule was drawn around the wrong moment.

Testing Instruction Files Against Real Sessions Changes Them

The only honest review of an instruction file is a review against transcripts. Read what the agent did in three recent tasks and look for moments where it chose wrongly, chose vaguely, or chose well by accident. Each such moment is either a missing rule, an untestable rule, or a rule that is fine and merely felt lucky. This exercise turns taste arguments into evidence, and it usually deletes more than it adds.

Run the same check on the tooling around the file, because behaviour also depends on what the agent can observe and verify while it works. A relay that forwards each request to the official model named in it, with no substitution, keeps those experiments comparable across families such as Claude, GPT, Gemini, DeepSeek, Kimi, GLM, Qwen and Grok, since a change in behaviour can be attributed to your instructions rather than to a silent swap behind the scenes. BestRelay works with Claude Code, Codex, Gemini CLI and any OpenAI SDK, bills pay as you go from the token counts the provider reports with cache reads and writes priced separately, and pays members a referral commission when people they invite top up. Create a BestRelay account if you want one place to test the same instruction file across model families.

Finally, treat the file as a maintained artefact rather than a monument. Rewrite rules whenever a decision pattern changes, keep the file short enough that a new teammate can read it in one sitting, and judge every sentence by whether it changes what happens next. The craft is not in saying what good work looks like. The craft is in naming the moments where the agent must move differently, so that good work becomes the path of least resistance.