The problem with "just try again"

You ask an AI coding agent to add webhook handling to a TypeScript service. It creates a new pub/sub layer instead of using the existing EventBus in src/core/events.ts. Tests fail because the new layer doesn't integrate with the existing event subscribers. You re-run the agent. It sees its own broken pub/sub code and, instead of questioning the approach, starts patching it. It wraps the broken handler in a try-catch, adds a special case for the failing test, and imports a compatibility shim. By iteration three, the code is worse than if the agent had never touched it.

The underlying problem is context pollution. A naive retry feeds the agent its own failed code, and it tries to fix that code in place. Stale snippets, debug logs from previous attempts, and half-applied fixes pile on more noise. By iteration three, the agent spends most of its context window navigating artifacts from earlier attempts instead of understanding the actual codebase.

PithyCyborg put this well: "A retry that doesn't change the conditions is usually just a more expensive way to fail." Feeding the agent its own failed output as context doesn't change the conditions.

The LLMLOOP study (ICSME 2025) confirmed the flip side: structured feedback loops measurably improve LLM code generation quality on benchmark tasks. Whether iteration is productive or just expensive randomness comes down to how the loop is designed.

Three design decisions that separate convergence from spiraling

A productive retry loop needs three mechanisms that most implementations skip.

Checks as a gate before review

Run lint, test, and build after every implementation attempt. If any check fails, skip review entirely and loop back to the implementer immediately.

Most retry loops send every attempt to a reviewer (human or LLM) regardless. That wastes the reviewer's token budget on surface-level problems. A reviewer analyzing code that doesn't compile will point out missing imports and syntax errors, not whether the approach is correct. The check gate ensures the reviewer only sees code that meets a minimum bar: it compiles, the linter passes, and the existing tests still work.

The check gate also creates a fast inner loop. Failed checks restart the cycle in seconds (the time it takes to run npm test), not minutes (the time it takes for a reviewer agent to read, analyze, and produce structured feedback). For common first-attempt mistakes like missing imports or type errors, this fast loop resolves the issue without ever invoking the reviewer.

Three-strategy review, not pass/fail

After checks pass, a reviewer evaluates the implementation and chooses one of three strategies: pass (exit the loop), continue (approach is sound, needs more work), or refactor (approach is fundamentally wrong).

"Continue" and "refactor" describe two different situations that binary pass/fail conflates.

Take the webhook example from the opening. On the first attempt, the agent creates its own pub/sub layer instead of using EventBus. The reviewer identifies this as a refactor situation: the foundation is wrong. No amount of patching will make a custom pub/sub layer integrate correctly with the existing event subscribers. The right response is to revert and start fresh with the instruction "use EventBus in src/core/events.ts."

On the second attempt, the agent uses EventBus correctly but forgets to clean up the handler registration in UserService.teardown(). The reviewer identifies this as a continue situation: the foundation is sound. The agent used the right abstraction, integrated with existing subscribers, and just missed one detail. The next iteration should build on this work, not throw it away.

Treating these the same way is why retry loops feel like expensive randomness. When a "continue" situation gets the "refactor" treatment, you throw away sound work. When a "refactor" situation gets the "continue" treatment, you spend iterations patching code that should have been reverted on iteration one.

This three-strategy model is a design choice, not a discovered law. You could add a fourth strategy ("abort and escalate to a human") or collapse it into two with a severity parameter. The point is that binary pass/fail isn't enough. The reviewer needs a way to distinguish "keep building" from "start over."

The reviewer’s feedback is all the next iteration has to work with. It needs to describe what went wrong, what approach would work better, which parts of the codebase matter, and what patterns the next implementer should follow.

Refactor means undo, not fix

When the reviewer chooses "refactor," a dedicated agent undoes the work. It does not attempt to fix or improve the code. It reverts.

The next iteration's implementer starts fresh: the original request plus the reviewer's feedback about what went wrong and what to try instead. The workspace is clean, with no artifacts from the failed approach to work around.

Throwing away code feels wasteful. But patching fundamentally wrong code usually makes things worse. The implementer is better off starting clean with good feedback than inheriting a workspace full of wrong-approach artifacts. The reviewer's diagnosis is what carries forward, not the code.

The reviewer isn't an oracle

The entire model depends on the reviewer making correct strategy calls. LLM reviewers get it wrong: they call "continue" on a fundamentally wrong approach, or call "refactor" on code that just needs a small fix. Two mechanisms limit the damage.

First, max_retries (default: 3) acts as a circuit breaker. Even if the reviewer consistently misclassifies, the loop terminates after a bounded number of iterations. When the loop exits at the retry limit, the workspace contains whatever state the last iteration left. The user reviews from there.

Second, yield: true pauses the loop after each iteration for human review. This is the default. The user sees the reviewer's strategy and feedback, and can override: continuing when the reviewer said refactor, or reverting manually when the reviewer said continue. Fully autonomous mode (yield: false) removes this safety net and is only appropriate when you trust the reviewer's judgment on the specific codebase.

What each iteration actually sees

In a naive retry, each iteration inherits everything from previous attempts: code, debug logs, failed approaches, reviewer comments. Context grows linearly with each attempt. JetBrains Research (2025) found that agent-generated context quickly becomes noise, and that effective context size is often much smaller than the window size. Stale implementation details from earlier iterations crowd out the agent's ability to reason about the actual problem.

A structured retry loop inverts this. Only the reviewer's feedback crosses the iteration boundary. Implementation narratives, check logs, and refactoring details stay in isolated thread forks that are discarded after each iteration.

Concretely, after three iterations the main thread contains:

Three messages. Not three full implementation transcripts with diffs, debug logs, and reviewer analyses.

The third implementer receives three feedback messages instead of 50,000 tokens of accumulated implementation history. Martin Fowler's overview of context engineering for coding agents arrives at the same conclusion: the challenge is curating what the model sees, not fitting more in.

The workflow implementation

Get It Right, an open-source Reliant workflow, implements these three decisions in a single workflow.yaml.

The workflow runs an attempt loop: implement → [lint, test, build] → review → [refactor?] → loop back. A CEL expression controls the loop condition:

The loop continues when the reviewer says "continue" or "refactor," or when any check fails. It exits on "pass" or when max_retries is reached. When the loop hits the retry limit without a "pass," the workflow exits with the current workspace state. The user takes over from there.

Lint, test, and build run in parallel after each implementation. A join_checks node waits for all three, then an edge condition decides whether to proceed to review:

If any check has a non-zero exit code, the edge goes to [] (no next node), ending the iteration. The reviewer never runs on broken code.

