The agent didn't misread the code. It read it perfectly. The problem is that code only records what exists. It doesn't record what you chose against. On a solo project those choices live in your head. Add one more person, or one more agent, and they live nowhere.

Four lines before the task

Goal: the one change you want, in one sentence
In scope: files it may edit | Off limits: files and areas it must leave alone
Decisions to keep: choices already made that this task could break
Done when: the check that proves it, run and shown

That's it. It takes about a minute and works in any agent, because it's plain text in the prompt.

Why these four and not ten

• Goal forces one change. If the sentence needs two "and"s, it's two tasks.
• In scope / Off limits keeps the agent out of files that only look related, and keeps its context for the ones that matter.
• Decisions to keep is the line almost everyone skips, and it's the one that prevents most reverts. Keep it to the two or three decisions this task could actually touch, not the whole rulebook.
• Done when turns "looks good" into something you can check. "Tests pass" is weak when the agent wrote the tests.

Where each kind of rule belongs

• True for every task (commands, stack, hard limits): the root AGENTS.md / CLAUDE.md / .cursor/rules.
• True for one folder: a nested file in that folder.
• True for this task: the brief.

When the same decision shows up in three briefs in a row, move it up a level. When a line in the root file hasn't mattered in a month, move it down or delete it.

A quick test

If you can't fill in the four lines, the task isn't ready yet. No prompt fixes that, and it's better to find out before the agent starts than after review.

What's the one decision your agent keeps un-making?

Written with AI assistance.

That's not a prompting skill issue. Code shows the agent what exists. It doesn't show what your team decided to stop doing, or which files actually matter for this task. So the agent fills that gap with a guess.

The fix that holds up best is boring: four lines at the top of every task.

The template

Goal: <one sentence on what should change>
In scope: <files the agent may touch>  |  Off limits: <files or areas it must not touch>
Decisions to keep: <choices the team already made>
Done when: <the check that proves it works, not just "tests pass">

A filled-in example

Say you ask your agent to add a "last edited" date to a post card.

Goal: Show "Edited <relative date>" under the title on PostCard when updatedAt differs from createdAt.
In scope: src/components/PostCard.tsx, src/components/PostCard.test.tsx  |  Off limits: src/api/**, package.json
Decisions to keep: We use date-fns (moment was removed, don't add it back). Dates render through formatRelative() in src/lib/dates.ts, don't write a new helper.
Done when: PostCard.test.tsx covers edited and not-edited cases, and the card shows nothing new when the dates are equal.

Without line 3, there's a decent chance you get a shiny new date helper and a fresh dependency. With it, the agent has no reason to guess.

Why each line earns its place

• Goal keeps it to one change. If you need "and" twice, split the task.
• In scope / Off limits stops the agent from reading half the repo and editing whatever looks related. It also keeps the context window for files that matter.
• Decisions to keep is the line people skip, and the one that prevents most reverts. Write down only the decisions that apply to this task, not your whole rulebook.
• Done when turns "looks good" into something checkable. "Tests pass" isn't enough when the agent wrote the tests.

How it fits with AGENTS.md / CLAUDE.md / .cursor/rules

Keep the rules file short and true for every task: commands, stack, a few hard rules. The brief carries what's true for this task. If a "decision to keep" shows up in three briefs in a row, promote it to the rules file (or a nested AGENTS.md for that folder).

Two habits that make it work better

1. Ask the agent to list the files it plans to touch before it writes code. If the list surprises you, fix the brief, not the diff.
2. When you reject a diff because it broke a team decision, add that decision to the next brief straight away. That's how the list stays honest.

It works the same in Cursor, Codex, OpenCode or Claude Code, because it's just text at the top of the task. Feel free to steal it.

Which of the four lines do you find yourself skipping?

Written with AI assistance.