DEV Community

Paulo Victor Leite Lima Gomes
Paulo Victor Leite Lima Gomes

Posted on

subagents and specialized agents: parallelism without chaos

#agents #ai #productivity #softwareengineering

This is part 3 of a 5-post series on professional agentic coding for senior engineers.

Subagents are one of the most useful ideas in agentic coding.

They are also one of the easiest ways to create a mess.

The rule is simple:

Use subagents to isolate context and specialization.

Do not use subagents to create uncontrolled shared-state writes.

why subagents work

Main agent context is expensive attention.

If you fill it with logs, search results, failed attempts, screenshots, and five different hypotheses, the final implementation gets worse.

Subagents let you move noisy work out of the main thread.

Good subagent work:

  • read-heavy research
  • security review
  • test gap analysis
  • log investigation
  • API surface mapping
  • migration planning
  • docs summarization
  • fresh-context review

Bad subagent work:

  • six agents editing the same files
  • parallel refactors in one checkout
  • broad write access with vague roles
  • "everyone go fix payment bugs"

The first category reduces cognitive load.

The second creates coordination debt.

Codex example: read-only review swarm 

Review this PR using parallel read-only subagents.

Spawn:
- one agent for security and correctness
- one agent for missing tests
- one agent for maintainability and API design

Keep all agents read-only.
Wait for all three.
Summarize findings by severity with file references.
Enter fullscreen mode Exit fullscreen mode

This is a good use of parallelism because each agent has a different lens and no agent writes.

The main agent or human engineer integrates the findings.

Claude Code example: isolated investigation 

Use a subagent to inspect token refresh edge cases.
It should read src/auth and tests/auth.
Report only:
- likely bug locations
- missing tests
- risks
- file references

Do not modify files.
Enter fullscreen mode Exit fullscreen mode

That subagent can consume a lot of context without polluting the implementation thread.

Then the main session can turn the result into a small plan.

GitHub Copilot custom agents

GitHub Copilot's custom agents are useful when a repository has repeated specialized work.

Examples:

  • security reviewer
  • migration planner
  • accessibility reviewer
  • test coverage reviewer
  • documentation maintainer

The custom agent should have a narrow role, clear instructions, and constrained tools.

Bad custom agent:

---
name: backend-genius
tools: ["*"]
---

You are a world-class backend engineer. Fix whatever is needed.
Enter fullscreen mode Exit fullscreen mode

Good custom agent:

---
name: migration-reviewer
description: Reviews database migrations for safety and reversibility.
tools: ["codebase", "search"]
---

Review migration changes only.
Check for reversibility, locking risk, destructive operations, and missing rollout notes.
Do not modify files.
Return findings with file references and severity.
Enter fullscreen mode Exit fullscreen mode

Specific beats powerful.

parallel writes need separate worktrees

Sometimes parallel write work is valid.

But it needs isolation.

If two agents are implementing unrelated parts of a system, use separate worktrees or branches. Give each agent a narrow file ownership boundary. Merge deliberately.

Good:

Agent A: implement frontend validation in apps/web only.
Agent B: implement backend validation in apps/api only.
Use separate worktrees.
Do not edit shared packages without stopping for review.
Enter fullscreen mode Exit fullscreen mode

Bad:

Both agents: improve checkout flow.
Enter fullscreen mode Exit fullscreen mode

That is how you get two plausible designs, overlapping diffs, and a human stuck doing archaeology.

writer and reviewer is the safest pattern

The best first subagent pattern is not parallel implementation.

It is writer and reviewer.

  1. Main agent or writer session implements a bounded change.
  2. Fresh reviewer agent reads the diff.
  3. Reviewer reports risks and missing tests.
  4. Main agent fixes.
  5. Human reviews final diff.

The reviewer has fresh context. It is not emotionally attached to the plan. It is not trying to defend its own code.

That alone catches a surprising amount.

bad practice: every agent gets every tool

Tool access should follow the role.

A log-analysis subagent probably does not need write access.

A security-review subagent probably should not push branches.

A migration planner probably should not execute production migrations.

Broad tools feel convenient until the wrong agent takes the wrong action.

This is normal engineering governance. Apply least privilege to agents too.

checklist

Before spawning a subagent, ask:

  • What specialized question should it answer?
  • Should it be read-only?
  • What files or systems can it inspect?
  • What output format do I need back?
  • Will its work pollute or clarify the main context?
  • If it writes, what ownership boundary prevents conflicts?

If you cannot define the role in one sentence, it is probably not a good subagent yet.

sources

To test my projects, I use Railway. If you want $20 USD to get started, use this link.

Top comments (0)