acribayik synapsis / bosuncadre

How to write briefs AI agents are less likely to get wrong

Most bad output from coding agents isn't the model's fault. When we trace a failure back in our own work, it usually starts with the brief: scoped too wide, missing a constraint, or stating something that stopped being true an hour before the agent read it. Writing a good brief is more of an art than an exact science. But there are patterns, and these are the ones that have saved us the most time.

This guide has two parts. Part 1 works with any agent: Claude Code, Codex, Cursor, a local model, whatever you use. Part 2 is about our own product, and we'll say so clearly when we get there.


Part 1: Writing the brief

1. Check the problem still exists, and put the proof in the brief

An issue or ticket is a claim about the past. Before you brief a fix, run the command that shows the problem today and paste its output into the brief. Then add one line: "If what you see contradicts this, stop and tell me."

Without that, an agent told to "add retries to the client" will add retries, even if they already exist under a different name, and now you have two.

Before: "The ticket says retry logic is missing. Add retries to the HTTP client."

After: "Step 0: search the client package for retry handling. When I checked, there was none. If you find any, the work is already done. Stop and say so; that's a correct outcome."

2. Search by topic, not by the name you were going to use

Searching for the file you plan to create always comes back empty, which feels reassuring and proves nothing. Search for the behavior: the keyword, the test, the concept. Look one level up too: the list of packages, modules or top-level folders. It's surprisingly common to brief a feature that already exists in the sibling directory.

3. Keep each task small enough to finish

Agents run out of turns. A task that needs many rounds of edit, run, check, fix will often deliver nothing at all. If your brief contains "if you run short on time, skip X," it's already too big. Split it.

  • Put the one thing the task exists for first, not last. Setup, then change, then proof means the proof is exactly what a truncated run loses.
  • Ask for a commit before verification. A run that saved its change and then ran out is recoverable. One that ran out before saving is not.
  • Give an honest exit: "If you run low, stop and list which checks you ran and which you didn't. A labeled partial result is acceptable."

4. State the state you want, not the action to avoid

Every warning in a brief is also a suggestion. Write "don't create a new branch" and you've just put branch creation into the agent's head. Write "you're already on the right branch; commit where you are" instead. Mention a hazard only when it's real and named.

5. If it must hold, give it a number

Agents treat the numbered checklist as the checklist and the surrounding prose as background. In our experience, a numbered check ("Check 4: …, pass or fail") is followed far more reliably than the same rule written as a bold paragraph.

6. Bound the scope by a property, not a count

"Fix these two call sites" gets exactly two fixed and leaves the third one, a line below, untouched. "Touch at most three files" rejects a correct fix that needed four. Describe the rule instead: "Every call that passes a raw user ID to the query builder. These are the ones I found, not the limit." If some look-alikes must not change, list those too.

7. Remove every word that can be read two ways

"Keep the old config" (keep using it, or keep it around?), "use it if natural," "point the client at the new endpoint": each has two readings, and the agent will pick the easier one. Prefer actions on named things ("move A to B," "delete A") over states ("keep," "ensure"). And re-read the brief for leftover placeholders. An unfilled <branch-name> in a step the agent has to run is a guaranteed failure.

8. Make every check able to fail

A check that passes before the work is done isn't a check. Before you send the brief, run your acceptance checks against the current, unfixed code. They should fail. Then ask the opposite question: can correct work actually pass them? Common traps:

  • a threshold the code already meets ("at least 4 results" when there are already 6)
  • a test filter naming a test that doesn't exist, which runs nothing and reports success
  • asserting a count instead of which items ("2 entries remain" vs "the two newest entries remain")
  • a negative with no positive: "corrupted files are rejected" is satisfied by rejecting everything

Before: "Add a test that the cache evicts old entries."

After: "With capacity 2 and three inserts, the oldest key is gone and the two newest remain. Assert the keys, not the count. Show the test failing with eviction removed, then passing."

9. Assert facts the agent can check, even if you might be wrong

"The timeout may not be applied consistently" can only be agreed with. "The timeout is applied in the client but not in the retry path" can be checked, and if you're wrong, the agent will tell you. Being wrong in a checkable way beats being vague in a defensible one. Mark your premises as premises: "This is my reading; contradicting it is a valid result."

10. Point to files; don't paste them

A brief that pastes a copy of a file becomes a stale snapshot the moment the file changes, and the agent will faithfully match the snapshot. Name the path and the rule. If you must quote something exact (an error message, an expected value), say the live file wins and any mismatch must be reported, not quietly reconciled.

11. Tell the agent that stopping is a success

Agents rarely refuse an impossible or underspecified instruction. They substitute something plausible and report success: they re-create a file that doesn't exist, invent a path they can't see, or write a test whose name claims the requirement while its body tests something easier. Give them a way out: "If the work is already done, or a requirement here is impossible, stop and say so. That counts as done."

12. Have someone else check the work, and re-run something

The agent's own "all tests passed" is a claim. Ask for the actual command output, and then have a different agent or person re-run at least one check. In our experience, independent re-runs are what catch false passes. Reviewing the work against the brief, not against the author's memory of what it meant, is what catches the rest.

The short version

  1. Prove the problem exists today.
  2. Search by topic before you build.
  3. Keep it small, put the main thing first, commit early.
  4. Describe the state you want, not the mistake to avoid.
  5. Number every rule that must hold.
  6. Scope by property, not by count.
  7. No words with two readings, no placeholders.
  8. Every check must fail on the broken code and pass on the right fix.
  9. State checkable facts; mark premises.
  10. Point to files, don't paste them.
  11. Make "stop and report" a success.
  12. Someone else re-runs the checks.

Part 2: How we do this with BosunCadre

Full disclosure: this part is about our product. Everything in Part 1 works without it.

BosunCadre is a self-hosted control plane for AI work. It doesn't write your briefs for you; the brief is still yours, and still the most important thing. What it does is give a good brief the structure around it that Part 1 asks you to build by hand.

  • Big jobs get split before anyone writes code. A plan-execute pipeline starts with a planning step that breaks the job into smaller tasks in order, which is rule 3 done for you.
  • Review is a separate stage, not a promise. An execute-review pipeline sends every draft to review before anything lands. You set the review chain: a stronger model, an AI session, or several in a row. Every stage has to approve, in order. A rejection with a reason sends the work back for a fresh draft.
  • By default, nothing merges by itself. Approved work waits at a land gate for you (or someone you trust) to land it.
  • Hard tasks go to strong models. Give each model a strength rating and tag a hard task with the strength it needs. BosunCadre offers it first to a model that clears the bar. If none takes it within a short wait, another available model can pick it up, so the task isn't left waiting indefinitely. Mark it strict and it waits for a strong enough model instead. Untagged work can go to any model, including the cheap local one.
  • Tasks only go where they can run. A task can require capabilities, such as a GPU or the ability to run your tests, and only machines that have them will pick it up.
  • Turn limits are a setting. Each task runs under a turn cap set in the runner's configuration, which is one more reason to keep briefs small (rule 3).

BosunCadre is in public beta. If you try it, we'd like to hear which of these rules you'd add to.