Eleven Specialist Agent Files, One Squad: Contracts, Not Speeches
Opening eleven .claude/agents files showed me the real constraint is not persona prose: it is the tools, model, and hook fields in six lines of frontmatter.
TL;DR
Eleven subagent files are shaped more like contracts than personas: six lines of frontmatter decide tools, model, and permissions for each role. Scope tools tightly, enforce limits with hooks since rules aren't enforced, and keep every brief self-contained because agents share no context. Delegation costs tokens, so only hand off work worth splitting.
I opened eleven new files under .claude/agents/ in a single maintenance commit on KotaPortal: architect, backend-engineer, code-reviewer, debugger, dev-lead, frontend-engineer, infra-engineer, release-manager, researcher, security-reviewer, test-engineer. My guess: eleven long persona speeches. What I found instead is drier and better. The heaviest constraint in each file is six lines of frontmatter, not the prose under it.
The official docs are blunt about what a subagent is: "Each subagent runs in its own context window with a custom system prompt, specific tool access, and independent permissions" [1]. Once you accept that, the persona prose stops mattering and the fields start mattering.
Six lines that do the constraining
Here is the top of the code-reviewer file, trimmed to the fields:
name: code-reviewer
tools: Read, Grep, Glob, Bash, WebFetch, WebSearch, mcp__context7__*
model: opus
memory: local
maxTurns: 40
---The tools line is the one that bites. The docs list two reasons to scope tools: enforcing constraints on what a subagent can touch, and routing work to faster, cheaper models [1]. Reviewers get Bash but no file writes; the other read-only reviewers are locked down further, able to Write only inside their own memory directory. The dev-lead gets the opposite deal: a long list of Agent(...) calls naming all eleven specialists, and a ban on researching inline. Technical questions get routed to researcher.
The omitClaudeMd field decides whether the repo's CLAUDE.md files load for a given subagent [1]. Same principle throughout: hand each agent only what its job needs. Cost is the other half of the deal. Local experience in this repo says multi-agent work burns far more tokens than staying in one conversation, so the squad rule is strict: a one-file fix never gets delegated. I do not have a precise multiplier figure to cite; what I have is the habit of checking before I summon any specialist.
Reports that name their next consumer
All eleven files share one identical standards block. It contains a five-step escalation ladder for moments of doubt: repo evidence first, then library docs through context7, then the web for errors and releases, then report the gap to dev-lead if you lack the tools, and finally state plainly what is unknown. No guessing anywhere in the chain.
The piece I lean on most is the report contract: your report is the interface to the next consumer of your work, and you must say who that consumer is. That is why read-only reviewers like architect and security-reviewer put their findings in their final response while dev-lead is the one who persists rows to the board. Subagents share no context with the lead, so every brief must stand alone: objective, target files, constraints, acceptance criteria. The Anthropic write-up of their multi-agent research system frames it the same way: "A multi-agent system consists of multiple agents (LLMs autonomously using tools in a loop) working together", with subagents delivering separation of concerns through distinct tools, prompts, and exploration trajectories [2].
Gates, memory, and the hook that refuses
The squad works through a fixed gate order: design, implement, test, review, release. A failing gate loops back to the responsible role once; a second failure stops and reports to the human. Design approval, review acceptance, and deployment stay human decisions, never marked done on an agent's word.
The rules section is honest about its own limits. The Claude Code memory docs state: "Claude treats them as context, not enforced configuration. To block an action regardless of what Claude decides, use a PreToolUse hook instead" [3]. So every reviewer file also carries a hook that refuses git mutations through Bash, and read-only reviewers can write to no place except their own memory directory. Subagents can keep their own auto memory [3], which means settled convention verdicts do not get re-typed every session.
Verification is pinned to anything runnable: "Give Claude a check it can run: tests, a build, a screenshot to compare" [4]. A gate without a runnable check is just a conversation. And because "Context is a critical but finite resource for AI agents" [5], descriptions stay short: once the combined descriptions of custom subagents exceed 15,000 tokens, Claude Code warns at startup [1]. Detail belongs in the system prompt that loads only when that subagent runs.
I read agent files like employment contracts now. Who may touch what, who reports to whom, and where the work stops. The prose is just commentary.