Subagents don't inherit .claude/rules/*.md auto-loaded context — 'always-on' rules silently skipped
Summary
.claude/rules/*.md files that the harness auto-injects into the parent session as "project instructions, checked into the codebase" are not propagated to subagents spawned via the Agent tool. The rules are documented and promoted as always-on context-management primitives, but that promise only holds at the top level. Subagents silently ignore them.
Related but distinct from #40459 (which covers omitClaudeMd:true on Explore/Plan). This is the .claude/rules/ case, and it affects the general-purpose subagent too.
Repro
Project layout:
CLAUDE.md
.claude/rules/tdd.md # Documents red→green→refactor as "always-on"
.claude/rules/testing.md
In the parent session, tdd.md is auto-injected alongside CLAUDE.md as "project instructions, checked into the codebase". Confirmed by inspecting the parent's claudeMd context block.
- From the parent, spawn a general-purpose subagent via the Agent tool with a non-trivial vertical-slice task (write a new service with tests).
- Let it complete.
- Inspect the subagent transcript at
~/.claude/projects/<dir>/<parent-session>/subagents/agent-<id>.jsonl.
Observed
- The subagent's initial system payload contains only
deferred_tools_deltaandskill_listingattachments — noclaudeMdblock, no.claude/rules/*.mdblock. - Zero references to
tdd.mdanywhere in the transcript. The agent never opens it. - The agent did voluntarily Read
CLAUDE.mdearly on (its own initiative), butCLAUDE.mddoes not restate the TDD rule — it relies on.claude/rules/tdd.mdbeing auto-loaded. - The agent proceeded to implement the entire SUT first, then write tests against the finished surface. Classic implementation-first, exactly what
tdd.mdforbids.
Expected
.claude/rules/*.md files that load into the parent as auto-context should propagate to subagents under the same load conditions documented in their frontmatter — or, at minimum, there should be a documented mechanism to opt subagents in. The current behavior makes "always-on" misleading: it's "always-on for the parent, silently dropped for subagents."
Why this matters
Recent guidance steers users away from monolithic CLAUDE.md toward structured .claude/rules/*.md for context management. As workflows move toward agentic dispatch (parent delegates real work to subagents), the rules need to land where the work happens. Today they don't, which means:
- The most load-bearing repo conventions (TDD, port/adapter discipline, mock-spec requirements) silently don't reach the subagent.
- Users can't tell from the transcript whether the subagent saw the rules — they only see the bad output.
- Mitigations (referencing rules inline from CLAUDE.md, SubagentStart hooks per #59309) put the burden on every project to work around the harness.
Version
2.1.148 (Claude Code)
Related
- #40459 —
omitClaudeMd:trueregression on Explore/Plan subagents (still unresolved on v2.1.142+) - #50093 — closed as dup of #40459
- #59309 — SubagentStart hook workaround for CLAUDE.md propagation
This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