Claude Code agents, judged on what they do to your diff

On this page#

• How we judged them
• The shortlist
• What we rejected and why
• The one nobody talks about
• Choosing by repo shape
• FAQ

How we judged them#

The best Claude Code agents produce the smallest correct diff that preserves repository invariants, passes the relevant checks, and remains easy to review. We judge an agent by its changes—not its explanation, confidence, speed, or ability to make a broken task appear finished. “It runs” is only the beginning of acceptance.

An agent is a system that uses a large language model—software trained to predict and generate language—to inspect context, choose actions, and modify code toward a goal. The useful unit of comparison is therefore the resulting patch and the evidence attached to it.

Our acceptance order is strict:

1. Invariant preservation: Does the diff respect public APIs, data rules, security boundaries, and architectural constraints?
2. Task correctness: Does it solve the requested problem, including unhappy paths?
3. Verification: Did it run the checks that could actually disprove its work?
4. Diff quality: Is the change focused, legible, and free of unrelated cleanup?
5. Review cost: Can a maintainer understand the behavior change without reconstructing the agent’s reasoning?
6. Recovery cost: If the approach is wrong, is the patch easy to revise or discard?

That order matters. A broad refactor with a polished summary still loses to a five-line fix that preserves the contract. An agent that adds tests after changing behavior also loses if those tests merely encode its own mistake.

The Claude Code overview explains the product’s operating model. It does not remove the need to define repository-specific acceptance criteria. The agent can inspect the repository; it cannot infer every unwritten business invariant reliably.

A good task brief should contain:

• The observable behavior to change.
• The files or subsystem likely in scope.
• The invariants that must remain true.
• The checks required before completion.
• Explicit exclusions, especially “do not refactor” boundaries.
• The expected final evidence: tests, type checks, or a concise diff explanation.

If those details are missing, adding more agents is the wrong fix. You are parallelizing ambiguity.

Photo by mali maeder on Pexels.

The shortlist#

For production repositories, the useful shortlist is not a ranking of personalities. It is four operating patterns: one scoped agent, a planner plus implementer, isolated parallel agents, and a review agent. Pick the narrowest pattern that matches the repository’s coupling and the task’s uncertainty; additional agents create coordination cost immediately.

| Pattern | Best for | Configuration that matters | When not to use | |---|---|---|---| | One scoped Claude Code agent | Local bugs, contained features, and migrations with a known boundary | Give it one outcome, named invariants, a file boundary, and required checks | Avoid when discovery and implementation require different evidence or when several subsystems can change independently | | Planner, then implementer | Unclear defects, unfamiliar modules, and changes with several plausible approaches | Make the first pass produce a plan and risk list without editing; give the approved plan to a fresh implementation pass | Avoid for obvious, low-risk edits; the ceremony can exceed the work | | Parallel isolated agents | Independent packages, separate failing tests, or alternatives that can be compared as diffs | Assign non-overlapping ownership and require separate patches or workspaces | Avoid when agents would touch shared types, schemas, lockfiles, or central configuration | | Dedicated review agent | Risky patches, cross-boundary changes, and work where hidden assumptions matter | Provide the diff, requirements, and invariants; ask for counterexamples and missing tests, not a rewrite | Avoid treating review as proof—the original checks still have to run |

The official Claude Code documentation is the right reference for available product mechanics. Your operating policy should sit above those mechanics: who may edit what, which checks are mandatory, and which changes require human approval.

My default is one agent with a hard scope. I add a planning pass when the problem is uncertain, not when the code is merely large. I add parallelism only when ownership boundaries already exist in the repository.

For reusable task structures, PairFoundry tools can shorten the setup. Templates are useful only when they expose constraints; a longer prompt that hides the acceptance line is still a bad specification.

What we rejected and why#

We rejected agent swarms, unrestricted “fix everything” prompts, role-play specialization without real boundaries, and agent-written verification accepted at face value. These approaches optimize visible activity rather than patch quality. They often produce more files, more narration, and more apparent coverage while making the actual behavior change harder to trust.

The unrestricted autonomous run#

An unrestricted run is attractive because it reduces interaction. In a real repository, it also lets the agent redefine the problem while solving it. The diff can expand from a defect into refactoring, dependency changes, formatting churn, and tests that validate the new implementation instead of the intended contract.

The correction is simple: define the stopping condition before execution. “Fix the checkout failure while preserving the existing payment interface; touch only the checkout module and its tests; stop after the targeted checks pass” is reviewable. “Investigate and improve checkout” is not.

The agent swarm#

A swarm is the wrong default because most repositories contain shared choke points. Multiple agents editing a common schema, exported type, configuration file, or test fixture do not create independent progress. They create competing assumptions that someone must reconcile manually.

Parallel agents earn their place only when work can be partitioned by existing repository boundaries. The Anthropic overview can explain what Claude Code does, but repository topology determines whether parallel work is safe.

The fake specialist panel#

