Español

Your Helper Agent Never Read Your Rules

You hand a task to a helper agent. It comes back having ignored a convention you've had written down for months. The natural conclusion is that it disregarded the rules. The likelier explanation is that it never received them.

A subagent is a new session, not a continuation

The mental model that causes the problem is picturing a subagent as an extension of your conversation — a colleague who has been in the room and is now going off to do one piece. It isn't. It's closer to a brand new session that happens to have been handed a task description.

What a non-fork subagent starts with is a short list: its own system prompt plus environment details, the delegation prompt written when the work was handed off, the CLAUDE.md hierarchy, a git status snapshot, any skills named in its skills field, and a roster of sibling agents.

What it does not get is the part that surprises people:

• Conversation history — none of it
• Your output style
• The main conversation's auto memory
• Files that have already been read into context

That last one causes the most confusion. You spent twenty minutes reading through a module together, then delegated a task about that module, and the helper starts by reading the same files again — or worse, doesn't, and reasons about them from the task description alone.

Explore and Plan skip the rules file entirely

There is a sharper edge here. The built-in Explore and Plan agents omit both CLAUDE.md and git status. Not as an oversight — deliberately, to keep research fast and cheap. There is no frontmatter field to change it.

This matters because those two are often delegated automatically. You didn't decide to spawn a subagent with no access to your conventions; the system reached for the right tool for exploration, and that tool is built to travel light. So a rule you'd consider non-negotiable can simply be absent from the agent doing the looking.

Note: Worth keeping in proportion: the main conversation reads Explore and Plan results back with full rules-file context. So a convention that governs how work is finally written usually doesn't need to reach the explorer. It's constraints that govern the exploration itself — don't read from this directory, treat this service as off-limits — that genuinely need restating.

Restate the constraints that matter

There is no configuration fix for this, and that's the right design — a subagent with a clean context is the entire point of delegating. The fix is in how you write the handoff.

Treat the delegation prompt as a full briefing rather than a pointer. A weak handoff names the task. A strong one names the task, the constraints that bound it, the context the agent can't derive, and what "done" looks like:

Weak:
  "Review the auth module for security issues."

Strong:
  "Review src/auth/ for security vulnerabilities. Focus on token
   handling, session management, and input validation. This app uses
   JWT tokens stored in httpOnly cookies. Report issues with severity
   ratings. Do not modify any files."

The second version survives an empty context. The first depends on shared understanding that isn't there.

When the task really does need everything: fork

Sometimes restating isn't practical, because the relevant context is an hour of accumulated decisions. Re-deriving it in a prompt is both painful and lossy. That's what forking is for.

A fork inherits the entire conversation, along with the main session's system prompt and tools. Start one with /subtask. It runs in the background and its result returns as a message in your main conversation, so the exploratory work stays out of your context while the fork itself has all of it.

The economics favour forks more than people assume. A fork shares the parent's prompt cache, which makes it cheaper than spinning up a fresh subagent that has to build its own. So the option that gives the agent more context is often also the option that costs less — the reverse of the usual tradeoff.

A rough rule: if you'd have to explain the background to a competent colleague before they could start, fork. If the task is self-contained and you can state it in a paragraph, delegate normally and write the paragraph properly.

The takeaway

A delegated agent is a new hire on day one: capable, and completely uninformed about your project's specifics. It gets the rules file — unless it's an Explore or Plan agent, in which case it doesn't even get that. It never gets your conversation. Brief it like the newcomer it is, or fork the conversation so it inherits everything you already know.