The reviewer produces a structured JSON response ({grade, strategy, feedback}), and its save_message directive writes only the strategy and feedback to the main thread. The reviewer's full analysis, the code diffs it examined, and the commands it ran stay in the reviewer's forked thread and are discarded.

The edge from review to refactor fires only on the "refactor" strategy:

Every agent fork uses memo: false, starting a fresh thread each iteration. Only the reviewer's save_message writes back to the main thread. The result: workspace state and reviewer feedback are the only data that persists across iterations.

When structured retry loops pay off

Retry loops with structured review cost roughly 2-4x a single agent pass in tokens and time: multiple implementation attempts, reviewer analysis, and conditional refactoring. That overhead is justified in specific situations.

Complex brownfield codebases with implicit conventions are the clearest fit — the kind where human PR reviews consistently say "we don't do it that way here." When the agent keeps generating code that "should" work but violates undocumented patterns, a retry loop with a reviewer that discovers and communicates those patterns is worth the token cost. Cross-cutting changes that touch multiple interconnected systems are another good case: higher odds of a fundamentally wrong approach, and the conditional undo prevents iteration debt from accumulating.

Greenfield projects and simple one-file bug fixes don't need this. No existing conventions to discover, no architecture to fight against. Run the agent once. If it fails, re-prompt. For well-documented codebases where the architecture is obvious from the code, the value of the three-strategy distinction drops because the agent is less likely to choose a fundamentally wrong approach in the first place.

There's a gray area for medium-complexity tasks where we're less sure. A multi-file refactor in a codebase you understand well might benefit from the check gate alone (run tests before re-prompting) without the full three-strategy review. The overhead depends on how often the agent picks wrong approaches, and that varies by codebase, task, and model.

These principles apply regardless of tooling. Running Claude Code manually? Run tests before re-prompting. When you review the output, distinguish "keep going" from "start over." When starting over, git checkout . before re-running the agent. These concepts work whether you use Get It Right, build your own loop, or do it by hand.

Get It Right as a workflow

Get It Right is an open-source Reliant workflow that implements this retry pattern as an automated pipeline. The workflow.yaml shown throughout this post is the complete implementation:

The workflow accepts configurable check commands, a max retry count (default 3), and an execution mode. Set yield: true to pause after each iteration for manual review, or yield: false to run the full loop autonomously.

The trade-off is real: Reliant replaces your current tool. If you're using Claude Code or Cursor, adopting Get It Right means switching to a different development environment. That's a legitimate switching cost, and it only makes sense if you're working on codebases complex enough to justify structured iteration.

For readers who won't switch, the three design decisions transfer to any setup. The check gate, three-strategy review, and conditional undo are patterns, not product features. Build them into your own scripts, apply them manually, or use them as a framework for evaluating other tools.

Get It Right is one workflow in a broader library. One Ring adds planning, parallel verification, and multi-reviewer code review around the same retry loop. The workflow.yaml and documentation are on GitHub. The Reliant platform documentation covers the workflow primitives (loop nodes, edge conditions, thread forking, structured output) used throughout this post.

This is the first post in a series examining the philosophies behind popular AI coding workflows — what they get right, where they break down, and what happens when workflows become a programmable primitive

Ask an AI coding agent to remove dead code and you usually get something that looks right. It deletes the obvious unused function, removes one import, updates a call site or two, then says the cleanup is complete. Then you open the diff and find three more helpers with no callers, a test fixture that still points to the old path, and one branch that still imports the deleted module.

Once you start noticing it, that failure mode is all over the place. A refactor updates the main implementation and still misses the shadow copy in a helper package. A test rename changes the test file names, but CI config still points at the old targets. The agent says it edited four files. One of those edits never landed in the branch.

This is why "done" from an agent often means review is just starting. The frustrating part is that the agent usually did real work. The branch is better than before, but the task still is not done.

It helps to give this a name: the repetition pattern. The human sees partial completion, asks again with a narrower prompt, gets another slice of progress, checks the repo again, and keeps going until the leftovers stop showing up. The Ghost Task Problem describes a similar symptom from another angle: claimed completion drifting away from branch state. This is not a weird edge case. It is a routine operating condition for AI coding work on brownfield codebases.

The natural reaction is to blame the prompt. Write clearer instructions. Add more context. Specify the directories to check. That helps on the margins, but it misses the structural issue: no prompt can give an agent the ability to verify its own fuzzy work. The agent's strongest skill — generating plausible, working code — is exactly what makes this failure mode so dangerous. It is not that agents are bad at coding. It is that they are too good at looking done. The problem is not linguistic. It is architectural.

The real distinction is objective completion vs fuzzy completion

The most useful question is whether the task has a clear stop condition, not whether the model seems smart in the abstract. Once you sort tasks that way, a lot of confusing agent behavior starts to make more sense.

Objective completion means there is outside evidence the work is done: the test suite passes, the build succeeds, the linter is clean, or the generated file matches the schema. You can argue about the implementation, but you do not have to guess whether the requested state was reached.

Fuzzy completion means the stop condition depends on judgment, coverage, or discovery. "Remove all dead code" sounds clear until you realize the repo has helper directories, test fixtures, generated stubs, half-migrated modules, and old scripts that only show up in deploy paths. "Finish this refactor" sounds clear until the remaining work is scattered across naming conventions, comments, docs, config, and edge-case call sites. The agent can make visible progress and still not have real evidence that it found everything.

This is why the same model can look solid on one task and shaky on another. Ask it to add a failing test, fix the implementation, and stop when the test passes, and the model gets a strong external signal. Ask it to find every stale pattern tied to a seven-month migration, and the model has to search and certify its own search. That is a harder problem than raw code generation.

The distinction matters because it tells you what kind of control loop you need. Objective tasks can often converge with repetition plus verification. Fuzzy tasks usually need narrower scopes, explicit checklists, or a human review step that accepts you may not get a perfect stop signal.

Why single-pass work breaks down

Single-pass workflows break down when the agent has to solve the problem and certify the result in one shot. It sounds efficient in chat. In practice, it lumps together three different jobs: finding the work, doing the work, and checking whether anything subtle remains.

The first problem is self-assessment. Models are good at recognizing local progress, but they are less reliable at proving global completeness when the search space is broad. If the agent removed ten stale references, that visible progress becomes a source of false confidence. The branch looks cleaner, the diff is non-trivial, and the model leans toward declaring success.

The second problem is attention. Large repos do not present all evidence with equal weight. The loud files are the ones that fail tests, import the old symbol directly, or sit near the files already in context. Quiet leftovers live in helper scripts, fixture data, deployment paths, copied utility modules, and low-traffic tests. A single pass hits the loud evidence first.

