Anthropic's workflows page draws the key distinction between ways of running a multi-step task: who decides what runs next (Source 1). With subagents, skills and agent teams, Claude orchestrates turn by turn and results land in a context window. With a dynamic workflow, a script holds the plan and only the final answer reaches Claude's context.

Reach for the lightest option that fits. Anthropic's agent guidance (Chapter 3) advises starting with the simplest solution and adding complexity only when it measurably helps; the agent-teams page says the same in practice — they add coordination overhead and use significantly more tokens, and for sequential tasks, same-file edits or work with many dependencies a single session or subagents are more effective (Source 2).

For a change that touches several packages — a shared type plus every call site — Anthropic's large-codebase guidance gives two techniques: hand Claude the whole change in one session, so the decisions behind each edit stay consistent, and plan first in plan mode. It adds that Claude writes the plan to a file, and Claude Code re-injects that plan file after each context compaction, so the plan survives where conversation history may not (Source 3).

Notice the order: files in dependency order, a check after each group, and a stop rule. A multi-file change fails when an early assumption is wrong and later edits compound it; frequent checks turn that into a one-step revert instead of a repository-wide cleanup.

Two ingredients carry over from Chapter 9: an oracle (compare behaviour against the original) and small, checkable steps. What changes at scale is that one conversation cannot hold hundreds of files. This is what dynamic workflows are for: Anthropic's own example prompts include migrating every file in a directory "working on each file in its own isolated copy", and auditing every route handler with adversarial verification of each finding before it is reported (Source 1).

• Availability: dynamic workflows are available on all paid plans, with Anthropic API access and on Amazon Bedrock, Google Cloud's Agent Platform and Microsoft Foundry; on Pro you turn them on from the Dynamic workflows row in /config (Source 1).
• Approve before it runs: Claude Code shows the planned phases and lets you view the raw script first; the exact prompt depends on your permission mode.
• Try a slice first: the docs advise running on one directory before the whole repository, because one run can use much more than the same task in conversation. A Large workflow warning appears above 25 agents or about 1.5 million projected tokens, and you can set a size guideline (small under 5 agents, medium under 10, large under 50).
• Hard limits: up to 16 concurrent agents by default, 4,096 items per parallel() or pipeline() call, and 1,000 agents per run.
• Not interactive mid-run: a run pauses only for agent permission prompts or a usage-limit wait; for sign-off between stages, run each stage as its own workflow.

The simplest, most documented form of parallelism is the one from Chapter 10: one git worktree per session, so edits do not collide. Here is that pattern run for real on bookshelf. Two independent changes — a title-search endpoint and a stats endpoint — each lived in its own worktree and branch, and their test suites ran at the same time.

Then the merge, which is where parallel work succeeds or fails:

The stats change added only new files, so it merged cleanly with the search change. A third worktree edited the same insertion point in BookController:

What it shows: two sessions run in half the wall-clock of doing them one after another (27 s for both here, because Maven ran concurrently), and independence is a property of which files each session touches. This is exactly Anthropic's advice for agent teams too: break the work so each teammate owns a different set of files, because two editing the same file leads to overwrites (Source 2). Plan the split before you start the sessions.

The table combines the workflows page's comparison with the subagent and agent-team pages (Source 1, Source 2, Source 4).

• Enable: set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. The page's warning says agent teams are experimental, with known limitations around session resumption, task coordination and shutdown.
• Shape: one session is the team lead; teammates are separate Claude Code sessions with their own context windows, a shared task list and a mailbox. You can message any teammate directly.
• Best first uses: research and review, not parallel code edits — for example three reviewers on one pull request with distinct lenses (security, performance, test coverage), or several investigators testing competing hypotheses and trying to disprove each other. The page notes sequential investigation suffers from anchoring and that adversarial investigators make the surviving theory more likely to be the root cause.
• Costs and limits: significantly more tokens than one session; one team per session; no nested teams; no resumption of in-process teammates; teammate permission prompts surface in the lead; teammates inherit the lead's permission mode, so a lead on --dangerously-skip-permissions makes them all bypass. The costs page says agent teams use roughly seven times more tokens than a standard session when teammates run in plan mode (Source 5).

More autonomy needs a stricter gate. A useful gate answers two questions mechanically: do the tests pass? and is the change the size we expected? The second matters because an agent that "fixes" a failure by rewriting half the code is a risk the tests alone do not reveal. Here is the bookshelf gate:

Reading it: the whole feature branch is 29 files away from main — a legitimate but large change that a reviewer should see in pieces — while the latest unit of work is 10 files. The right budget depends on the task; the point is that the number is visible and enforced. Three ways to wire a gate in, from weakest to strongest:

• Cap the spend and turns of unattended runs: --max-turns and, with -p, --max-budget-usd (the latter appears in this machine's claude --help, Chapter 6).
• Ask for evidence, not assurance: the command and its output (Chapter 8).
• Adversarial verification: workflows can have independent agents try to refute each other's findings before reporting; Anthropic describes this as a way to a more trustworthy result than a single pass (Source 1). It lowers false positives; it does not replace a deterministic check.

Two entry points exist, both built on the same engine: the CLI's non-interactive mode, and the Claude Code GitHub Action, which is itself built on the Agent SDK (Source 6, Source 7).

• Basics: claude -p "…" prints the response and exits; it exits 0 on success and non-zero on failure. Output formats: text (default), json (result, session ID, metadata; includes total_cost_usd as a client-side estimate) and stream-json. --json-schema with json output returns validated structured_output.
• Permissions with nobody watching: in -p a call that needs approval is denied unless something approves it. Use --allowedTools with narrow rules (the docs' example allows only git diff, git log, git status and git commit), --permission-mode dontAsk for locked-down runs, or --permission-prompts none so denied requests do not stall the run.
• Reproducibility: --bare skips auto-discovery of hooks, skills, subagents, plugins, MCP servers, auto memory and CLAUDE.md, so the same prompt behaves the same on every machine; Anthropic calls it the recommended mode for scripted and SDK calls and says it will become the default for -p in a future release. In bare mode authentication uses ANTHROPIC_API_KEY or an apiKeyHelper, not your subscription login.
• Piping: stdin is read (capped at 10MB), so git diff main | claude -p "…" works without giving Claude shell permission to read the diff.

A pull-request workflow that runs the tests first and only then asks Claude to review. It follows the structure of the docs' review example (a prompt input puts the action in automation mode; claude_args passes CLI flags). I wrote this file for bookshelf; it was parsed to confirm it is valid YAML with the intended jobs, but it was not run on GitHub.

(One quirk seen while checking: PyYAML reads the bare key on as the boolean True, a YAML 1.1 behaviour, so the script looked the triggers up under True. GitHub itself treats on as the trigger key.)

• Secrets: store the key as a GitHub secret, never in the repository. The docs warn against committing API keys or OAuth tokens. For a shared organisation secret, use an API key; an OAuth token belongs to whoever ran claude setup-token.
• Who can trigger it: by default the triggering user needs write access, and bot actors are rejected unless listed in allowed_bots, which keeps bots from triggering Claude in a loop.
• Cost controls: --max-turns, workflow timeouts and concurrency limits; runs consume GitHub Actions minutes and API tokens.
• Least privilege: the review job above gets read permissions only; the docs' @claude example grants write because it can push commits. Grant what the job needs.
• Fork pull requests: on public repositories GitHub withholds secrets from fork-triggered runs, so the review runs only for same-repository branches.

In a large codebase the defaults tuned for small projects can fill the context window with unrelated instructions and file reads, costing tokens and degrading performance. Anthropic's large-codebase guide scopes Claude to the part you are touching (Source 3):

Two caveats from the same page matter. Project settings in .claude/settings.json are not inherited from parent directories the way CLAUDE.md files are, so each starting directory needs its own. And Read deny rules cover Claude's built-in file tools and recognised file commands, but a Bash grep -r over a directory containing denied files can still list them, and subprocesses that open files themselves are not covered. For Spring/Maven monorepos the same pattern holds: per-module CLAUDE.md with that module's test command, deny **/target/**.

A project that spans many context windows hits a problem Anthropic's engineering team describes plainly: each new session starts with no memory of the last; with only a high-level prompt a capable model tends to try to build too much at once, leaving half-finished work, and a later session may see some progress and wrongly declare the project done (Source 8). Their remedy is a harness pattern: an initializer step that creates a feature list, a progress log, a startup script and an initial git commit; then coding sessions that each advance one item and leave the repository ready to merge.

The article's other findings map to this guide's lessons: agents marked features complete after unit tests or simple API checks without confirming end-to-end behaviour (so verify like a user would); git lets agents revert to working states; and structured JSON status was chosen because models alter it less casually than Markdown. Anthropic also names open questions — whether one general agent beats specialised testing or QA agents is unclear, and the approach was tested mainly on full-stack web development (Source 8). Here is the pattern at bookshelf scale:

• Only statuses change. Instruct the agent that it may flip status only after the verification command passes, and never edit or delete features.
• Tools for the unattended case: /loop repeats a prompt in a session; claude --bg starts a background session (agent view is a research preview); a run that hits a claude.ai usage limit can pause and resume itself in an interactive session when autoContinueAtUsageLimit is on, but not in -p, background or Remote Control sessions (Source 1). An expired login stops unattended work.
• Checkpoints are session-scoped. Git commits are the durable record.

A process you run on every branch should not be re-typed. Anthropic's docs offer three levels, each more portable than the last:

A repeatable workflow also benefits from being run the same way in CI: the GitHub Action can run a skill from your repository (check out the repo first, pass /skill-name as the prompt) or a plugin skill (Source 7). Packaging is the subject of Chapter 12.