Use Claude Cowork to fix a bug

Give Claude Cowork four things: the symptom, a way to reproduce it, the area you suspect, and how you will know it is fixed. Then read the diff it returns before you merge anything. That loop turns a vague "this is broken" into a focused, checkable task an agent can finish without you sitting next to it.

This guide is the bug-fixing version of a good Cowork brief. If you have not written a brief before, read briefing Claude Cowork first; this one applies the same idea to the specific shape of a bug.

What goes in a bug brief for Claude Cowork?

A bug report written for a human ("login is broken, please look") works because the human can ask you questions. An agent running in the background cannot. So you front-load the four things it would otherwise have to guess.

The symptom and the pass condition are the two ends of the loop. The symptom says where you are now; the pass condition says where you need to be. Everything Cowork does in between is in service of moving from one to the other.

Part 1: state the symptom precisely

A precise symptom is observable and specific. "Slow" is a feeling. "The dashboard takes nine seconds to load on first paint, every time" is a symptom. Include:

• The exact action that triggers it (which page, which button, which command).
• The exact wrong result (the error message, the wrong number, the missing element).
• The expected result, so the gap is explicit.
• Whether it happens every time or only sometimes.

A bug that fails every time and a bug that fails one time in twenty need different approaches. Tell Cowork which one you have so it does not waste a run chasing a race condition that is a typo, or vice versa.

Part 2: give it a way to reproduce

The single most valuable thing in a bug brief is a reliable repro. If Cowork can make the bug happen, it can confirm when it stops happening. Without that, the agent is editing in the dark.Common gotchaWatch for a repro that only works on your machine: one that leans on a specific database row, a logged-in session, or local files the agent never has.It reproduces for you and silently never fires for Cowork. Give it seed data or a fixture so the same steps trigger the bug in a clean checkout.

A repro can be steps, a command, or a failing test. A failing test is best, because it doubles as the pass condition: when the test goes green, the bug is fixed. If you do not have one yet, you can ask Cowork to write the failing test first.

# A repro that doubles as the pass condition: one failing test.
npm test -- src/auth/session.test.ts

If the repro is a sequence of manual steps, number them and keep them literal:

1. Start the app with `npm run dev`.
2. Go to /login.
3. Enter a valid email and password, then submit.
4. Observe a 500 error in the network tab instead of a redirect to /dashboard.

Literal steps remove interpretation. "Log in" is ambiguous; "enter a valid email and password, then submit" is not.

Part 3: point at the suspected area

You usually have a hunch about where the bug lives. Share it, but frame it as a starting point, not a conclusion. "Probably in the session signing code, but check the middleware too if that is clean" tells Cowork where to look first without blinding it to the real cause.

This is a balance. Too little direction and the agent reads the whole codebase to orient itself, which is slow and dilutes its focus. Too much and you steer it past the actual bug. The sweet spot is naming a file or two and the behaviour you suspect, while leaving room to follow the evidence.

If you have no idea where the bug is, say that too. "I do not know where this lives; start from the error message and trace backwards" is honest direction, and it is better than a fake guess that sends the agent down the wrong path.

Part 4: define the pass condition

The pass condition is how both you and Cowork agree the job is done. Make it checkable by a command or a clear observation, not by vibes.

Good pass conditions:

• "The test in src/auth/session.test.ts passes."
• "The login flow returns a 200 with a session cookie, confirmed manually."
• "The existing test suite still passes; no test is skipped or deleted to get there."

That last clause is worth adding to almost every bug brief. Agents under pressure to make a test pass can take the cheap route: delete the test, skip it, or weaken the assertion. State up front that the fix has to address the cause, not silence the symptom.Common gotchaThe trap is making "all tests pass" your only pass condition. An agent can satisfy that by editing the test instead of the code, so a green suite tells you nothing about the actual bug.Pair it with a repro-based check the agent cannot rewrite, and forbid touching tests to get there.

Putting it together

Here is the four-part brief as one prompt you can adapt. Fill in the brackets with your specifics.

