Context Engineering: The team playbook

Playbook

14 min read

How to prompt AI coding agents so the work lands right on the first pass, with fewer bugs and less QA.

The AI is not 100% accurate

Every model we use is very good. None of them is always right.

The cleanest measurement we have is Scale's SWE-Bench Pro, updated in September 2026. It gives top models real coding tasks from real repositories. The same model scores very differently depending on whether it could have seen the tasks before.

Claude Opus 5 on SWE-Bench Pro V2 (Scale, September 2026). Public tasks: 638 of 642. Private tasks: 222 of 272.

On the public tasks, the model solves 99.4%. Scale says that score is "consistent with both genuine capability and recall": the model may have seen those answers in training. On the private tasks, which it has never seen, it solves 81.6%.

Our codebase is a private task. Nobody trained a model on it. So the honest starting point is this: on work it has not seen before, a top model gets it wrong about one time in five.

That fifth time is what we find in QA.

The takeaway

The model is not the problem, and a better model is not the fix. Our job is to move the odds before the agent starts writing code.

Every extra step lowers the odds

A prompt that asks for one thing is one bet. A prompt that asks for five things is five bets, and the agent has to win all of them.

The math is simple. If each step works 85% of the time, the chance that every step works is 85% times 85% times 85%, and so on.

If each step is 85% reliable (one-shot) or 95% reliable (context first), this is the chance the whole job lands. Arithmetic, not a study.

Two things stand out.

One-shot prompts fall off fast.

By step five, a job at 85% per step lands clean 44% of the time. That is close to a coin flip. The other half becomes a bug report.

Context changes the slope.

Raise each step to 95% by building context first, and five steps lands 77% of the time. Same job, same number of steps, very different result.

This chart is the best case. Research on long agent tasks finds that the error rate per step goes up as a task goes on, and Anthropic warns about "the potential for compounding errors" in agents. Real work is usually worse than the simple math.

But steps are not the problem

Unchecked steps are. The fix is not fewer steps. It is a check after each one, so a miss gets caught before the next step builds on it. That is section 4.

Count the steps hiding in one sentence

"Find out why this broke and optimize it" reads like one request. It is at least five steps, and the prompt gave the agent no way to check any of them:

Reproduce the problem

Find the cause

Fix it

Measure the performance

Optimize without breaking anything else

What context engineering is

The model knows a huge amount about code in general. It knows almost nothing about our code: why this screen is slow, what our users do, what "risky" means in our Firebase setup, or what done looks like.

Context is the lens. It points general knowledge at one specific problem.

Context engineering is the work of giving the agent the facts it cannot guess, before it starts changing code.

A good prompt narrows that wide knowledge onto your exact problem. When context is missing, the agent fills the gaps with guesses. Some guesses are right. The rest become bugs.

Anthropic describes context as "a finite resource with diminishing returns." More words do not help. The right facts help.

Where the time goes

Top: a one-shot prompt loops through bugs and QA. Bottom: a few minutes of context, then a clean first pass.

A one-shot prompt feels faster because the agent starts sooner. It is slower in the end, because the time comes back as QA rounds, bug fixes and a second engineer's afternoon.

Rule of thumb

A mistake caught before execution costs a paragraph. A mistake caught in production costs a teammate's day.

Quarterback, not Hail Mary

There are two ways to move a ball down a field.

The Hail Mary.

One long prompt, thrown at the end zone. Diagnose it, fix it, optimize it, make it zero risk. Nothing gets checked on the way, so every miss from section 2 multiplies out of sight. Sometimes it lands. Usually it comes back as a bug report.

The drive.

Short plays that each gain some yards. After every play, you look at what came back before you call the next one. That look is your first-down marker. A bad play costs you one play, not the game. By the time you throw to the end zone, almost everything is known, so the throw is a single bet with high odds.

One long throw that falls short, next to a drive: short gains, a check after each, then the throw.

This is not our invention. Anthropic calls it prompt chaining: "Prompt chaining decomposes a task into a sequence of steps, where each LLM call processes the output of the previous one." They add checks between the steps "to ensure that the process is still on track."

The play call: How, Double-check, Do

Writing all the context yourself is heavy work, and on a busy morning nobody does it. That is how one-liners happen. So let the AI carry the load. You only need three words.

How.

Ask how, not do. The agent has to lay out its approach before it touches any code, and its answer shows you what it assumed. Reading an answer takes far less effort than writing context from scratch.

Double-check.

Send it back to the real code, logs and data to confirm or correct its own plan, then rank what survives. This turns its guesses into facts.

Do.

One job, using the context it just built, with a way to prove it worked.

The AI does most of the labor: the digging, the reading, the writing. You do what only you can do: read, judge and pick.

Example: lowering the Firebase bill

How

How would we lower our Firebase bill? Look at our billing breakdown and
our code before you answer. Don't change anything.

Double-check

Double-check each idea against the actual code and usage data. What did
you assume that turned out not to be true? Drop those, and rank what is
left by savings and risk.

(same session, so it keeps everything it just learned)