Calling one agent an architect, another a security expert, and another a test engineer does not create independent expertise. If all receive the same incomplete context, they can repeat the same assumption in different voices.

Specialization becomes useful when inputs and outputs differ:

• The planner returns constraints and a proposed change surface.
• The implementer returns a focused diff.
• The reviewer receives that diff and searches for counterexamples.
• The verifier runs predefined checks and reports results without editing.

That is a pipeline with separable artifacts, not a panel discussion.

Self-approved tests#

Tests written by the implementing agent are evidence, but they are not independent evidence. The agent may misunderstand the requirement and encode that misunderstanding perfectly.

Require at least one external anchor: an existing regression test, a documented contract, a caller’s behavior, or a human-specified example. Engineers who need stronger foundations before adopting a team workflow should start with PairFoundry’s free foundations track, then graduate to repeatable operating patterns.

Photo by Digital Buggu on Pexels.

The one nobody talks about#

The underrated option is a deliberately constrained single-agent pass followed by human diff review. It sounds less sophisticated than orchestration, but it usually gives the cleanest ownership, the fewest conflicting assumptions, and the lowest recovery cost. For tightly coupled repositories, “one task, one agent, one diff” is a strong default.

The key is to make the agent prove the patch rather than perform intelligence:

Goal:
Change the observable behavior described below.

Preserve:
- Public interfaces
- Existing data semantics
- Unrelated formatting and structure

Verify:
- Run the targeted tests
- Run the relevant static checks
- Report any check that could not run

Stop:
Do not refactor adjacent code or broaden the task.

This configuration is intentionally boring. Boring is good when a production diff will be maintained long after the conversation disappears.

A second agent can review the completed diff, but it should not silently modify it. Ask: “Which invariant could this patch violate? Which input is untested? Which changed line is unnecessary?” Those questions produce review leverage.

PairFoundry’s pack overview is useful when you want this discipline packaged for recurring work rather than recreated task by task. The broader operating context belongs in the landscape, not inside every implementation prompt.

Choosing by repo shape#

Choose Claude Code agent patterns by coupling, ownership, and verification speed—not repository size or trendiness. A large monorepo with clean package boundaries may support parallel agents safely, while a small application centered on one schema may require a single serialized change. The dependency shape predicts coordination risk better than line count.

• Tightly coupled application: Use one scoped agent. Add a read-only planning pass for changes touching shared state, authentication, or persistence.
• Modular monorepo: Parallelize only across packages with independent ownership and checks. Serialize edits to shared contracts, root configuration, and dependency metadata.
• Legacy repository with weak tests: Use a discovery pass first. Require the agent to identify callers, current behavior, and a reproducible failure before editing.
• Library or SDK: Optimize for compatibility. State the public surface explicitly and reject incidental API cleanup.
• Generated-code-heavy repository: Separate source edits from generated output. Tell the agent which files are authoritative and which are products of a defined generation step.
• Fast test suite: Keep verification inside every task.
• Slow or fragmented checks: Specify a targeted gate for iteration and the broader gate required before merge.

The Claude Code documentation should inform configuration details, but it cannot choose these boundaries for you. That decision belongs to maintainers who understand where the repository’s invariants live.

If you are deciding how to use agents in Claude Code, start with one constrained agent and measure the diff: correctness, unnecessary lines, missed tests, and review effort. Add another agent only when a specific failure mode demands separation.

Photo by ThisIsEngineering on Pexels.

Related reading#

• Claude Code agents team: what each one is genuinely good at
• Vibe coding tools: what each one is genuinely good at

FAQ#

What are agents in the Claude code?#

Claude Code agents are goal-directed coding workflows that inspect repository context, choose actions, edit files, and run checks. In practice, the important distinction is not the label “agent” but its scope, permissions, stopping condition, and required evidence. Judge the resulting diff against repository invariants.

Can Claude Code work as an agent?#

Yes. Claude Code can operate agentically by examining code, making changes, and verifying work within the capabilities and controls described in the official overview. Production use still requires explicit boundaries; autonomy does not supply missing acceptance criteria.

Is Claude Code still the best coding agent?#

There is no repository-independent “best” coding agent. Claude Code is a strong option when its workflow fits your codebase and produces correct, reviewable diffs. Compare tools on invariant preservation, verification, change focus, and recovery cost—not benchmark claims or the quality of their narrated reasoning.

Will Claude Code automatically use agents?#

Do not build a team process around assumed automatic behavior. Define the workflow you require: whether work needs planning, isolated implementation, independent review, or serialized ownership. Check the official documentation for current mechanics, then enforce repository policy explicitly.

Who are the big 4 AI agents?#

“Big 4 AI agents” is not a stable technical category or a useful acceptance criterion. Teams commonly compare prominent coding-agent products, but any fixed list becomes outdated or vendor-shaped. Evaluate the tools you are considering on the same repository task and judge their diffs using one acceptance rubric.