# Use Claude Cowork to write tests and docs

Tests and docs are the work most people skip when they are busy. Claude Cowork is good at exactly this, because it runs in the background while you do something else. Point it at code that already works, tell it to cover that behaviour with tests or describe it in docs, and you come back to a result you review rather than write from scratch.

This is a different job from building a new feature. You are not asking Cowork to invent behaviour. You are asking it to read what is already there, lock it in with tests, and explain it in prose. That makes the task safer to delegate and easier to brief, as long as you are specific about your conventions.

## Why are tests and docs a good fit for Cowork?

Cowork runs tasks asynchronously. You assign the work, it executes on its own, and you review the output later. For background on that model, read [what Claude Cowork is](/guides/what-is-claude-cowork). Two properties make tests and docs an unusually good fit.

First, the source of truth already exists. The code runs. The behaviour is observable. Cowork does not have to guess what the system should do, it reads what the system does do and writes that down. That removes the biggest risk in async delegation, which is the agent inventing the wrong thing while you are not watching.

Second, these tasks are bounded. "Add tests for the cart total calculation in `src/cart/total.ts`" has a clear edge. The agent knows when it is done, because the tests pass and cover the listed cases. A bounded task with a verifiable finish line is the safest kind of work to run without supervision.

## What are characterisation tests?

When you add tests to existing code, you are usually writing characterisation tests. The goal is not to check that the code is correct in some ideal sense. It is to capture what the code does today, so a later refactor cannot change that behaviour without a test going red.

Ask for "tests that the function is correct" and Cowork has to decide what correct means, then it may write tests that fail against your real behaviour. Ask it to "capture the current behaviour as tests" and it reads the code, derives the expected outputs from the code itself, and your existing logic becomes the spec.If you do not forbid source edits, an agent that hits a test it cannot make pass will sometimes "fix" the code under test instead, and a green suite then proves nothing because the behaviour you meant to lock in is the thing that just changed. Tell it the implementation is frozen and may not be touched, and in review confirm the diff lands only in the test directory before you trust a passing run.

Be explicit that the implementation is the source of truth and must not change:

```text
Add characterisation tests for src/cart/total.ts.

Goal: lock in the current behaviour so a future refactor cannot change it silently.

Rules:
- Do not modify any file outside the test directory.
- Derive expected outputs by reading the code, not by guessing what is correct.
- Match the existing test style in tests/ (same runner, same assertion helpers, same file naming).
- Cover the empty cart, a single item, multiple items, a discount code, and a quantity of zero.

When done: list the cases you covered and any branch you could not reach.
```

The last line earns its place. Asking for a list of covered cases and unreachable branches turns the run into a coverage report you can read in ten seconds, and it surfaces dead code or missing inputs without you digging through the diff.

## How do I make Claude match my existing test style?

A test suite that does not match the surrounding code is a chore to review and a magnet for inconsistency. Claude reads your existing test files and copies their style, the runner, the assertion helpers, the naming, so you rarely need to spell out a framework by name. But it can only copy what it can see.

Two things make this reliable:

- **Point at a reference test.** Naming one good existing test file ("follow the structure in `tests/cart/total.test.ts`") is worth more than describing the style in words. The agent has a concrete pattern to mirror.
- **State the boundary.** Say which directory tests go in and that nothing else may change. Without that, an agent fixing a test sometimes "helpfully" edits the code under test, which defeats the purpose of a characterisation test.

| Brief says | What you get |
|---|---|
| "Write some tests for the cart." | Tests in an arbitrary style, possibly a new runner, maybe edits to the source |
| "Add tests in `tests/cart/`, mirror `tests/cart/total.test.ts`, change no source files" | Tests that match the suite and review like the rest of the code |

If your project has conventions a fresh reader could not infer, put them where the agent always sees them. A `CLAUDE.md` file at the repo root is read at the start of every run, so test-location rules, the runner command, and "never edit source from a test task" belong there, not re-typed into each brief. The [briefing guide](/guides/briefing-claude-cowork) covers the split between stable project context and per-task detail.

## Docs: write down what the code does

The same principle, code as source of truth, applies to documentation. The most useful docs Cowork can produce describe behaviour that already exists and is currently undocumented or out of date.

Good doc tasks for background runs:

- **A README for a module** that has none. "Read `src/auth/` and write a `src/auth/README.md` that explains what the module exposes and how to use it."
- **Refreshing a stale doc** after the code moved on. "The setup steps in `docs/setup.md` no longer match `package.json` scripts and the env example. Update the doc to match the code, change nothing in code."
- **API reference from signatures.** "Document every exported function in `src/api/` in `docs/api.md`, one section each, with parameters and return values taken from the code."