Do #2 only. Measure Firestore reads before and after on staging. Existing
tests must pass. Show me the numbers before you commit.

Stay in the session

The context the agent built during How and Double-check is the whole point. A new session throws it away. Start fresh only in two cases:

The next job is unrelated.

That is Rule 2 in section 5.

The drive went badly.

Anthropic's advice: "If you've corrected Claude more than twice on the same issue in one session, the context is cluttered with failed approaches. Run /clear and start fresh with a more specific prompt that incorporates what you learned."

Before you start fresh, have the agent write down what it learned ("Write what you found and what failed to notes.md"), then point the new session at that file. The AI carries the context forward, not you.

Two ways the play call fails

The generic how.

A plain "how do I lower a Firebase bill" comes back as a top-10 tips article that could apply to any company. Fix: ask how we would do it in our code, and tell it where to look before it answers.

The rubber-stamp double-check.

A plain "double-check that" often comes back as "Looks good!" Research backs this up: models reviewing their own answer, with nothing outside their own head to check against, often fail to improve and "at times, their performance even degrades" (Huang et al., 2023). What works is checking against evidence: the code, a log, a test. The single best line is: "What did you assume that isn't true?"

How far to drive

It depends on the length of the field. If you could describe the change in one sentence, just run it. The Claude Code docs say the same: "If you could describe the diff in one sentence, skip the plan." If there is a lot you don't know yet, drive.

You are in the red zone when you could write the final prompt with every question on the checklist in section 6 already answered.

The three rules, from the people who build the tools

None of this is our opinion. These rules come straight from the official docs for Claude Code, the tool we use every day. OpenAI's Codex docs and Cursor's docs say the same things. Think of them as what every play needs.

Rule 1: Give the agent context

Claude Code docs

"Provide specific context in your prompts. The more precise your instructions, the fewer corrections you'll need."

Tell it what is happening now, what should change, what must not change, and what it cannot find on its own.

Rule 2: One job per prompt

Never throw two unlike jobs in one prompt. "Find out why this broke and also optimize it" is two bets riding on one throw, and every miss multiplies (section 2).

A session can still hold more than one job, if you run them as plays. Diagnose, check what came back, then optimize in the same session: what the agent learned in the diagnosis is exactly the context the fix needs. Related plays build context. Unlike jobs thrown together crowd it.

Where the line sits: when the next job is unrelated to what the session knows, start clean. Anthropic lists this as a named mistake, "The kitchen sink session": you start with one task, then ask for something unrelated, and the context fills with information that no longer matters. Their fix: "Run /clear between unrelated tasks to reset context."

Unrelated jobs crowd one context. Related plays in sequence build it.

Rule 3: Give it a way to verify its work

Claude Code docs

"Give Claude a way to verify its work."

A check the agent can run itself: a test, a build, a timing, a screenshot to compare. Write down what done looks like before any code is written, for example "every onboarding screen loads in under 2 seconds on a store with 200+ markets." If the agent can check it, the agent can catch its own mistakes. If it cannot, a person catches them later.

The context checklist

These five questions are what a good prompt answers. You don't have to answer them all yourself. Use them as the test for the agent's "how" answer: did it find each one? Anything it couldn't find is your next "how." Anything nobody can answer is the part the agent will guess.

What is happening now?

A number, an error message, a screenshot, a slow request with its timing.

What exactly should change, and what must not change?

Name the files, the flow or the screen. Name what is off limits.

What does the agent need to know that it cannot find on its own?

Business rules, past decisions, what already failed, what another person is changing.

What does done look like, and how will it prove it?

A target and a check: tests pass, a screen loads under a set time, the build is clean.

Does it need a drive first?

For anything you can't describe in one sentence, run How, Double-check, Do before any code changes.

How much context is enough?

A simple test: could a new contractor who has never seen our codebase do this task well with only what is in your prompt? If not, the agent cannot either.

Remember that the prompt can be the result of a drive. When the checklist is full, you are in the red zone: tell the agent to do it, in the same session.

Before and after

These are real prompts from our own agent sessions this month, lightly trimmed. Each one is a common habit, not a personal failing. Every one of us has written prompts like these.

Two jobs in one prompt

Before

why did wildfoods have the jobsV2 function trigger this morning, also
optimize that function to also prevent cold starts

Two unlike jobs (a diagnosis and an optimization) in one throw, no timings, and no definition of done.

After, play 1

The jobsV2 Cloud Function ran for the wildfoods store this morning and
it should not have. Find out why. Check the function logs for that
invocation and trace what triggered it. Report the cause and the
evidence. Do not change any code.

After, play 2

(same session, once you have read the answer to play 1; what it found in the logs is useful here)

jobsV2 has cold starts of about [X] seconds (from the logs). Reduce
them without changing its behavior. Measure cold-start time before and
after. Existing tests must still pass. Show me the numbers before you
commit.

"Zero risk"

Before

find opportunities to reduce our monthly firebase bill that have zero
risk to implement it

"Zero risk" is a wish, not an instruction. The agent cannot know what is risky in our system until it has looked.

After