The third problem is context pressure. Long sessions pile up plans, diffs, failed ideas, and partial scans. Once the conversation gets heavy, the model starts reasoning through a compressed version of the work instead of the full raw state. Reliability degrades because the session now contains a summary of the repo problem, not the repo problem itself.

Put those three together and you get a common sequence. The agent does something meaningful. The remaining work gets less salient after the first cleanup. The model reads its own progress as stronger evidence than it deserves, then emits a confident completion statement.

Repetition as workaround, and where it stops working

Once engineers notice the pattern, they reach for the same fix. They ask the agent again with a tighter question. Check the diff. Search for the old symbol. Paste the remaining matches back into chat. Ask for another pass focused on leftovers.

This works more often than a single pass suggests it should. The repo changed after the first pass, so the remaining evidence stands out more clearly. A second prompt aimed at one blind spot can direct the model toward files it ignored.

The problem is scale. A strong engineer can run that loop on one important task. A team cannot afford to do it by hand for every migration, cleanup, refactor, and bug fix. And the cost is not just the review time — it is what organizations choose not to attempt. Teams unconsciously limit AI to the tasks where single-pass works: write a test, fix this bug, add this endpoint. The hardest and most valuable work — large migrations, cross-cutting refactors, deep cleanup of technical debt — stays manual or does not happen, because the review cost of running an agent on fuzzy tasks is too high to justify.

That hidden cost is the real impact of the repetition pattern. It is not that agents waste twenty minutes of review time. It is that the pattern silently caps the return on AI-assisted development at the easy tasks.

Repetition also has a hard ceiling. It does not fix a bad plan, a wrong abstraction, or a design mistake the model keeps preserving. If the agent misunderstood the architecture, extra passes produce a more complete version of the wrong solution. A practical diagnostic: after two or three passes, is the system finding new territory or working over the same ground? New territory looks like previously missed files, newly surfaced search hits, or a shrinking set of concrete leftovers. Same ground looks like reworded explanations, churn in the same files, or cosmetic edits around an unresolved core issue.

What the structured version looks like

Once repetition becomes routine, the question is how to make the loop and the stop condition explicit instead of relying on memory and patience.

Two strategies keep appearing. One resets context between passes — each run reads the repo fresh, takes a bounded step, and checks exit conditions. This works well when the task can be verified objectively. The other preserves accumulated state — each pass builds on the previous one's findings. That approach matters more for fuzzy, diagnosis-heavy work, but the challenge is keeping the session coherent as state piles up.

Reliant's Ralph Wiggum workflow is a context-reset loop that makes all of this explicit. Each iteration runs three steps: orient (read the repo, pick the next task), implement (execute that one task, test, commit), and verify (structured check against acceptance criteria). The loop continues while tasks remain, up to a configurable cap.

The key design decisions are visible in the workflow definition:

Three things matter here for the repetition pattern. First, the while condition is an explicit exit rule — tasks_remaining == true && iter.iteration < max_iterations — not the agent deciding it feels done. Second, the verify step forces a structured boolean through a response schema instead of letting the agent write prose about completion. The agent must commit to tasks_remaining: true or tasks_remaining: false. Third, each step forks its own thread (thread.mode: fork, memo: false), so the orient step re-reads the repo fresh each iteration rather than reasoning from accumulated context. Iteration summaries are saved to the main thread, but the working context resets.

Ralph Wiggum workflow overview (YouTube)

This is not a magic fix. It is the same loop practitioners already discovered — orient, implement, verify, repeat — but with the stop condition, the context strategy, and the verification schema encoded as workflow primitives instead of living in the engineer's head. For recurring work where review cost is already high, the explicit version is easier to trust and cheaper to run than the manual version.

A practical decision framework

Before handing work to an agent, classify the task by completion type and choose the evidence that will stop the loop.

Three questions:

1. Is completion objective or fuzzy?
2. What observable evidence would prove the task is done?
3. If the evidence stays fuzzy, what is the stop rule?

That last question matters because every loop needs a bound. The bound might be three passes, a fixed checklist, a search with zero remaining matches in named directories, or a required human review before merge.

The framework is simple, but it prevents a lot of avoidable frustration. Many bad experiences with agents come from handing them fuzzy tasks while expecting objective-task reliability, or from treating a weak proxy like a hard stop signal. Once you separate those cases, the behavior gets easier to predict.

Where Workflows Go Next

Once you treat premature "done" as a structural failure mode — not a prompting problem — the next question is how to prevent it systematically. Two camps have emerged. One bets on tighter process: enforced TDD, role separation, structured reviews. The other bets on context management: fresh state, file-based memory, decomposition into bounded chunks.

The next post examines the discipline camp — Superpowers and BMAD — and what happens when you treat enforced process as the primary defense against agent failure.

Opus 4.6 is the most capable model Anthropic has released. It’s also the most expensive to run on simple tasks, and not because of the input pricing.

The cost is in thinking tokens. Opus 4.6 defaults to high effort, which means it thinks deeply on almost every request. Ask it to rename a variable, generate a boilerplate Express route, or format a JSON response. It reasons through all of them. Anthropic’s own announcement says as much: the model “thinks more deeply and more carefully revisits its reasoning before settling on an answer,” which “can add cost and latency on simpler ones.”

Output tokens on Opus 4.6 run $25 per million. Input tokens cost $5 per million. Thinking tokens bill as output tokens. So every time Opus 4.6 spins up its reasoning engine on a task that didn’t need it, you’re paying 5x the input rate for tokens you’ll never see in the response. The actual thinking content gets summarized before it reaches you, but you’re billed for the full chain of thought.

This creates a specific problem for anyone running Opus 4.6 in production or using it through the API for coding workflows. The model is better at hard problems like complex debugging, architectural reasoning, and root cause analysis across large codebases, which is where Opus 4.6 earns its pricing. But most engineering work is implementing a known pattern, writing a standard test, generating scaffolding, formatting output. Running Opus 4.6 at full reasoning depth on those tasks eats tokens that could be otherwise used for hard work.

Anthropic knows this. The Opus 4.6 announcement recommends setting effort to medium for “many routine tasks” and only using high or max effort when you need the deepest reasoning. They give you the tools to avoid spending more time and money than you have to. So how do you take advantage?

That’s what effort controls are: a way to tell Claude how hard to think. Four levels, from low to max, each one changing how many tokens Claude spends on internal reasoning, how many tool calls it makes, and how long it takes to respond. Paired with adaptive thinking, effort controls give you a dial that trades reasoning depth against cost and latency. Turn it down when you need speed. Turn it up when you’re doing something complex.

The rest of this post covers how effort controls work at the API level, when to use each level on real engineering tasks, and how effort interacts with model selection in multi-agent workflows. If you’re running Opus 4.6 and your API bill is higher than expected, start here.

