Do subagents inherit CLAUDE.md automatically when launched from Claude Code?

No. Each subagent runs in its own conversation context window with no automatic access to the parent's CLAUDE.md. The parent reads CLAUDE.md at session start as a local filesystem convention; that text never gets transmitted through the spawn payload. You must inject conventions into the subagent's system prompt or first turn, or accept that the subagent will operate without project rules.

Why doesn't Anthropic just propagate CLAUDE.md to subagents by default?

Because subagents are intentionally context-isolated. The whole point of a subagent is that its 20-file exploration does not pollute the parent context. Automatic CLAUDE.md propagation would re-introduce the very coupling subagents are designed to break. Treating CLAUDE.md as opt-in keeps the isolation guarantee; the cost is that you, the architect, must make inheritance explicit.

Should I inject the full CLAUDE.md or just the rules a subagent needs?

Inject a distilled convention block, not the full file. A 500-line CLAUDE.md wastes tokens on every spawn and dilutes attention. Pull the 10-30 lines that govern that subagent's task class - naming, output format, hard constraints, what NOT to touch - and inject those. Per the vault's context-window guidance, a 2KB TASK_CONTEXT block beats a 150KB blanket dump because the subagent has more of its 200K window for actual work.

Where exactly do I inject the convention block - system prompt or first user turn?

Both work; pick one and stay consistent across the project. System prompt is cleaner and benefits from prompt caching (the same block reused across many spawns pays cache cost once). First user turn is easier when you cannot edit the subagent definition file. The wrong answer is to put it in the second turn or rely on the subagent reading a file - by then the subagent has already made its first decision blind.

What is the most common failure mode this pattern catches?

A code-review subagent that flags none of the project's documented anti-patterns because it never received the anti-pattern list. The reviewer reads git diff, applies generic best practices, returns a clean summary, and ships code that violates three project rules. The fix is to inject the anti-pattern block in the reviewer's system prompt so its 'specialized review criteria' line in the Skilljar docs is actually populated.

Does the CLAUDE.md hierarchy (user / project / path-scoped) affect subagent inheritance?

Yes - and it makes the problem worse. The parent session resolves all three hierarchy levels at startup. The subagent sees none of them. If your project uses path-scoped rules (e.g., test-file conventions in .claude/rules/testing.md with a paths glob), those rules only auto-load in the parent when it edits a matching file. The subagent that runs the test never sees the glob match, never loads the rule, and never enforces it. Inject the relevant scoped block explicitly.

How does this show up on the CCA-F exam?

Under D1 (Agentic Architectures, 27%) and D3 (Agent Operations, 20%). Stem pattern: a subagent produces output that violates a stated project rule. Distractors usually include 'the subagent should re-read CLAUDE.md from disk' and 'increase the parent's context window.' Correct answer is always the injection step - the subagent never had the rules in context, so no amount of re-reading or window growth helps.

What is the 'convention block' and how is it different from CLAUDE.md?

A convention block is a 10-30 line subset of CLAUDE.md, scoped to one task class, that you prepend on every relevant subagent spawn. CLAUDE.md remains the source of truth for the parent. The block is the propagated subset. The two should be kept in sync via a template loader, not by hand. The /concepts/claude-md-hierarchy page explains why @import composition makes the source of truth modular enough to slice into blocks.

Can I make this work for MCP-based subagents that I do not own?

Partially. If you control the orchestrator, you can pass the convention block as part of the first tool input. If the MCP server is third-party and ignores extra fields, you are limited to whatever input schema it accepts - usually you cannot smuggle policy through a typed parameter. For third-party MCP, push enforcement to the post-processing layer: validate the subagent's output against the rules instead of asking the subagent to follow them.

How do I keep multiple subagents in sync when CLAUDE.md changes?

Centralize. Maintain one conventions file and one prompt template. Every subagent definition loads the block from the same place. When CLAUDE.md changes, the next spawn picks up the new block automatically. The anti-pattern is hand-copying the block into each subagent definition - within two weeks the copies drift, and you have five subagents enforcing four different versions of the rules.

Does this apply to /skills the same way as to subagents?

Yes. A skill is a packaged unit of instruction; it runs in whatever context the calling agent has. If the calling agent is a subagent without conventions, the skill executes without conventions. Inject the convention block at the subagent layer, and every skill the subagent invokes inherits it transitively through the shared context window.

Is there a tooling fix on the roadmap that will make this automatic?

