Big refactors with dynamic workflows

A refactor that touches 300 files does not fit in one conversation. The context fills with file reads, Claude loses track of which call sites it already fixed, and one bad edit hides among hundreds of good ones. This guide is for developers who want to run that kind of change as a dynamic workflow: a script Claude writes, a runtime executes in the background, and you can stop, resume and rerun.

By the end you will have a repeatable five-stage process and a prompt pack you can point at your next migration.

What you will have at the end

• A refactor brief (REFACTOR.md) with one measurable done check that both you and Claude can run.
• An inventory workflow that edits no source files and lists every unit of work as structured data before anything is edited.
• A pilot run on a small slice, so you see the token cost before you commit to the whole repo.
• A fan-out workflow that edits each unit in its own isolated copy, then has independent agents try to break each result.
• The workflow saved as a project command (/<name>) your team can rerun on the next package.

Before you start

• Access to dynamic workflows. Every paid plan has them, as do Anthropic API accounts and the major cloud providers. Pro users switch them on first, in the Dynamic workflows row of /config (workflows).
• A recent Claude Code. Run claude --version (changelog). Some pieces below have minimum versions: the /workflow-authoring skill needs v2.1.248 or later, and pausing a run at a usage limit needs v2.1.271 or later (workflows).
• A git repository with a clean working tree. Isolated copies are git worktrees by default (worktrees).
• One command that proves the codebase is healthy, such as npm test or npx tsc --noEmit. If you do not have one, build it first. Everything in this guide hangs off that check.
• The attachment refactor-prompts, which holds the brief template, the six stage prompts and a settings snippet.

Step 1: Write the refactor brief and prove the check works

Create REFACTOR.md at the repository root. The attached template has every field; a filled version for a typical migration looks like this:

# Refactor: move data access from the legacy db helper to the new client

## Goal
Every import of src/lib/db-legacy.ts is replaced by src/lib/db/client.ts.
src/lib/db-legacy.ts is deleted.

## Done check (must exit 0)
npx tsc --noEmit && npm test

## Invariants (must not change)
- Public API of src/routes/** (same paths, same response shapes)
- No test file is edited except to update imports
- No new dependencies

## Unit of work
One file that imports db-legacy, plus its colocated test file.

## Out of scope
- Query rewrites or performance changes
- Files under src/generated/

Then run the done check yourself on the untouched branch:

npx tsc --noEmit && npm test

It must pass now. If the baseline is red, no agent can tell whether it broke something or inherited the failure. Fix the baseline first, or record the known failures in the brief by name.

Why each field matters:

• Goal is a sentence you could check with grep. "Clean up data access" is not a goal; "zero imports of db-legacy" is.
• Done check is one shell line with an exit code. Later the verification stage and the /goal loop both use it, and the /goal docs recommend exactly this shape: one measurable end state, a stated check, and the constraints that must hold on the way.
• Invariants are what reviewers attack in step 5. Each one becomes a question an adversarial agent asks of every diff.
• Unit of work decides how the workflow splits the job. A unit must be small enough for one agent and independent enough that two units never edit the same file. File plus colocated test is the safest default.
• Out of scope stops the slow creep where agents "improve" code they were only meant to move.

Commit the brief on a fresh branch so every later stage can read it:

git switch -c refactor/db-client
git add REFACTOR.md
git commit -m "Add refactor brief"

This brief is useful even if you stop here. Pasting it into a normal session already gives Claude a sharper target than a one-line request. The rest of the guide turns it into a run that scales past what one conversation can hold.