How Effort Controls Work

Effort controls are a single parameter in the API that changes how Claude allocates compute to a request. You set it in output_config:

{

"model": "claude-opus-4-6-20250613",

"max_tokens": 16000,

"output_config": {

"effort": "medium"

},

"messages": [...]

}

Four levels are available: low, medium, high, and max. High is the default. If you omit the parameter entirely, you get high. By the way, Max is exclusive to Opus 4.6.

Effort is a behavioral signal, not a strict token budget. Setting effort to low doesn’t cap thinking tokens at a fixed number. It tells Claude to approach the task with less deliberation. The model decides what that means in context. On a simple formatting task, low effort might skip thinking entirely. On something moderately complex, it might think briefly instead of deeply. You’re setting intent, not a hard limit.

What each level does

Low. Claude skips thinking on straightforward requests, makes fewer tool calls, and produces shorter responses. Use this when you already know what you want and Claude’s job is execution, not reasoning. Boilerplate generation, formatting, classification, simple transformations.

Medium. Claude thinks when the task warrants it but doesn’t go deep by default. Fewer tool calls than high, shorter reasoning chains. This is the level Anthropic recommends for “many routine tasks” on Opus 4.6. At medium effort, Opus 4.5 matched Sonnet 4.5’s best SWE-bench score while using 76% fewer output tokens. That’s the efficiency sweet spot for most coding work.

High (default). Claude thinks on most requests and reasons more carefully before responding. This is what you get if you don’t set the parameter at all. Good for complex tasks, but expensive on routine ones because thinking tokens bill at the output rate ($25/MTok on Opus 4.6).

Max (Opus 4.6 only). No constraints on thinking depth. Claude will use as much reasoning as it determines it needs, which can mean long chains of thought that approach the max_tokens budget. Reserve this for problems where you want Claude to exhaustively reason through every angle: security audits, root cause analysis, architectural decisions with competing tradeoffs.

How effort interacts with thinking

Effort controls work best when paired with adaptive thinking:

{
  "model": "claude-opus-4-6-20250613",
  "max_tokens": 16000,
  "thinking": {
    "type": "adaptive"
  },
  "output_config": {
    "effort": "medium"
  },
  "messages": [...]
}

Adaptive thinking is the recommended configuration for Opus 4.6. It replaces the older budget_tokens approach, which is deprecated on this model. Where budget_tokens gave you a fixed token ceiling for thinking, adaptive thinking lets the model decide how much to think based on the effort level and task complexity. The two work together: effort sets the intent, adaptive thinking handles the allocation.

One behavior that adaptive thinking enables automatically is interleaved thinking. Claude can think between tool calls, not just at the start of a response. In agentic workflows where Claude calls tools in sequence, this changes the execution pattern. Without interleaved thinking, Claude does all its reasoning upfront and then executes. With it, Claude can reason about each tool result before deciding what to do next. At lower effort levels, it skips this intermediate reasoning when the tool results are straightforward. At higher levels, it reasons after every step.

What effort affects

Effort doesn’t just control thinking tokens. It changes three things:

1. Thinking depth. How many tokens Claude spends on internal reasoning before producing a response

2. Tool call frequency. How many tools Claude invokes per request. Lower effort means fewer calls, which reduces both latency and cost.

3. Response length. Lower effort produces shorter, more direct text responses. Higher effort produces more detailed, considered responses.

A high-effort request with multiple tool calls and deep thinking can generate 5-10x the output tokens of the same request at low effort. That multiplier hits your bill at $25 per million output tokens on Opus 4.6.

One more thing: effort is promptable

You can also steer thinking frequency through your system prompt. If you tell Claude “think carefully about edge cases” in the system prompt, it will think more often even at medium effort. If you tell it “respond concisely without deliberation,” it will think less even at high effort. The effort parameter sets the baseline; the prompt can push it in either direction. This gives you two levers: the parameter for broad control, the prompt for task-specific tuning.

When to Use Each Level

Here’s what we know so far. Anthropic’s benchmark data shows that at medium effort, Opus 4.5 matched Sonnet 4.5’s best SWE-bench score while using 76% fewer output tokens. At the highest effort, it exceeded Sonnet 4.5 by 4.3 points while still using 48% fewer tokens.

Here’s what we know so far. Anthropic’s benchmark data shows that at medium effort, Opus 4.5 matched Sonnet 4.5’s best SWE-bench score while using 76% fewer output tokens. At the highest effort, it exceeded Sonnet 4.5 by 4.3 points while still using 48% fewer tokens.

Early access partners reported similar results in production. GitHub’s Mario Rodriguez saw it “surpass internal coding benchmarks while cutting token usage in half”. JetBrains reported 50-75% reductions in tool calling errors and build/lint errors with their Junie agent. AJ Orbach at Text2SQL.ai called the effort parameter “brilliant,” noting that at lower effort the model “delivers the same quality we need while being dramatically more efficient” for SQL generation workflows.

That data is compelling but narrow. SWE-bench scores and SQL generation are specific use cases. What’s missing is systematic testing across the range of tasks engineers run every day: writing tests, debugging across multiple files, reviewing PRs, scaffolding new services, refactoring legacy code. Nobody’s published “I ran the same debugging task at low, medium, high, and max and measured quality, cost, and latency for each.” We’re running those experiments now and will publish the results in a follow-up post. If you’re testing effort levels in your workflows, we’d like to compare notes.

Until that data exists, here’s what we’re working with. It draws on Anthropic’s docs, the benchmark results, the partner reports, and our own experimentation.

Low effort: execution tasks

Use low when Claude’s job is to produce something you already know the shape of. You’re asking it to write a known pattern, not reason through a problem.

Tasks that fit: boilerplate generation, file scaffolding, import formatting, conventional commit messages, simple type annotations, lint-fix suggestions, renaming variables across a file, generating standard route handlers.

The common thread is that these tasks have a clear correct output. There’s no ambiguity about what “good” looks like. Claude doesn’t need to weigh tradeoffs or consider edge cases. Low effort skips thinking on these, produces shorter responses, and makes fewer tool calls. Thomas Wiegold frames it well: “Need a quick function signature? Low effort.”

Medium effort: standard implementation

Medium is the workhorse level. This is where most daily coding happens: implementing a CRUD endpoint, writing unit tests for an existing function, refactoring with a known pattern, reviewing straightforward PRs, writing documentation for existing code, adding error handling to a module.

These tasks need some reasoning but not deep analysis. Claude should think about how your conventions apply, check that the implementation is correct, and produce clean output. It shouldn’t spend tokens tracing edge cases or reconsidering architectural decisions. Medium gives you that balance.