Not in public docs as of mid-2026. The Skilljar Introduction to Subagents course explicitly frames context isolation as the design intent, not a bug. Expect prompt injection to remain the propagation mechanism. Build for it: template the block, version it with the conventions, and treat manual propagation as a permanent architectural responsibility, not a workaround.

Why Subagents Don't Automatically Inherit CLAUDE.md and How to Fix It

01 · TLDR

The short version

Subagents are independent Claude instances with fresh context windows. CLAUDE.md is a local filesystem convention the parent session reads at startup; it is never transmitted to spawned subagents. To make a subagent respect your project rules, inject a distilled convention block into its system prompt or first turn on every spawn. Centralize the block in one template so updates propagate without hand-editing five agent definitions. On the CCA-F exam this surfaces under D1 and D3 as scenario stems where a subagent breaks a stated rule and you must name the missing inheritance step.

02 · Why this matters in production

The silent rule-dropping bug

A code-review subagent shipped a PR that violated three of our project rules in one pass: it added a server-side import to a client file, used a forbidden API, and renamed a public export. Each rule was clearly written in CLAUDE.md. The reviewer returned a clean summary and approved the diff. The bug was not the reviewer; it was the assumption that CLAUDE.md is ambient. It is not. The reviewer never saw a single rule because none had been injected into its context. This is the most common multi-agent bug in production Claude Code pipelines and it is silent - the subagent does not warn you it is missing rules, it just operates without them.

Per the vault's context-window guidance: "Coordinator delegates with full 150KB case context expecting inheritance. Subagent wastes 100KB on irrelevant history. Fix: coordinator extracts a 2KB TASK_CONTEXT and passes only that. Subagent has 198K for actual research." The same principle applies to CLAUDE.md - except the default is not 150KB of garbage, it is zero KB of rules.

03 · The mechanics

How parent context is built, why subagents miss it, and what to inject

When Claude Code starts in a project directory, it loads CLAUDE.md in a defined order. Per the /concepts/claude-md-hierarchy page in the vault: "(1) reads user ~/.claude/CLAUDE.md (personal defaults); (2) reads project root .claude/CLAUDE.md or root CLAUDE.md (shared); (3) while editing a file, checks all .claude/rules/*.md files, tests the paths glob against the filename, and loads matches. All loaded content is concatenated and injected as context into Claude's system prompt." This is a one-time, parent-session filesystem operation.

A subagent does not repeat that operation. The Skilljar Introduction to Subagents course (Lesson 1) is explicit: "Each one runs in its own conversation context window... The intermediate steps - all the file reads, searches, and tool calls - stay in the subagent." The flip side is also true: anything the parent loaded into its own context is not visible to the subagent unless the parent explicitly passes it in the spawn message.

The fix has three layers. First, identify the rules that govern the subagent's task class - if it is a reviewer, the relevant rules are review standards and anti-patterns; if it is a styler, design tokens and component patterns. Second, extract those rules into a convention block, typically 10-30 lines. Third, inject the block at spawn time. The Skilljar Lesson 4 quote nails the intent: "This separation also lets you encode project-specific review standards in the subagent's system prompt, ensuring consistent review criteria across the team." The catch: that encoding does not happen automatically. You write it.

A minimal injection pattern looks like this:

# subagents/reviewer.md
---
name: reviewer
description: Code review subagent for this project
---

# Project convention block (mirror of CLAUDE.md §Code Style + §Anti-Patterns)
- Server-side imports never appear in app/ or components/.
- Named exports only; no default exports in lib/.
- Type hints required on every function (mypy strict).
- Reject any PR that adds a NEXT_PUBLIC_*KEY* variable unless it is a publishable key.

# Specialized review criteria
- Run git diff first.
- Flag every violation of the block above before commenting on style.
- Cite the violated rule by section so the human can verify.

Three things matter about that snippet. The convention block is scoped to what a reviewer needs - not the full CLAUDE.md. It is labeled as a mirror of CLAUDE.md so a future maintainer knows where the source of truth lives. The specialized criteria reference the block directly, which gives the subagent a closed loop: rule, check, citation. Without that structure the subagent treats the rules as advisory and ignores them under load.

For a multi-subagent pipeline (one orchestrator, four specialists), build a shared template loader. The orchestrator reads CLAUDE.md once, slices it into per-role blocks (reviewer block, styler block, security block, docs block), and injects the appropriate slice on each spawn. This costs one file - the loader - and prevents the failure mode where five subagent definitions each carry their own stale copy of the rules. Treat the rules like code: one source, many consumers, never hand-copied.

