Subagents don't inherit .claude/rules/*.md auto-loaded context — 'always-on' rules silently skipped

Resolved 💬 2 comments Opened May 22, 2026 by fwilkerson-cn Closed May 26, 2026

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.

  1. 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).
  2. Let it complete.
  3. 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_delta and skill_listing attachments — no claudeMd block, no .claude/rules/*.md block.
  • Zero references to tdd.md anywhere in the transcript. The agent never opens it.
  • The agent did voluntarily Read CLAUDE.md early on (its own initiative), but CLAUDE.md does not restate the TDD rule — it relies on .claude/rules/tdd.md being auto-loaded.
  • The agent proceeded to implement the entire SUT first, then write tests against the finished surface. Classic implementation-first, exactly what tdd.md forbids.

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:true regression on Explore/Plan subagents (still unresolved on v2.1.142+)
  • #50093 — closed as dup of #40459
  • #59309 — SubagentStart hook workaround for CLAUDE.md propagation

View original on GitHub ↗

This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