Anthropic recommends medium for “many routine tasks” on Opus 4.6, and the SWE-bench data supports it. For most implementation work, medium delivers the same quality as high at a fraction of the token cost. If you’re only going to change one thing about how you use Opus 4.6, set effort to medium for your standard coding workflows.

High effort: complex reasoning

High is the default, and for good reason on hard problems. Debugging a race condition, refactoring a module that touches six files, writing tests for edge cases in auth flows, understanding how an unfamiliar dependency behaves under load, reviewing a PR that changes core business logic.

These tasks require Claude to hold multiple concerns in working memory, trace execution paths, consider failure modes, and reason about interactions between components. The extra thinking tokens are worth it because catching an issue here prevents hours of debugging later. High effort is where Opus 4.6 earns its pricing.

If you’re leaving high as your default for everything, you’re either rich or NGMI. If 60% of your API calls are medium-complexity tasks running at high effort, you’re overpaying on the majority of your workload.

Max effort: exhaustive analysis

Max is for problems where you want Claude to leave nothing on the table. Root cause analysis across a large codebase, security audits of authentication flows, designing system architecture from competing requirements, debugging production incidents with incomplete logs.

These are the tasks where a shallow answer is worse than no answer. You want Claude to consider every angle, second-guess its initial conclusions, and reason through implications. Max effort can produce long chains of thought that approach the max_tokens budget. The cost per request is high, but you’re using it on problems where the alternative is hours of senior engineer time.

Max is exclusive to Opus 4.6. If you’re not on Opus 4.6, high is your ceiling.

Cost math: why distribution is everything

One practitioner framework from Digital Applied suggests a 60/30/10 split: 60% of requests at medium, 30% at high, 10% at low. They report taking a client from $840/month to $320/month by shifting requests from blanket-high to this distribution.

That’s one data point, not a proven formula, but the principle is sound. Most API spend on Opus 4.6 comes from thinking tokens on requests that didn’t need deep reasoning. Shifting your default from high to medium and reserving high/max for tasks that warrant it is the highest-leverage change you can make.

The Multi-Model Angle

Effort controls give you one axis of optimization: how hard a single model thinks. The second axis is which model you use in the first place.

Anthropic’s current lineup spans a wide cost range:

Haiku 4.5: $1/$5 per MTok (input/output)

Sonnet 4.5: $3/$15 per MTok

Opus 4.6: $5/$25 per MTok

Haiku 4.5 delivers roughly 90% of Sonnet 4.5’s agentic coding performance at one-third the cost, based on Augment’s evaluation. That means a formatting task running on Opus 4.6 at high effort versus Haiku 4.5 at low effort isn’t a small difference. It’s an order of magnitude.

Practitioners figured this out before Anthropic shipped the tooling for it. Simon Willison ran a major refactor of sqlite-utils with Opus, covering 20 commits, 39 files, and 3,000+ lines changed. Partway through, he switched to Sonnet and “kept on working at the same pace”. The gap between the models showed on ambiguous architectural decisions, not on well-scoped implementation. Ayaan Haider tested all three models across Flutter projects and landed on a simple split: “Haiku for setup, Sonnet for builds, Opus for reviews. That combo just works”. He found Opus caught async bugs and rebuild issues the other models missed entirely, but for routine builds it was overkill.

The pattern keeps showing up. An open-source tool called claude-router routes requests to Haiku, Sonnet, or Opus based on complexity and reports ~40% cost savings. The Clawdbot optimization guide describes workflows where a main agent spawns sub-agents on cheaper models for background tasks, reporting 60%+ cost reductions. Anthropic themselves built this pattern into Claude Code: opusplan mode uses Opus for planning and auto-switches to Sonnet for execution.

Use the expensive model for the hard thinking and cheaper models for everything else. The community has been doing this by hand: switching models mid-session, building routing layers, running different models in different terminals.

But here’s where the two axes meet. Model selection tells you which brain to use. Effort controls tell you how hard that brain should think. Combined, you get a matrix:

Nobody’s running every row at Opus/high, but in practice most developers are still using one model at one effort level per session. Claude Code lets you pick a model and set an effort level, but it applies to the whole session. You can’t say “use Opus at max for this planning step, then switch to Sonnet at medium for implementation, then Haiku at low for cleanup.” Not without manually switching between commands.

The primitives exist, but the per-task orchestration doesn’t. Not yet.

Where This Goes: Effort as a Workflow Primitive

If you’re running single-agent sessions in Claude Code, effort controls save you money today. Set your default to medium, bump to high when you’re debugging something hard, and you’ll see the difference on your next invoice. That saves money with zero tooling changes.

If you’re looking to save even more using multi-agent workflows, we recommend per-agent configuration, tuning the model and effort level for each step in a workflow independently. A planning step needs Opus at max effort, an implementation step needs Sonnet at medium, and a formatting step needs Haiku at low. Running every step at Opus/high means paying $25/MTok output on a formatting pass that Haiku could handle at $5/MTok with low effort. Per-agent tuning lets you put your budget where it earns a return and cut it everywhere else.

Claude Code doesn’t support this yet. You pick one model and one effort level, and it applies to the whole session. If you want to change the configuration between steps, you switch manually. That works for two or three steps but breaks down when you’re running a six-step bug reproduction workflow or kicking off three workflows in parallel.

This is what we’re building at Reliant. In Reliant’s workflow builder, each agent in a workflow gets its own model and effort level:

Planning Agent → Opus 4.6, max effort

Implementation Agent → Sonnet 4.5, medium effort

Test Agent → Sonnet 4.5, high effort

Review Agent → Opus 4.6, high effort

Formatting Agent → Haiku 4.5, low effort

The workflow runs sequentially. Planning completes, implementation starts, tests run, review checks the output, formatting cleans it up. Each agent uses the configuration tuned to its role. You set it up once in the visual builder and run it on every bug, every feature, every refactor.

The matrix from the previous section is the mental model, and Reliant is where you implement it.

Anthropic shipped agent teams alongside Opus 4.6 today. If you missed it in the announcement, here's the short version:

You can now spin up multiple Claude Code instances that coordinate through a shared task list and work in parallel.

On the same day, Anthropic's Nicholas Carlini published a post about using 16 parallel Claude agents to build a C compiler from scratch: 2,000 sessions, $20,000 in API costs, 100,000 lines of Rust. That post is the best stress test of this primitive that exists right now, and I'll reference it throughout.

Agent teams are still experimental, the docs are thin, and the gap between "multiple Claudes working together" and "multiple Claudes working together productively" is wide.

Here's what we’ve found so far.

What are agent teams?

Agent teams sit on top of Claude Code's existing primitives (subagents, custom agents, CLAUDE.md files) but they work differently from all of them.

