Specialised sub-agents and an orchestrator with Claude Code: when to delegate, limits and costs
A small team of agents (SQL, PowerShell, Azure, documentation reviewer) and an orchestrator: file format, briefs, parallelism, limits and costs.
A sub-agent is a specialist that Claude Code can delegate a task to. It runs in its own context window, with its own instructions and its own tools, and comes back with a summary. On a DBA repository I use a small team: a SQL expert, a PowerShell expert, an Azure expert, a read-only documentation reviewer, and an orchestrator that routes work between them.
What an agent file looks like
An agent is a Markdown file in .claude/agents/. The frontmatter says who it is and what it may do; the body is its system prompt.
---
name: sql-expert
description: Use for T-SQL work: queries, procedures, DDL, migration scripts, tuning, and placeholder templates read by PowerShell.
tools: Read, Edit, Write, Grep, Glob
model: inherit
---
You are a SQL Server and Azure SQL expert for this repository.
## Standards
Follow rule `sql-script.md`. Do not copy it here.
## Safety
Read-only queries are fine. Never run DDL or DML against production: write the script, stop.
## Output
What was done / files changed / how it was validated.
Three fields matter most:
descriptionis what the main session reads to decide whether to delegate. Say when to use the agent.toolsis the real permission boundary. A reviewer gets read and search tools only, so it physically cannot edit.modelcan be inherited or set to a cheaper model for simple roles.
My team
| Agent | Writes? | Role |
|---|---|---|
sql-expert |
yes | T-SQL, templates, tuning |
powershell-expert |
yes | functions, modules, Pester tests, lint |
azure-expert |
yes | pipeline YAML, Azure SQL, Batch, identity |
docs-expert |
yes | README, changelogs, comments |
docs-reviewer |
no | checks docs against the code, confirmed findings only |
orchestrator |
no | splits a multi-part request and routes it |
Naming convention: <domain>-expert writes, <domain>-reviewer only reads. The word tells you the risk before you invoke it.
When to delegate, and when not to
Delegate when:
- the task is self-contained and its result is a short summary (review this diff, find every caller of that function);
- it needs a lot of reading that would flood the main context;
- you want an independent view, for example a reviewer who has not seen your reasoning;
- several independent pieces can run in parallel (different files, different components).
Do not delegate when:
- the change is small. For a one-function fix, writing the brief costs more than the edit;
- two agents would touch the same file;
- the task depends on a long conversation that the agent has not seen.
How to brief an agent
An agent knows only what you put in the brief. A good one has four parts, which I use as a template:
Task: add a -WhatIf switch to function Remove-Foo in the shared module.
Context: the function is called by two applications; do not change its return contract.
Constraints: follow rule powershell-function; do not commit; do not run any entry script.
Expected outcome: changed files, lint clean, one Pester test.
Give rule names, not rule contents. State what is forbidden. Never put secrets or personal data in a brief.
The orchestrator
The orchestrator has no write tools. It reads the request, picks agents, sequences dependent work (the SQL first, then the PowerShell that consumes it), parallelises independent work, validates what comes back and writes the synthesis. If an agent fails twice, it escalates to me instead of looping.
flowchart TD
U["Request"] --> O["Orchestrator"]
O --> Q["sql-expert"]
O --> P["powershell-expert"]
O --> Z["azure-expert"]
Q --> P
P --> D["docs-expert"]
D --> R["docs-reviewer : read-only"]
R --> O
Z --> O
O --> S["Summary to the DBA"]
Limits and costs
- Tokens. Each agent starts with a fresh context and re-reads files. Several agents in parallel burn tokens quickly. Use them where isolation or parallelism pays.
- Lost context. The agent only sees the brief, and you only see its summary. Details disappear on both sides.
- Confident errors. A summary reads as sure of itself even when it is wrong. I open the cited files and confirm every reported finding before acting on it.
- Conflicts. Agents that edit the same file overwrite each other. One writer per file; no Git operations from agents.
- Hypothesis bias. If you hand a reviewer your conclusion, it tends to agree. Give it the code and the criteria.
Lessons learned
- Start with two agents, not nine. Add one when you notice you keep giving the same brief.
- Read-only reviewers are the best value: cheap, safe, and they catch what the author missed.
- Keep the standards in rules and let the agents point to them.
- The main session stays responsible. It validates, runs the checks and decides.