How to Brief a Coding Agent Before It Writes a Line

Open a fresh session with a coding agent and ask it to add a feature. It’ll ask reasonable clarifying questions, read whatever files it can find, and make a plan that sounds confident. None of that confidence tells you whether it knows the thing that actually matters: that your team tried this exact approach four months ago and killed it, or that the naming convention it’s about to violate was a hard-won compromise from a meeting nobody wrote down anywhere the agent can read.

A coding agent needs the same thing a new hire needs on day one: the decision history, the constraints already ruled out, and who owns what, not just the current file tree. Without it, the agent re-derives context from scratch every session, at the cost of correctness.

We’ve seen this pattern show up outside the product too. It’s the strongest single message in Thor’s own Reddit testing to date: the campaign built around exactly this idea, that an agent starts every session at zero, ran at roughly double the click-through rate of every other campaign we’ve run there. People recognize the problem the moment it’s named. This post is about what actually fixes it.

What does a coding agent need to know before it writes anything?

It needs the decisions that would change what it builds, not the full history of how the codebase got here. Three things, specifically: what’s already been tried and ruled out, what naming and structural conventions are non-negotiable, and who owns the area of the code it’s about to touch. Leave any one of those out and the agent doesn’t fail loudly. It ships something plausible that’s wrong in a way nobody catches until review, or later.

That’s a narrower ask than “give the agent everything.” Most of a repo’s history doesn’t matter to the next commit. What matters is small, specific, and usually lives in someone’s memory of a Slack thread, not in a file the agent can grep.

A before and after, same starting prompt

Take one prompt: “Add rate limiting to the webhook endpoint.” Two teams. Same codebase, same model, same prompt.

Without Day Zero context, the agent has the file tree and whatever’s in the repo’s README. It picks a reasonable, generic approach: an in-memory token bucket, keyed by IP. Clean code, passes its own tests. Except this team already tried in-memory rate limiting eight months ago and pulled it in a postmortem, because it doesn’t survive a pod restart and doesn’t work across their three running instances. That decision lives in a closed Linear ticket and a Slack thread from March. The agent had no way to see either one, so it rebuilt the exact thing the team already threw away.

With Day Zero context, the same prompt arrives with three lines attached: rate limiting was tried in-memory in Q1 and rejected for not surviving restarts or working across instances; the team standardized on Redis-backed limiters for anything cross-instance; and the webhook module is owned by the payments pair, tag them on anything touching auth headers. The agent reads that, picks the Redis-backed approach the team already committed to, and flags the payments pair for review instead of skipping straight to a PR. Same model. Same prompt. Different, correct output, because the constraints that mattered were sitting in front of it instead of buried in a ticket it never queried.

Why does this beat a bigger model or a longer prompt?

Because the failure isn’t a reasoning problem. It’s a memory problem, and no amount of additional reasoning capacity recovers information the model was never shown. A more capable model asked to add rate limiting with no history of the failed attempt will reason its way to the same plausible, wrong answer, just with cleaner code and more confident phrasing around it.

Anthropic’s own prompt engineering guidance makes a version of this point directly: model quality doesn’t substitute for giving the model the actual, relevant facts it needs for the task in front of it. A longer prompt has the same ceiling. You can paste more of the repo into the context window, and the agent will read more of it, but reading more isn’t the same as reading the three lines that would have changed the plan. Padding a prompt with everything you can find is a worse version of the same problem: now the settled decision that mattered is one paragraph buried in twenty, competing for attention with a hundred lines of markdown nobody needed. The fix isn’t more model or more text. It’s making sure the small set of facts that would actually change the output is what’s in front of the agent, not just possible to find.

What does re-deriving context actually cost?

Tokens and turns spent re-covering ground the team already settled, and a wrong answer at the end of it if nobody catches the gap. When an agent starts from the file tree alone, it doesn’t just risk one wrong guess. It spends real work rediscovering things a person already knows: it might explore the in-memory approach, write it, and only get corrected in review, three turns and a full implementation after a single sentence would have redirected it. Multiply that by a team running agents across a dozen tickets a week, and the tax isn’t hypothetical. It’s the difference between an agent that ships the right thing on the first pass and one that needs a human to catch the same category of mistake over and over.

There’s a second cost that’s easier to miss. It builds up one session at a time, so it never shows up as one big failure worth investigating. Each individual re-derivation looks like normal agent output, a plan that reads fine until someone who remembers the March postmortem happens to review it. The compounding cost is invisible unless someone’s specifically watching for it.

What actually needs to travel with the brief?

Not the repo’s history. Not the last twenty PRs. The short list of things that would change what gets built: rejected approaches and why, hard constraints (naming, architecture, a security requirement that isn’t optional), and who owns the area being touched. That’s a handful of facts, usually traceable to a specific decision, a specific person, and a specific moment, not a document dump.

Travels with the brief	Doesn’t need to
A rejected architecture and the reason it was rejected	The full PR history that led to the current architecture
A naming or structural convention the team enforces	Every file in the module, unfiltered
Who owns the code being touched, for review	The org chart
An active constraint (a compliance rule, a performance floor)	Every constraint the team has ever discussed, including resolved ones

The test for whether something belongs in the brief is simple: would knowing it change what the agent builds? If yes, it travels. If it’s just background that happens to be true, it’s noise, and noise in a context window competes for attention with the fact that actually matters.

How is this different from a system prompt or a CLAUDE.md file?

A system prompt or a CLAUDE.md-style instruction file is fixed at the moment someone writes it. It’s genuinely useful for things that don’t change week to week: coding standards, how to run tests, which directories are off-limits. What it can’t do is stay current with a decision made in yesterday’s design review, because nobody edits that file in real time as the team’s actual state of the world shifts.

Day Zero context is the opposite kind of thing: the live, current answer to “what’s actually been decided,” current enough to reflect a call made an hour ago, not last quarter when the file was last touched. A static instruction file tells an agent how the team likes its code written. It can’t tell the agent that the approach it’s about to take was already tried and killed, or that ownership of a module changed hands two weeks ago, because that information didn’t exist when the file was written and nobody’s job is to keep re-writing it by hand every time something changes.

That’s the practical difference between the two, and it’s also the reason a good CLAUDE.md file and Day Zero context aren’t competing solutions. One is a stable reference; the other has to move at the speed the team actually moves. Coding agents need real context to work from either way, whether that’s a fixed style guide or the live record of what’s actually been decided, and giving Claude Code and Cursor that real context is a different problem from writing a good instruction file, even though the two get confused for each other constantly.

FAQ

Isn’t this just a longer, more detailed prompt?

No. A longer prompt adds volume; Day Zero context adds the specific facts that change the plan. Padding a prompt with everything findable makes the few facts that matter harder to find, not easier.

Does a bigger context window solve this?

No. A bigger window lets an agent read more of what’s already there. It doesn’t put a decision made in a Slack thread or a closed ticket into that window in the first place. The problem is what’s missing, not how much room there is to read it.

Is this the same as a CLAUDE.md or system prompt?

No. Those are fixed at write time and good for standards that don’t change often. What’s been decided about a specific piece of work changes weekly; a file nobody’s re-writing that often can’t track it.

Who has to maintain this, if not a static file?

See Day Zero for how the record stays current without turning into someone’s part-time job of manually updating a doc every time a decision changes.

Does this replace code review?

No. It reduces how often review is catching an agent for rebuilding something the team already rejected, which frees review time for the harder question of whether the new work is actually right.

See how your agents work from one checked answer instead of a stale ticket. Book a demo.