One Claude Code session becomes the team lead. It creates a shared task list, spawns teammates, and coordinates results. Each teammate runs in its own context window and works independently. When teammates finish, they report findings back through an inbox system, and the lead synthesizes everything.

To enable the feature, set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in your environment or settings.json.

After that, you describe the team structure in natural language and Claude handles the spawning.

Here's the example from the docs:

I'm designing a CLI tool that helps developers track TODO comments across their codebase. Create an agent team to explore this from different angles: one teammate on UX, one on technical architecture, one playing devil's advocate.

Claude creates the team, spawns three teammates, gives each a perspective, and synthesizes their findings when they're done. You can interact with individual teammates directly using Shift+Up/Down to cycle between them, or run in tmux for split-pane visibility. That "explore from different angles" framing is deliberate.

The docs recommend starting with tasks that have clear boundaries and don't require writing code: reviewing a PR, researching a library, investigating a bug. These are read-heavy, parallel-friendly tasks where agents can work without stepping on each other.

How this differs from what Claude Code already had

Claude Code already supports parallel work through a few different mechanisms, and agent teams add a coordination layer on top.

Subagents run inside a single Claude Code session. They inherit the parent's context, do a task (research a question, verify a fact, run a specific check), and report back to the main agent. They can't talk to each other, and you can't interact with them directly. They work well for delegation within a single conversation, but not for parallel exploration across independent contexts.

Custom agents are specialized roles you define in .md files: a code reviewer, a security auditor, a documentation writer. Claude invokes them based on task fit. Each gets its own system prompt, tool access, and optionally a specific model (Opus, Sonnet, Haiku). They're powerful for specialization, but they still run one at a time within a single session.

Manual worktrees are the DIY version. You open multiple terminal tabs, check out separate Git worktrees, and run independent Claude Code sessions in each one. You get full context isolation and parallel execution, but you're the coordinator. This is what a lot of power users already do for parallel work, and it works well if you don't mind managing the merges yourself.

Agent teams add automated coordination on top of parallel sessions. The team lead manages a shared task list, teammates communicate through inboxes, and you can monitor everyone from one place. The tradeoff: you give up some control in exchange for not having to manually orchestrate across tabs.

Subagents and custom agents are single-session primitives. Manual worktrees and agent teams are multi-session primitives. Context isolation (each session having its own window) makes true parallel work possible, but also makes coordination hard.

The C compiler version is a different harness

One thing that confused us initially: the agent teams feature shipping in Claude Code today and the setup Carlini used for the C compiler project are related but not identical.

Carlini's harness is more bare-bones. He spins up Docker containers, each with its own clone of a shared bare git repo. Each agent runs in an infinite loop: finish a task, push changes, pull from upstream, pick the next task. Coordination happens through git's own conflict resolution and a lock file system where agents claim tasks by writing to current_tasks/. There's no orchestration agent or inbox system. Each Claude just decides what to work on next.

The Claude Code agent teams feature adds more structure: a team lead role, explicit task assignment, inter-agent messaging, and the ability to interact with individual teammates without stopping the team. But both approaches share the same core idea: multiple Claude instances, each with independent context, working on a shared codebase.

Carlini's version ran 16 agents for two weeks and produced a compiler that can build Linux 6.9. Claude Code features a research preview with known limitations around session resumption, task coordination, and shutdown behavior. The primitive works, but the shipping feature is still a research preview.

If you've been following Steve Yegge's Gas Town framework, agent teams cover similar ground with a simpler coordination model: one lead, N workers, inbox messaging.

Gas Town uses a more elaborate role hierarchy (mayor, polecats, witnesses) and has been in use longer.

Both are trying to solve the same problem: how do you coordinate multiple Claude instances working on a shared codebase?

Agent teams bake a minimal version of this into Claude Code itself rather than requiring an external harness.

When do agent teams work?

Based on 24 hours of use, we found Agent Teams have a narrow sweetspot: tasks where multiple agents can explore a problem in parallel, mostly by reading, without needing to write to the same files.

Read-heavy parallel exploration

The strongest use case is when you have a question with multiple angles, and each angle can be explored independently. We call it multi-perspective investigation.

Code review from multiple perspectives. You're reviewing a large PR and want a security audit, a performance review, and an architectural assessment happening simultaneously. Each agent reads the diff, checks different things, and reports findings to the lead. The agents never conflict because they're all reading, but not writing code.

Bug investigation. You have a production error and don't know where to start. One agent traces the stack trace through the codebase, another checks recent commits that touched the relevant modules, a third reads the test suite for coverage gaps. Each agent narrows the search space, and the lead synthesizes a hypothesis from their findings.

Library evaluation. You're choosing between three ORMs for a new service. Each agent evaluates one: reads the docs, checks GitHub issues, looks at the API surface, assesses compatibility with your stack. Instead of serial research, you get three parallel evaluations that the lead can compare.

The team lead synthesizes perspectives you'd otherwise read and compare yourself.

How to structure tasks so agents don't collide

The moment agents start writing code, you need to think about file boundaries.

Anthropic's docs are direct about this: two teammates editing the same file leads to overwrites. The lead assigns work rather than merging results, so you need to break work into units where each agent owns distinct files.

Module-per-agent. If you're building a CLI tool, one agent writes the argument parser, another writes the core logic, a third writes the output formatter. Each agent owns a directory or file and doesn't touch the others. This is roughly how Carlini structured the C compiler. Agents worked on separate compiler passes (lexer, parser, code generator) and pushed changes independently.

Test-per-agent. You have ten modules that need test coverage. Each agent gets assigned a module and writes tests for it. The files are naturally separated because each module has its own test file. This is close to "embarrassingly parallel" because agents are interchangeable and can self-assign from a queue.

Spike-per-agent. You're prototyping three different approaches to the same problem. Each agent works in its own branch or directory, building a proof of concept. You compare the results and pick one. The agents never touch shared code because each approach is isolated by design.

The common thread: you need to decompose the work before spawning the team, and the decomposition needs to produce units with clear file boundaries. If you can't draw those boundaries cleanly, agent teams will fight over files, and right now there's no merge resolution built into the coordination layer.

So what did $20,000 and 16 agents actually produce?

Carlini's C compiler experiment is the most ambitious test of parallel Claude agents that exists, and it shows the real ceiling of this approach with current models.

What worked? 16 agents, each running in a Docker container with its own git clone, built a Rust-based C compiler from scratch over about two weeks. The result compiles real-world C code, including the Linux 6.9 kernel for x86, ARM, and RISC-V. Without being told to, agents self-organized into roles: deduplication, performance, code quality, documentation.

