When to use background agents

A background agent works on its own while you do something else. It does best on tasks with a clear goal and a way to check the result, such as a test that should pass.

Good tasksCopy Anchor Link

These usually finish in one session with little help:

• Fix a failing test, given the test's name and the error.
• Fix a bug with a clear error message or a stack trace.
• Bump a dependency and fix what breaks.
• Add tests for existing code.
• Small refactors: rename, extract a function, remove dead code.
• Configuration, CI and documentation changes.

Tasks that need more from youCopy Anchor Link

These work, but give more context and expect a review round:

• A new endpoint or feature that follows existing patterns. Name the pattern to follow.
• A bug that spans several files. Say where it shows up and what you have ruled out.
• A flaky test. Say how often it fails and how you run it.

Tasks to split firstCopy Anchor Link

Large changes go better as several small sessions. Ask for a plan first, then one session per step.

First session: "List every place the old auth client is used, and propose the order to migrate them. Don't change code."
Next sessions: "Migrate src/billing to the new auth client, following the plan in docs/migration.md."

Keep a person in the loopCopy Anchor Link

Some steps should never run unseen: deploys, migrations, anything that spends money or touches production. Put those tools behind approvals.