Claude Code Agents: Custom Agents, Agent Teams, and How to Run Them Well

TL;DR

Claude Code agents are separately configured agent instances inside Claude Code: each one a markdown file defining a role, a model, a tool allowlist and instructions, invoked on demand or delegated to automatically. Teams use them to split work that one context window handles badly, to enforce least-privilege on risky tools, and to run genuinely parallel workflows. The mechanics are simple; the discipline is what separates teams that get leverage from teams that get chaos. This guide covers how agents are defined, when they beat a single session, and the coordination problem that every multi-agent setup eventually hits.

How do Claude Code agents actually work?

An agent is a definition file in .claude/agents/ (project-scoped) or ~/.claude/agents/ (user-scoped): frontmatter for the name, description, model and allowed tools, then a body of instructions that becomes the agent's system prompt. Three properties drive everything else:

1. Each agent runs in its own context window. A delegated task starts clean, does its work, and returns only its final text to the caller. The parent's conversation does not bloat with the agent's reading.

2. The description controls delegation. Claude Code matches tasks to agents by their descriptions, so an agent whose description names the situations it handles gets used, and one with a vague title never fires.

3. Tools are scoped per agent. A reviewer agent can be granted read-only access while a fixer agent gets write access, which turns least-privilege from a policy into a configuration.

Version the project-scoped ones with the repository, so the agent that knows your deploy process changes in the same pull request as the process.

When do agents beat a single session?

Four cases where the split earns its overhead, and the honest counter-case:

1. Context isolation for bulky work. A search across two hundred files, a long log read, a full-codebase audit: done inline, it floods the window that your actual task needs; delegated, it returns three lines of conclusion.

2. Parallel fan-out. Independent subtasks, such as reviewing five modules or testing five hypotheses, run concurrently in separate windows instead of sequentially in one.

3. Enforced roles. A security-reviewer agent that can read but never edit, an SRE agent that can run diagnostics but never deploy. The permission boundary holds even when the model would have been talked into something.

4. Repeatable specialist prompts. Instructions you keep retyping (how to review a migration, how your team writes tests) live once in the agent body instead of in every conversation.

The counter-case: for small tasks, delegation is pure overhead, since the subagent re-derives context the parent already had. If the task fits comfortably in the current window and needs no special permissions, do it inline.

What goes wrong with agent teams?

The failure modes reported by teams running multi-agent setups, in the order they usually appear:

1. Duplicated work. Parallel agents each read the same shared files and each burn tokens understanding them, because nothing tells agent B what agent A learned.

2. Contradictory conclusions. Two agents reach different answers about the same code, and the parent has no principled way to pick, because each saw a different slice.

3. Lost findings. An agent rules out an approach, explains why in its working, and returns a one-line recommendation. The reasoning is discarded with its context window, and tomorrow's agent tries the ruled-out approach again.

4. Cost surprise. Every agent pays its own orientation cost on every run. Five agents on a task can consume several times the tokens of one, so route by necessity rather than enthusiasm.

All four are the same root problem wearing different clothes: agents do not share what they learn. Isolation is the feature that makes them useful and the property that makes them forgetful.

How do teams solve the shared-knowledge problem?

Ranked from lightest to most durable:

The practical ladder: restate context for one-off tasks, use a scratch file for one session's fan-out, put stable conventions in CLAUDE.md, and adopt a shared memory layer when findings need to outlive the session or reach agents in other repos and other tools. Sentra plugs into that last rung over MCP: agents query one governed store of current facts (decisions, ownership, conventions, prior findings with timestamps), so the knowledge an agent team accumulates compounds instead of evaporating. That is also the honest scope note: for a solo developer in one repo, files are enough, and the memory layer starts paying at team scale.

What does a well-run agent setup look like?

1. Few agents, sharp descriptions. Five agents that each own a clear situation beat twenty that overlap. Write descriptions with the words a task would actually contain.

2. Read-only by default. Grant write and execute tools only to agents whose job requires them.

3. A return contract in every agent body. Specify the output shape (findings list, file-line references, confidence) so the parent can consume results without re-parsing prose.

4. State what a negative result looks like. Agents told "report an empty list if nothing is found" fabricate less than agents left to improvise.

5. A place findings go. Scratch file or memory layer, chosen deliberately, so conclusions survive the window that produced them.

FAQ

The decision rule

Create an agent when a role recurs with distinct permissions or a distinct playbook, delegate when the work would flood your window or genuinely parallelize, and decide where findings live before you scale past two agents, because an agent team without shared memory is a hiring plan for workers with amnesia.