How much did it cost? 2,000 Claude Code sessions, roughly 2 billion input tokens, and $20,000 in API spend. The compiler is 100,000 lines of Rust.

Is it actually good? Carlini is honest about this: the generated code is less efficient than GCC with optimizations disabled. The compiler proves the approach works, but nobody's shipping code with it. The internet claims the compiler is brittle - thus we need more time to tell whether it’s good or not.

What challenges did he face working with multiple agents?

Agent Collisions: When multiple agents hit the same failing test during the Linux kernel compilation, they all tried to fix it simultaneously and overwrote each other's changes. Carlini had to build a custom oracle-based test harness that split test cases so agents would encounter different failures. The same file conflict the docs warn about, playing out across 16 agents at once. The solution required custom infrastructure outside of Claude Code itself.

Context Rot: Context windows filled up fast. Test output from a full compiler run can flood the context with thousands of lines of irrelevant diagnostics. Carlini built --fast flags that run random subsamples of tests so agents could check their work without burning their entire context on output. Claude also can't tell time, so agents would happily run a full test suite for hours without realizing they were blocked. The --fast flags doubled as a time management hack.

What did Carlini prove about agent teams: The compiler experiment proves that parallel Claude agents can produce real, working software at non-trivial scale. It also shows that the coordination problems (file conflicts, context pollution, unbounded execution) don't disappear when you throw more agents at them; they multiply. Every solution Carlini built (the oracle test harness, the --fast flags, the task lock files) was custom infrastructure built to solve problems the agents couldn't solve on their own.

Where agent teams break down

Section 2 covered the file conflict and context pollution problems through the lens of Carlini's compiler experiment. Those are real, but they're also the obvious failure modes. The structural limitations of agent teams as a coordination primitive are more interesting, because they're not bugs waiting to be fixed. They follow directly from how the feature works.

Agent collisions

When multiple agents work on the same codebase independently, they tend to notice the same things. In the compiler project, agents would all encounter the same failing test during a Linux kernel compilation and independently try to fix it. Carlini's solution was a custom oracle that split test cases so agents would hit different failures.

This isn't specific to compilers. If you spin up a team to investigate a production bug, there's a good chance multiple teammates will trace the same stack trace to the same root cause and file near-identical reports. The lead then has to deduplicate rather than synthesize. You spent tokens on three agents but got one answer.

So what’s the underlying issue? Agent teams don't have a mechanism for teammates to check what others are already working on in real time. The inbox system lets them report findings after completing work, but there's no shared state that prevents duplicate effort during work. Carlini solved this with lock files in current_tasks/. The Claude Code feature relies on the team lead's judgment to assign non-overlapping work upfront, which works well for clearly decomposable tasks and poorly for investigation where the right decomposition isn't obvious until you're mid-exploration.

Supervising agents

Anthropic's own docs include this line: "Letting a team run unattended for too long increases the risk of wasted effort". That's a carefully worded way of saying agent teams need babysitting.

Each agent drifts independently, and the drift compounds. In a single Claude Code session, you can watch the agent's reasoning and course-correct when it goes off-track. With a team of four agents running in parallel, you're monitoring four streams of work simultaneously.

You can cycle between teammates with Shift+Up/Down, but you can only read one at a time. If teammate #3 goes down a rabbit hole while you're reviewing teammate #1's findings, you won't notice until #3 reports back with wasted work.

Agent teams exist to parallelize work, but monitoring parallel work is inherently harder than monitoring serial work. The more agents you add, the more supervision overhead you take on. Carlini's 16-agent setup required building automated test infrastructure specifically to catch agents that were spinning. For a three-agent team reviewing a PR, the overhead is manageable. For anything larger or longer-running, you need external structure to keep agents on track.

Single model per session

Agent teams don't support per-teammate model selection, rather every teammate uses the same model.

If your session runs Opus, every teammate runs Opus. If it runs Sonnet, every teammate runs Sonnet. This gets expensive quickly.

Different tasks within a parallel workflow have very different intelligence and cost profiles. Planning tasks benefit from a strong model that can reason about architecture. Tasks that grep through a codebase counting function signatures don't need Opus-level reasoning and shouldn't cost Opus-level tokens. A security review probably wants the strongest model available, while a formatting check could run on Haiku.

In the compiler experiment, every agent ran the same model for every type of work: planning, implementing, testing, debugging, documenting. Carlini's $20,000 bill reflects this. Some of that spend went toward Opus-level reasoning for tasks that could have been handled by a cheaper model, and there's no way to optimize that within the current agent team’s design.

