Context Engineering for Agents

You can build the most sophisticated multi-agent system in the world. Wire up every tool perfectly. Give agents full filesystem access. And still get garbage results.

The reason is almost always bad context. Agents don't read your mind. They read their context window. Vague instructions, missing details, irrelevant noise? The output mirrors that exactly.

Context engineering is assembling the right information package so an agent does its job correctly on the first try. Not the second try after you correct it. The first try. Most people underestimate how much this matters compared to everything else.

Why Context Is the Fundamental Constraint

Every LLM has a context window, and performance degrades as it fills up. More tokens doesn't mean better results. Stuffing a context window with everything you can think of actively hurts performance because the model has to sort through noise to find signal.

This hits especially hard with subagents. When you spawn one, it starts completely fresh. No inherited conversation history. It gets a clean window with exactly four things: the system prompt from your agent config, the contents of CLAUDE.md, any preloaded skills, and the spawn prompt the lead agent writes when delegating.

That's it. The entire universe the subagent knows about. If you didn't explicitly include something in one of those four sources, the agent doesn't know it. Won't go looking. Won't ask questions. It'll work with what it has, and if that's insufficient, it'll hallucinate the rest. Confidently.

The Anatomy of Good Context

Good context is specific, scoped, structured, and sufficient.

Specific: name exact files, functions, and constraints. "Review lib/auth.ts for SQL injection vulnerabilities" versus "review everything for security issues." The gap between those two prompts is often the gap between a useful result and a wasted context window.

Scoped: limit the task to what the agent can actually finish within its context budget. Ask it to refactor an entire codebase and it'll either run out of context or produce shallow changes across too many files. Narrow beats broad every time.

Structured: organize information so the model can parse it efficiently. Clear headers, most important details first, instructions separated from reference material. Your CLAUDE.md is a textbook example.

Sufficient: include everything the agent needs, no more. If the task requires a specific API schema, include it or point to it. If there are constraints like "don't modify the public API surface," say so explicitly. Agents don't infer constraints. They ignore them.

Controlling the Context Package

Several levers for controlling what lands in a subagent's context window.

System prompt is the markdown body of your agent definition. Describe the role, expertise, standard procedure. Keep it focused on the "who" and "how." The "what" comes from the spawn prompt.

Preloaded skills inject domain knowledge at startup. Your code review agent needs to understand your error handling conventions? Preload a skill with those conventions. The agent has that knowledge from the moment it starts.

Tool restrictions via tools and disallowedTools control what the agent can do. A research agent only needs read access. A reviewer shouldn't have write access. Restricting tools isn't just safety. It helps the agent focus by removing irrelevant capabilities from its decision space. Fewer tools, less confusion.

Model selection should match task complexity. Haiku for quick exploration. Sonnet for balanced speed and reasoning. Opus for deep multi-step analysis.

The spawn prompt is what the lead agent writes when delegating, and it's often the weakest link. The lead agent will write vague prompts unless you tell it not to. In your agent's description field, spell out exactly what information the lead should include when spawning. Easy to overlook, expensive to get wrong.

Try It

Create a PR reviewer agent. Start with .claude/agents/pr-reviewer.md and think about what context it actually needs.

System prompt: the agent's role and your team's review standards. Preload skills for your coding conventions. Use disallowedTools to block write access (it should analyze and report, not change things). In the description, spell out what the lead should include when spawning: PR number, files changed, specific concerns.

Test it on a real PR. Did the agent just work, or did it need follow-up? Every follow-up question means something is missing from the context package. Refine, test again, repeat until you get a useful review on the first try.

The Feedback Loop

Context engineering isn't a one-time setup. Every bad result is a signal. Task too broad? Narrow it. Agent missed a constraint? Add it to the system prompt. Lacked domain knowledge? Preload a skill. Treat failures as debugging data, not frustrations.

Agent-based hooks can verify conditions against the actual codebase state before problems compound. The memory field lets agents accumulate learning across sessions so you stop re-teaching the same lessons.

Over time you develop an instinct for what an agent needs to know versus what it can figure out. That instinct comes from paying attention to failures and closing gaps one by one. First-try correctness isn't luck. It's engineering.