a drive, not one prompt. This is the three-prompt play call from section 4: How (look at billing and code, change nothing), Double-check (what did you assume that isn't true? rank by savings and risk), then Do (one fix, measured before and after). The risk question gets answered by evidence, one play at a time, instead of by a wish in the first sentence.

No context at all

Before

There's an 401 error in the oauth flow, investigate what the issue is and
fix it

Which step of the flow? For which stores? Since when? What does a fixed flow look like?

After, if you don't know the answers yet

start with how.

How would you find out why installs are getting a 401 in the OAuth flow?
Look at the logs and the OAuth code first. Don't fix anything yet.

After, once you know them

Stores installing the app get a 401 at [step] of the OAuth flow, starting
[date]. Here is the error and the request: [paste]. Reproduce it on
staging first. Find the cause and explain it before fixing. Done means a
fresh install completes on staging and the existing OAuth tests pass. Add
a test that would have caught this.

What a great prompt looks like: one of ours

This one was written by our own team this month, to fix links broken by a domain change. It is close to perfect. It says what is known, where to look, what users see, what to leave alone, how to check each change, and where to stop.

The boost.shop domain no longer resolves (no A or NS records as of
2026-09-24; the API already moved to api.boostyourstore.com). Image URLs
on assets.boost.shop were handled separately, so leave those alone.
Every other boost.shop link in the repo is now dead. Find them with
git grep. Known groups: wizard setup videos (merchants see broken video
players), help articles, marketing pages, the "Powered by" link, and
referral links. For each group, check whether a working equivalent
exists on boostyourstore.com. Only swap a URL when you have confirmed
the replacement returns 200. List the rest for the user to decide.
Do not commit.

The standard

We already know how to write this prompt. The goal is to write it every time, especially when we are busy.

Case study: the setup wizard

After a large onboarding update, screens in the setup wizard were slow to load. Tracing the fixes back through the repository shows the slowness was not one bug. It was several separate problems stacked up, each one small enough to miss without a measurement:

What the user felt

What the code was doing

Found by

Returning from the trial approval hung

Navigation waited up to 5 seconds for a ready signal, twice in a row, because the signal fired after the navigation started

Code comment in the fix

Opening the app could stall

The install redirect waited on a webhook sync: 21 Shopify calls, 11 to 12 seconds on some stores

Code comment in the fix

Every dashboard load was slow on big stores

Loading full market documents to read one field: 10.9 MB, 2.7 to 4 seconds per load on a store with 237 markets

Commit message in the fix

The charge-return step made extra trips

Three API calls in a row, then setup made a fourth for the same data

The diff

The cart preview blinked and reloaded

The preview reloaded on every step and fetched the same products twice

The diff

These are separate paths, so the numbers should not be added up as one visit. And several of these problems were older than the update. The update just put more weight on them.

What each rule would have caught

Rule 3 (verify) catches almost all of it.

One line in the prompt, "every wizard screen loads in under 2 seconds on a large store; measure before and after," turns every row in that table into a failing check the agent sees itself, before a person does.

Rule 1 (context) catches the big-store cases.

"Test against a store with hundreds of markets" is a fact the agent cannot guess.

Rule 2 (one job per prompt) makes the rest findable.

The update shipped as one commit covering onboarding, trial and branding: 43 files and about 3,200 new lines. When something breaks in a change that size, nobody can easily see which part caused it. Three smaller changes would each have been easy to review, test and roll back.

The pattern is simple. The fixes each took a few lines once someone measured. The expensive part was that nobody measured until after it shipped.

The one-page version

How. Double-check. Do.

Ask how, grounded in our code. Make it double-check its answer against real evidence: "What did you assume that isn't true?" Then do one thing, with a way to prove it worked.

The three rules

Give the agent context.

What is happening now, what should change, what must not change, and what it cannot find on its own.

One job per prompt.

Run related jobs as plays in one session: diagnose, check, then fix. Run /clear between unrelated tasks.

Give it a way to verify its work.

Write the definition of done before any code: a test, a timing, a build, a screenshot.

What a good "how" answer covers

What is happening now? (a number, an error, a screenshot)

What should change, and what must not?

What does it need that it cannot find on its own?

What does done look like, and how will it prove it?

Does it need a drive first?

The contractor test

could someone who has never seen our code do this well with only your prompt? If not, the agent cannot either.

Why it matters

On work it has never seen, a top model is wrong about one time in five.

Misses multiply across steps: five steps at 85% lands 44% of the time. At 95%, it lands 77%.

A drive checks every step, so a miss costs one play, not the game.

Sources

Scale AI, SWE-Bench Pro V2 (September 2026): labs.scale.com/blog/swe-bench-pro-v2

Anthropic, Claude Code best practices, Effective context engineering for AI agents, and Building effective agents: code.claude.com/docs/en/best-practices and anthropic.com/engineering

OpenAI, Codex best practices: developers.openai.com/codex/learn/best-practices

Cursor, Agent best practices (January 2026): cursor.com/blog/agent-best-practices

Huang et al., Large Language Models Cannot Self-Correct Reasoning Yet (2023): arxiv.org/abs/2310.01798