The failure mode to guard against is the agent inventing capabilities the code does not have. State plainly that the docs must describe only what exists, and that anything it cannot verify in the code should be flagged, not filled in.Point the agent at the implementation, not at old comments or a stale README, since prose drifts long before code does and the agent will faithfully copy a wrong claim it reads there. Tell it to derive every statement from function signatures and bodies, and treat existing docs as the thing being checked, never as a source of truth.

```text
Update docs/setup.md so it matches the current code.

Source of truth: package.json scripts, .env.example, and the README.

Rules:
- Describe only steps that are real in the code today. Do not invent steps.
- If a documented step no longer has matching code, remove it and note the removal.
- If something is unclear from the code, add a TODO line rather than guessing.
- Change no files outside docs/.

When done: list each change and each TODO you added.
```

That TODO instruction is the safety valve. It gives the agent a place to put uncertainty instead of papering over it with a confident, wrong sentence.

## Brief so the output matches your conventions

A test or doc task succeeds or fails on how well the output fits the work already in the repo. Three things move the needle most.

### Name a reference, not a rule

"Match our docs style" is vague. "Follow the structure and tone of `docs/billing.md`" is concrete. A pointed example beats a paragraph of description because the agent can read the example directly. Do this for both tests and docs: name the file that already looks the way you want.

### State the boundary explicitly

The single most valuable line in a tests-or-docs brief is the one that says what must not change. A test task must not edit source. A docs task must not edit code. Without the boundary, an agent acting in good faith will sometimes "fix" things you did not ask it to touch, and a clean review turns into untangling unrelated edits.

### Ask for a summary of what it did

End every brief with a request for a short report, the cases covered, the files changed, the open questions. This costs the agent almost nothing and saves you from reading a large diff blind. It also gives you a fast way to catch when the agent misunderstood the scope.

## How do I keep parallel runs from colliding?

Background tasks are most useful when several run at once: tests for one module while docs for another get written. If two runs edit the same working copy at the same time, their changes collide.

The clean way to isolate work is a Git worktree. A worktree is a separate directory backed by the same repository, on its own branch. Each background task gets its own worktree, so its file edits never touch another task's files.

```bash
# Create a worktree on a new branch for the tests task
git worktree add -b tests/cart ../work-tests-cart

# Create a second worktree for the docs task
git worktree add -b docs/setup ../work-docs-setup

# See what is checked out where
git worktree list

# Clean up when a task's branch is merged
git worktree remove ../work-tests-cart
```

Each task works in its own directory and branch, you review the branches independently, and you merge them in whatever order makes sense. For how this scales to many parallel runs, see [how agents fan out](/guides/how-agents-fan-out) and [keeping parallel agents from clobbering each other with git worktrees](/guides/isolate-parallel-agents-with-git-worktrees).

## How should I review what Cowork produces?

Delegation does not remove your judgment, it moves it from writing to reviewing. Two checks catch most problems, and the same habits carry over to [reviewing and merging what Cowork builds](/guides/review-claude-cowork-results).

For tests, read what the test asserts, not only that it passes. A test that calls the function and asserts nothing meaningful is worse than no test, because it gives false confidence. Confirm the assertions describe behaviour you want locked in. Run the suite yourself.

For docs, spot-check claims against the code. Pick three statements and verify each is true in the source. If the agent flagged a TODO or removed a stale step, that is a signal it was reading carefully. A doc with zero open questions about a messy module is more suspicious than one with a few honest TODOs.

## A reusable setup

If you run these tasks regularly, the conventions are stable and belong in one place. Put the boundaries and references in your project context once, and individual briefs get short:

```markdown
## Project conventions for background tasks

- Tests live in tests/, mirror the structure of src/.
- Follow the style of tests/cart/total.test.ts for new tests.
- A test task never edits files in src/.
- A docs task never edits code; docs live in docs/.
- Every task ends with a short summary: files changed and open questions.
- Flag anything uncertain as a TODO. Never invent behaviour.
```

With that loaded, a task brief shrinks to "add characterisation tests for `src/cart/total.ts`, cover empty, single, and multi-item carts." The stable rules are already in scope, so you only write the part that changes.

The return compounds. The first brief takes ten minutes to get right. After a few runs the conventions are settled, and the tests and docs that always slipped can go to a process that does them in the background while you build the next thing.