How to brief a Cursor agent properly

What changes when you go agentic

A Cursor agent does not just edit the file you are looking at. It searches the repo, opens files you did not mention, edits several of them, and runs commands. You approve, or you do not, and then it keeps going.

That autonomy is why the briefing matters more than it did with inline completion. With completion, a bad suggestion costs you one keystroke to reject. With an agent, a bad framing in message one costs you a fifteen-minute run and a diff you have to read carefully to undo.

The four things a good brief contains

We teach this as a checklist because under time pressure people skip straight to the verb.

• The outcome, stated as a testable condition. Not "fix the cart bug" but "adding a second unit of the same item should update quantity, not create a second line".
• The entry point. One file path saves the agent five minutes of searching and saves you the version where it edits the wrong module.
• The constraint. What it must not change. Public API, database schema, the vendored directory, the file your teammate has open.
• The check. How the agent knows it worked. A test command, a script, a URL to load.

Four sentences. It feels slow the first ten times and then it becomes automatic, and the difference in output is not subtle.

Let the Cursor agent verify its own work

An agent that can run your tests behaves like a different tool from one that cannot. If it can run the check itself, it catches its own mistake in the same turn, silently, and you never see the broken intermediate version.

So the highest-value thing you can do is not prompt engineering. It is making your verification command work from a clean state with no arguments:

npm test -- --run src/cart

Point at the narrow scope when you can. A full suite that takes nine minutes means the agent runs it once and hopes. A targeted run it can do six times in a session actually closes the loop.

Where it goes wrong

The long session. Quality falls after the context fills up, and the tell is consistent: the agent starts reintroducing something you told it to remove forty messages ago. Do not fight it. Start a new session and paste in a two-line summary of where things stand.

The vague verb. Anything phrased as "improve", "clean up", or "make it better" gives the agent no stopping condition, so it keeps going and reformats half the file. If you cannot state what done looks like, you are not ready to hand it over.

The unread diff. Approving edits by reflex is how a codebase acquires three different patterns for the same job in one sprint. Read the diff. If it is too big to read, that is the actual problem, and the fix is smaller tasks.

And repo rules only exist if they are written down. Put your conventions in the project rules file, in version control, so every engineer's agent gets the same instructions. Conventions living in a senior engineer's head do not reach the model.

What to do next

Take your next task and write the four-line brief before you touch the keyboard: outcome, entry point, constraint, check. Do that for one full day. Then compare how often you had to interrupt and redirect against your normal week. Most engineers we train see the interruption count roughly halve, and that is the number worth watching, not the wall clock.

If you want help putting this into practice, talk to us.