# I Audited My Own Claude Code Subagent Setup With Search Console Data — Here's What Was Broken

> We audited our own 34-agent Claude Code setup and found scope overlap, over-permissioned tools, and a subagent that should've been a skill. The real fixes.

Canonical: https://www.agentickit.co/blog/subagent-setup-audit-fixes
Last updated: 2026-10-29

**Short answer:** We run 34 Claude Code subagents in this repo and still found three concrete setup mistakes when we audited it — two agents whose descriptions overlapped enough that Claude routed the same task to both on separate runs, one agent carrying read access to files it never needed (pure context bloat on every invocation), and one job that should have been a skill, not a subagent, because it never needed its own isolated context window. Below is the actual audit: what was bloated, how we narrowed scope, and the rule we now use to decide subagent vs. skill vs. hook.

This isn't a "best practices" listicle written from the outside. It's what broke in our own [agents directory](/agents) after building up to 34 subagents over several months, and the fixes we shipped this week. If you're running more than 5-6 Claude Code subagents in a repo, you likely have at least one of these three problems.

## Starting state: a 34-agent setup, and where it was bloated

AgenticKit ships 22 engineering subagents and 12 marketing subagents (installed separately via `--kit engineering`, `--kit marketing`, or `--kit both` — see the [Kit Picker](/tools/kit-picker)). That split alone solved the worst problem, which is marketing agents reading your Drizzle schema. But inside the engineering kit, auditing the actual agent files turned up three specific issues that a flat list of 22 names hides:

1. **Scope overlap.** `backend-architect` and `api-engineer` both had "design and implement backend logic" somewhere in their description. On two separate `/ship` runs for the same feature, Claude picked a different one of the two for the schema-touching part of the task — meaning the contract-vs-implementation split we wrote about in [how we structured 34 AI agents](/blog/how-i-structured-34-ai-agents) wasn't actually enforced by the description text, just by convention in our heads.
2. **Over-permissioned tool access.** `code-reviewer` had edit access left over from an earlier draft of the agent file, even though its entire job is to return PASS/FAIL and never implement its own fix. Every invocation was loading edit-tool context it structurally could not use correctly, because the agent's own playbook forbade using it.
3. **A subagent that should've been a skill.** `technical-writer` was defined as a full subagent with its own system prompt, triggered by `/write-docs`, but it never needed an isolated context window — it only ever ran as the last step of a chain that already had the relevant code in context. Giving it a separate subagent call meant re-reading files Claude had just read two turns earlier.

## Symptom: context pollution and duplicate work across agents

The visible symptom wasn't a crash — it was a `/ship` run on a routine feature taking noticeably more turns than the same complexity-S feature took three months earlier, with the transcript showing the same file being read by two different subagent turns inside one session. That's the generic failure mode worth naming: when two subagents can plausibly claim the same task, you don't get a single bad choice, you get Claude re-deriving context that was already current in the other agent's turn, and you pay for both.

The second symptom was more subtle: `code-reviewer` occasionally produced a diff instead of a PASS/FAIL verdict. Not because the agent "decided" to fix the bug — because the tool was there and the model used it when the review turn had edit access available, even though the agent's own file says "ask, don't implement." Removing the tool, not rewriting the prompt, is what actually stopped it; a permission the model structurally cannot reach for is more reliable than an instruction asking it not to reach for one it can.

## Fix 1: narrowing subagent scope boundaries

The fix for overlap wasn't a longer description — it was moving the boundary from "what this agent does" to "what this agent is the only one allowed to do, and what it's explicitly forbidden from touching." Concretely, for `backend-architect` vs. `api-engineer`:

- `backend-architect` owns contracts and layering decisions — it decides *that* an endpoint exists and what it returns, and it does not write the Zod validators or the route handler itself.
- `api-engineer` owns the route file and request validation — it implements against a contract that already exists, and if one doesn't exist yet, it says so instead of inventing one.

That distinction has to live in the agent file as an explicit "do not" line, not just an implicit "primary responsibility" line, because Claude routes off the description text, not off intent you only wrote down once in a blog post. The same fix applied to `postgres-pro` (schema and indexes only — never route logic) and `integration-engineer` (third-party API clients and webhooks only — never your own schema). Three writers, three non-overlapping failure modes, each with an explicit boundary instead of an implicit one.

For `code-reviewer`, the fix was simpler: drop edit-tool access from the agent definition entirely. A reviewer that cannot edit cannot "helpfully" fix what it was asked to critique.

## Fix 2: when to use a subagent vs. a skill vs. a hook

The `technical-writer` case forced us to write down a rule we'd been applying inconsistently. The three mechanisms solve different problems, and the test is "who decides it runs, and does it need its own context window":

| Mechanism | Who triggers it | Gets its own context window? | Use it when |
| --- | --- | --- | --- |
| Subagent | Claude routes to it, or a command invokes it by name | Yes — isolated | The task needs a different persona/boundary than the main thread (a reviewer that must not implement; a specialist with its own required-skills list) |
| Skill | Claude matches it by description, mid-task | No — runs inline in the current context | The task needs a specific procedure or reference (how to write a Stripe webhook handler) but not a role boundary |
| Hook | A lifecycle event fires (pre-commit, post-tool-use) | No — runs outside the agent loop entirely | The rule must apply every time, deterministically, with no chance the model skips it |

`technical-writer` moved from a subagent to a documented step inside the `/write-docs` command plus a `technical-docs` skill reference, because its actual job — read the code already in context, write the doc — never benefited from a fresh context window. It only ever ran as a tail step of a chain, so isolating it just meant re-loading what the chain already had. We kept it as a subagent for the one case where it genuinely helps: a standalone `/write-docs` call with nothing else in context, where the isolation prevents an unrelated feature's half-finished code from leaking into the docs.