Notice the last line. Asking Cowork to plan before editing, and to surface the diff at the end, sets up the review step that the rest of this guide is about.

The loop, end to end

The four parts feed a loop. You brief, the agent works, you review the diff, and either you accept it or you feed the gap back in as a tighter brief.

Most failed runs trace back to a missing part of the brief. A fix that solves the wrong problem usually means a vague symptom. A fix that breaks something else usually means a missing pass condition about the rest of the suite. Refine the weak part and re-run; you rarely rewrite the whole thing.

Why should I review the diff Cowork returns?

Cowork can write the fix. Only you can decide it is the right fix. The review is where you stay in control, so do not skip it. The same discipline applies to anything Cowork builds; see reviewing and merging what Cowork builds.

Read the actual changes, not only the agent's summary of them. The summary tells you what Cowork thinks it did; the diff tells you what it did. If you are working alongside the run in a terminal, you can inspect the changes directly with git.

# See exactly what changed, line by line.
git diff
 
# See which files were touched, without the line detail.
git diff --stat

When you read the diff, run through this short checklist:

• Does it fix the cause or hide the symptom? A real fix changes the logic that produced the wrong result. A fake fix swallows an error, loosens a check, or special-cases the one input you mentioned.
• Is the blast radius right? A login bug that touches one file is plausible. The same bug touching nine files across the app deserves a closer look.
• Did any test get weakened? Scan for deleted assertions, skipped tests, or a test changed to expect the buggy behaviour.
• Are there leftovers? Debug logging, commented-out code, or a temporary workaround the agent forgot to remove.
• Does it match your conventions? The fix should read like the surrounding code, not like a transplant from another project.

If the diff passes the checklist, run the pass condition yourself. A green test you ran is worth more than a green test you were told about.

A reviewer prompt

You do not have to review entirely by eye. You can ask Claude to review its own change critically before you look, which surfaces the obvious problems first.

Treat the answer as a second opinion, not a verdict. You still read the diff. But a critical self-review catches the cheap fixes before they reach you, which makes your own pass faster.

How do I isolate a bug fix with a git worktree?

A bug fix that runs in the background should not collide with whatever else you have open. A git worktreeA second working directory linked to the same repository, with its own checked-out branch, so two branches can be worked on at once without stashing gives the fix its own directory and its own branch, so the agent can edit freely while your main checkout stays untouched.

# Create a fresh branch and working directory for the fix.
git worktree add -b fix/login-500 ../fix-login-500
 
# When the fix is merged, list and remove the worktree.
git worktree list
git worktree remove ../fix-login-500

Pointing Cowork at the worktree keeps the change contained. If the fix goes wrong, you delete the branch and the worktree and nothing in your main checkout was ever at risk. For more on structuring agent work this way, see how top developers use Claude Code and keeping parallel agents from clobbering each other with git worktrees.

Common failure modes

These are the patterns that turn a quick fix into a long afternoon. Each maps back to a missing part of the brief.

What if the bug needs context the brief cannot hold?

Some bugs depend on state the agent cannot see from the code alone: the contents of a database row, a recent log line, an external service's response. For those, the brief is not enough on its own, and you connect Cowork to the source of that state through a tool.

The standard way to do that is the Model Context Protocol, which lets an agent read from systems like a database or an issue tracker through a defined interface rather than through guesswork. The guide on MCP fundamentals covers how that connection works. The point for bug fixing: if the cause lives in data the agent cannot reach, no brief will fix it, and you need to give it a tool that can see the data.

Is writing a bug brief worth the time?

Yes: a four-part brief produces a focused fix and a diff you can trust, and it does the work while you do something else. A bug brief takes a few minutes to write, and the first time, that feels slower than just poking at the code yourself.

The discipline compounds. The more precisely you state symptoms and pass conditions, the better your fixes get, and the less time you spend reviewing fixes that solved the wrong problem. Write the brief, read the diff, run the check. That is the whole loop.