04 · Decision rule and checklist

Six steps to bulletproof inheritance

Catalog which rules each subagent class needs. Reviewers need anti-patterns; stylers need design tokens; security subagents need the secrets boundary. A subagent does not need the rules of a class it never executes.
Distill a per-class convention block from CLAUDE.md. 10-30 lines, scoped to the task class. Label it as a mirror so future maintainers find the source.
Inject the block at the system-prompt layer when possible.System prompts cache; first-turn injections do not. Across many spawns this is a real cost saving.
Reference the block from the subagent's task instructions.Tell the subagent explicitly to check the block before producing output, not to treat it as background context.
Centralize block storage in one file or loader. Hand-copying guarantees drift. One source, many consumers.
Verify on every meaningful CLAUDE.md change. Re-run a known scenario through each subagent class after editing the rules. A silent regression here is invisible until production catches it.

05 · Common anti-patterns

Five failures we keep seeing

Ambient assumption."The subagent will read CLAUDE.md because it's in the directory." Cause: confusing parent-session behavior with subagent behavior. Fix: treat injection as the only propagation mechanism.
Full-file dump. Injecting the entire 500-line CLAUDE.md into every spawn. Cause: avoiding the work of distillation. Fix: scope blocks to the task class; let unused rules stay in the parent.
Hand-copied blocks. The same convention block pasted into five subagent definitions. Cause: no loader. Fix: one file, one source; every subagent reads from the same template.
Background-context tone.Block injected but the subagent told "here are some guidelines" instead of "check this before output." Cause: weak prompt structure. Fix: make the block a hard constraint, with the cite-on-violation pattern in §The mechanics.
Path-scoped rule blindness. A scoped rule in .claude/rules/*.md that auto-loads in the parent never reaches the subagent that triggers it. Fix: inject scoped blocks explicitly when spawning a subagent that will touch matching files.

06 · CCA-F exam mapping

How this shows up on the exam

Domains: D1 Agentic Architectures (27%) · D3 Agent Operations (20%)
What is tested: Whether you can name the inheritance step as the defect when a subagent produces output inconsistent with stated project rules. The exam pattern is diagnostic: given a symptom, identify the architectural cause.
Stem pattern: A multi-agent pipeline ships output that violates a documented project rule. What change makes the subagent enforce the rule?
Distractor to reject: "The subagent should re-read CLAUDE.md from disk." Subagents do not browse filesystems for convention files; injection is the only mechanism.
Second distractor: "Increase the parent's context window." The parent already has the rules; the subagent does not. Window size does not change what crosses the spawn boundary.
Third distractor: "Switch to a larger model." A model upgrade does not invent rules that were never in context. This is the Model vs Design distractor heuristic documented in ACP-T03 §6.

07 · Sources

Vault and external references

Vault: data/aeo/reports/2026-05-17-recommendations.md §Signal 3 - source of the original five-bullet recommendation that seeded this page.
Vault: public/concepts/context-window.md§Where you'll see it in production - documents the 150KB-vs-2KB TASK_CONTEXT pattern that informs the distillation step.
Vault: public/concepts/claude-md-hierarchy.md §How it works - authoritative three-level load order (user → project → path-scoped) that subagents do not repeat.
Vault: 99-attachements/asc-a01-skilljar-course-content/course-16-introduction-to-subagents/lesson-01-what-are-subagents.md - Anthropic Skilljar definition: "Each one runs in its own conversation context window... intermediate steps stay in the subagent."
Vault: 99-attachements/asc-a01-skilljar-course-content/course-16-introduction-to-subagents/lesson-04-using-subagents-effectively.md - Skilljar quote on encoding project-specific review standards in the subagent's system prompt.
Vault: 02-tasks/acp-t03-claude-architect-competitive-research.md- "Subagents do NOT inherit coordinator context automatically. Every required fact must be explicitly passed in the subagent prompt. No shared memory, no history propagation."
Vault: public/concepts/subagents.md- "The message list inside the subagent is isolated from the coordinator. Every file read, every tool call, every intermediate result stays in that nested context window."

Why Subagents Don't Automatically Inherit CLAUDE.md and How to Fix It.

The short version

The silent rule-dropping bug

How parent context is built, why subagents miss it, and what to inject

Six steps to bulletproof inheritance

Five failures we keep seeing

How this shows up on the exam

Vault and external references

Adjacent reads

Subagents 101

Context window

Related

Share this primitive