Anti-Patterns

Role-Typed Subagents

Anti-pattern: pre-allocate roles (manager, coder, designer, researcher) across a fixed set of typed sub-agents and route tasks to them by role label.

Problem

Real workloads do not partition cleanly into the roles the architect imagined in advance. Tasks that fall between two roles get squeezed into whichever label is closest, and the chosen specialist underperforms because its tool palette is missing what the task actually needs. Adding a new role means changing the architecture rather than parameters, and capability-equal parallelism — running many fully capable, identical sub-agents in parallel on the same subtask — is structurally impossible because no sub-agent has the full tool set.

Solution

Don't bake role types into the architecture. Use one general-purpose sub-agent shape with the full tool palette and let the orchestrator route by task content, not role label. When specialisation pays, scope it per-call (system-prompt overlay, tool subset for this task) rather than per-agent-type. For wide tasks, prefer capability-equal fan-out over typed crews. See clone-fan-out-research, role-assignment (the valid form: per-call persona, not per-agent type), supervisor.

When to use

  • Never as the architectural backbone; role labels are not a free lunch.
  • Treat persona prompts as per-call overlays on general-purpose sub-agents, not as a fixed agent typology.
  • When tempted to add a new typed sub-agent, ask first whether a general-purpose sub-agent with a per-call overlay would do.

Open the full interactive page

Diagram, neighbourhood map, code examples, related patterns and full provenance.

Related