Custom agents in Claude Code do support per-agent model selection (you specify the model in the agent's .md definition). But custom agents are single-session primitives. Agent teams, which give you parallel execution, don't give you model flexibility, so you currently have to choose.

For API users, this is a cost optimization problem. For Pro subscription users, it's a rate limit problem: agent teams multiply token consumption with no way to route cheaper tasks to cheaper models. A three-agent team burns through your daily allocation roughly three times faster, and every teammate consumes Opus tokens whether the task warrants it or not.

No checkpoints or approval gates

The bottleneck in multi-agent work is validation. Running four agents simultaneously is easy. Knowing whether each agent's output is correct before the next agent consumes it is the hard part, and agent teams have no structural answer for it.

When a workflow runs through agent teams, progress depends entirely on the model's judgment about when a task is "done." There's no mechanism to insert a validation step between phases of work, like "confirm the bug is actually reproduced before starting the fix" or "run the test suite before moving to documentation."

In a single Claude Code session, you can approximate this by being present and saying "wait, check this before continuing." With agent teams, you'd need to monitor each teammate's progress and manually intervene at the right moment. For a three-agent PR review, that's fine because the task is inherently one-shot: each agent reviews and reports. For a multi-phase task like bug reproduction (reproduce, then debug, then fix, then test), there's no structural way to enforce "don't start debugging until reproduction is confirmed."

The team lead coordinates task assignment, but it doesn't validate task completion. A teammate says "done" and the lead trusts it. If the reproduction agent reports "bug reproduced" but actually reproduced something slightly different, the debug agent proceeds on a false premise and the error compounds through every subsequent step. Adding more agents doesn't help here. It makes validation harder because there are more handoffs to check.

Visibility is terminal output across tmux panes

The monitoring interface for agent teams is tmux. You split your terminal into panes, one per teammate, and watch the output scroll. As mentioned before, can also cycle between teammates within a single pane using Shift+Up/Down.

For a short-lived team of two or three agents doing read-only work, this is adequate. For anything longer or more complex, you're watching multiple streams of unstructured text and trying to hold the state of each agent in your head. There's no summary view of "agent 1 is 60% through its task, agent 2 is blocked on a failing test, agent 3 finished and reported findings." You have to read the raw output and figure that out yourself.

Carlini's compiler setup had the same visibility challenge at a much larger scale (16 agents). His solution was to watch git commit messages and task lock files to infer what agents were doing. He built external tooling to track progress because the agents themselves didn't provide structured status updates.

Terminal output shows you what agents are producing, but not which step they're on, what's passed validation, or what's blocked. That kind of structured execution tracking doesn't exist in agent teams yet.

What’s the value of structured orchestration?

Agent teams sit at one point on a coordination spectrum.

On one end, subagents: single-session helpers that do a task and report back. On the other end, explicit workflow definitions where every agent, sequence, checkpoint, and model choice is specified upfront. Agent teams land in the middle: multi-session parallelism with coordination through model judgment.

The limitations from section 3 (convergence, supervision, single model, no checkpoints, terminal visibility) all trace back to the same design choice: agent teams coordinate through the team lead's reasoning rather than through explicit structure. That choice buys you flexibility.

You describe what you want in natural language and the lead figures out how to decompose it. But it also means every coordination decision (who works on what, when a task is done, what happens when something fails) depends on the model getting it right.

Structured workflow orchestration takes the opposite approach. You define the coordination explicitly: which agents run, in what order, with what validation between steps. The model handles execution within each step, but the structure between steps is fixed.

Take the multi-perspective code review from section 2 (security audit, performance review, architectural assessment in parallel) and add a sequential phase: after the reviews complete, an agent synthesizes findings into an action plan, and a final approval step validates the plan before it's marked complete.

This is how we’d set this up with Reliant:

On rejection: Step 2 re-runs with feedback included in context

On approval: workflow completes, action plan delivered

Each agent runs a different model at a different effort level. The Security and Architecture Reviewers run on Opus because those assessments benefit from stronger reasoning. Performance Reviewer runs on Sonnet because it's mostly checking quantitative patterns (N+1 queries, unindexed lookups, unnecessary allocations) where Sonnet is adequate and cheaper. Synthesis Agent runs Opus at max effort because it's doing the hardest reasoning in the workflow: reconciling three perspectives into one coherent plan. Approval Agent runs Sonnet at medium effort because it's checking against known conventions, not generating novel analysis.

In agent teams, all of these would run the same model at the same effort level. For a workflow like this, that means either overpaying for the performance review and approval check (if you run Opus) or under-powering the security review and synthesis (if you run Sonnet).

This matters more because models tend to perform differently across roles. Engineers consistently report that LLMs catch problems during review that they introduced during implementation: the same model that writes a bug will flag it when asked to review against the original spec. If review is where models are most reliable, you want your review agents running at high effort on a strong model, and you can afford to run implementation agents cheaper. Uniform model selection across a team prevents that optimization entirely.

The checkpoint at Step 3 does something agent teams can't express: it gates progress on validation. The approval agent checks the synthesis against the repo's conventions (pulled from local context that smart onboarding generated from the codebase). If the action plan misses something or contradicts a convention, the workflow loops back to Step 2 with specific feedback rather than delivering a flawed result. The team lead in agent teams would need to catch this by reading the output and manually intervening.

And because each step in the workflow is a defined node, execution tracking shows you exactly where things stand: which parallel reviews have completed, whether the synthesis is running, whether the approval passed or rejected. If the workflow fails at Step 2 (say, a rate limit or context overflow), you resume from Step 2 with the Step 1 results still intact rather than re-running the entire pipeline.

Where this doesn't make sense

Structured workflows require you to know the structure upfront. If you're investigating a bug and you don't know whether the problem is in the frontend, the backend, or the database layer, defining a fixed agent sequence before you've explored the problem is premature. Agent teams are better here because the lead can decompose the work dynamically based on what teammates discover.

The same applies to open-ended research, prototyping, and any task where the right decomposition only becomes clear mid-execution. Agent teams trade structural guarantees for flexibility, and that's the right tradeoff when the task is genuinely exploratory.

There's also a subtler limitation: structured workflows shift the bottleneck from "monitoring agent work" to "defining agent work well enough upfront."

Writing a good workflow definition is its own skill. If your task decomposition is wrong, the structure doesn't save you; it just makes you wrong in a more organized way. The workflow builder helps by making decomposition visible and editable, but the thinking still has to come from the engineer.

The decision framework is straightforward: if you can write down the steps before starting, structured orchestration gives you per-agent model selection, checkpoints, visual tracking, and resume capability. If you can't write down the steps because you need to discover them, agent teams let you describe the goal in natural language while the lead figures out decomposition on the fly.

Most real engineering work involves both. You investigate (exploratory, agent teams are well-suited) and then you execute a known process (structured, workflow orchestration is well-suited). A bug goes through an open-ended investigation phase where you don't know what you're looking for, followed by a reproduce-debug-fix-test sequence that follows the same steps every time.

Building on these primitives

Agent teams don't exist in isolation. They combine with Claude Code's other primitives, and the combinations matter more than any single feature.

Custom agents define the roles your teammates play. A teammate spawned as your security-reviewer custom agent carries that agent's system prompt, tool permissions, and behavioral constraints into its isolated session. Skills (CLAUDE.md files) give every agent access to your codebase conventions, API patterns, and architectural decisions. Hooks trigger actions at specific points in the execution: run linting after every file edit, execute tests after implementation, post a summary to Slack when a team completes its work. Together, these primitives turn a generic "investigate this codebase" team into a specific, configured squad that knows your project's rules and follows your team's process.

These combinations are assembled manually. You write the custom agent definitions, maintain the skill files, configure the hooks, and prompt the team lead with the right decomposition strategy. The orchestration layer (who runs when, what validates what, when to stop and check) lives in your prompt and the model's judgment rather than in explicit structure.

Agent teams are still marked experimental in Claude Code's documentation. Anthropic is iterating on the messaging protocol, the coordination patterns, and the interfaces between lead and teammates. The primitives will get more composable, the coordination will get more structured, and the boundary between "flexible agent team" and "defined workflow" will narrow. Future versions will likely support typed message schemas between agents, coordination strategies beyond the lead-teammate pattern, and hook integration for checkpoint-like validation.

For now, the decision framework from section 4 holds. Use agent teams when you need parallel exploration and the decomposition isn't known upfront. Use structured workflows when you need sequential handoffs, per-agent configuration, validation between steps, and organizational reuse. Use both when a task has an exploratory phase followed by a known execution process.

The engineers getting the most out of multi-agent AI right now are the ones who recognize which phase of work they're in and reach for the right primitive. Agent teams gave Claude Code a real parallelism capability. Understanding its boundaries, and knowing what sits beyond them, is how you use it well.