The general rule we now apply before adding the 35th agent: if the job only ever runs at the end of an existing chain with no new persona or permission boundary, it's a skill or a command step, not a subagent. If it has to apply on every commit regardless of what the model "decides," it's a hook, not an agent you hope gets invoked.

## Before/after: what actually changed

We didn't instrument token-level cost tracking before this audit, so the only honest comparison is structural, not a measured percentage — and we're not going to publish exact timing or token-cost numbers we didn't measure. What we did verify directly, by re-running the same complexity-S feature slice before and after the fixes:

- The duplicate-file-read pattern (same file read by two subagent turns in one session) no longer appeared in the transcript for that feature.
- `code-reviewer` could not produce an edit diff even when prompted to, because the tool access no longer exists in its agent definition — a structural fix instead of a prompt-level one.
- The `/ship` chain for that feature dropped from invoking `technical-writer` as a separate subagent turn to handling docs inline inside the existing `/write-docs` step, removing one full context-isolation boundary (and the re-read it caused) from the chain.

If you want to run this same audit on your own setup: open every subagent file you have and ask two questions per file. First, "is there another agent whose description could plausibly also claim this task?" — if yes, add an explicit "do not" line to each, not a longer "do" line. Second, "does this agent's job ever run as a tail step of something else, with nothing new to isolate?" — if yes, it's a skill or a command step waiting to be demoted. Both checks take minutes per agent and don't require any tooling beyond reading the files.

## FAQ

**How many Claude Code subagents is too many?** There's no fixed number — the AgenticKit kit ships 22 engineering and 12 marketing subagents split by install kit specifically so a founder who only ships code doesn't load the other 12 into context at all. The real signal isn't a count, it's whether two agents' descriptions could plausibly claim the same task. If they can, you have one too many regardless of the total.

**What's the difference between a subagent and a skill in Claude Code?** A subagent gets routed to by Claude (or invoked by name from a command) and runs in its own isolated context window — use it when a task needs a different role or permission boundary than the main thread. A skill runs inline, matched by description, with no separate context window — use it for a procedure or reference the current thread should just apply, not delegate.

**Why would giving a subagent fewer tools fix a behavior problem?** Because an instruction ("don't implement, only review") is advisory, while removing the tool that implements is structural. In our audit, `code-reviewer` stopped producing edit diffs once edit access was removed from its agent definition — not because the prompt changed, but because the capability no longer existed to reach for.

**Should a documentation-writing agent always be a subagent?** Only if it runs standalone with nothing else already in context — the isolation then prevents an unrelated feature's half-finished code from leaking into the docs. If it only ever runs as the last step of an existing chain, isolating it just means re-loading context the chain already had, which is pure overhead.

**Is it safe to combine a reviewer and an implementer into one subagent for a small project?** No — that's the same mistake the [34-agent structure post](/blog/how-i-structured-34-ai-agents) and the [first workflow mistakes post](/blog/first-ai-coding-workflow-mistakes) both call out: a reviewer that can also implement will approve its own fix. Keep those as two turns even in a two-agent setup.

**Is a subagent the same thing as an Agent Team?** No, and that distinction is worth getting straight before you scale past a couple of agents — see [Agent Teams vs. Subagents](/blog/claude-code-agent-teams-vs-subagents) for the full breakdown of when each applies.

**Is there a general checklist for designing a subagent, not just fixing one that's already broken?** Yes — see [Claude Code Subagents Best Practices](/blog/claude-code-subagents-best-practices) for the five rules (single responsibility, proactive-trigger descriptions, CLAUDE.md inheritance, concurrency, and the scope-creep mistake this audit is one instance of).

**How many subagents can actually run at once, and can I set a different model per agent?** There's no single official number for concurrent subagents published in Claude Code's docs — see [Claude Code Subagent Limits: Concurrency and the Model Setting](/compare/claude-code-subagent-concurrency-model-setting) for how to set a per-agent model in frontmatter and why context isolation matters more than the raw count.

## Sources

- AgenticKit's own [agents directory](/agents) and `/ship` [command chain](/commands/ship), audited directly on our own repo, 2026-10-29 (first-party, not published externally)
- [How I Structured 34 AI Agents](/blog/how-i-structured-34-ai-agents) — the original org design this audit tested against
- [First AI Coding Workflow Mistakes](/blog/first-ai-coding-workflow-mistakes) — the reviewer/implementer split this audit re-confirmed
- [20 Best Claude Code Subagents for SaaS Founders in 2026](/blog/best-claude-code-subagents-2026) — the ranked list of which roles to set up first, with the tool grant each needs

_Written by Rakshit Yadav. Published 2026-10-29, last updated 2026-10-29._


## Related
- [agent-chain](https://www.agentickit.co/tools/agent-chain)
- [kit-picker](https://www.agentickit.co/tools/kit-picker)
- [hooks-builder](https://www.agentickit.co/tools/hooks-builder)
- [tech-lead](https://www.agentickit.co/agents/tech-lead)
- [code-reviewer](https://www.agentickit.co/agents/code-reviewer)
- [backend-architect](https://www.agentickit.co/agents/backend-architect)
- [api-engineer](https://www.agentickit.co/agents/api-engineer)
- [project-conventions](https://www.agentickit.co/skills/project-conventions)
- [prompt-engineering](https://www.agentickit.co/skills/prompt-engineering)
- [/ship](https://www.agentickit.co/commands/ship)
- [/write-docs](https://www.agentickit.co/commands/write-docs)
