Allow per-subagent exclusion of CLAUDE.md / .claude/rules (parity with built-in Explore/Plan)
What I'm trying to do
Run custom read-only review subagents (defined in .claude/agents/*.md) in a large monorepo without them inheriting the project's entire .claude/rules/ + CLAUDE.md context.
The gap
Per the docs, custom subagents inherit the parent's CLAUDE.md + .claude/rules/ at startup, and "Explore and Plan skip your CLAUDE.md files... Every other built-in and custom subagent loads both" (code.claude.com/docs/en/sub-agents). There is no frontmatter field or setting to give a custom subagent the same opt-out that the built-in Explore/Plan agents already have.
In a repo with a large rules tree (ours is ~600KB of .claude/rules/*.md once everything is counted), this matters a lot: a review subagent that reads a few files starts so close to the context limit that autocompact thrashes and the agent dies ("context refilled to the limit within 3 turns of the previous compact, 3 times in a row") before producing output. After each autocompact the always-loaded rules re-inflate at full size, so the compact never frees enough headroom.
Today's workarounds are all indirect:
claudeMdExcludesis session-wide (blunt) -- it also strips context from the parent, which usually still wants it.- Keeping rules small / path-scoping with
paths:helps the baseline but can't express "this agent doesn't need rules" independent of the parent.
A reviewer reviewing a diff genuinely does not need the repo's full institutional-knowledge rules loaded; its checklist lives in its own system prompt.
Proposed
A per-subagent control, e.g. one of:
- A frontmatter field on
.claude/agents/<name>.md:loadProjectRules: false/loadClaudeMd: false(or an inclusive allowlistloadRules: ["safety.md"]). - Treat custom agents the same as Explore/Plan when such a field is set.
This already exists internally for Explore/Plan, so the mechanism is presumably present -- this asks to expose it to custom agents.
Impact
Would let large-monorepo teams run reviewer / specialist subagents reliably instead of falling back to inline-in-parent or hand-curated /tmp diff payloads. Happy to test a build.
This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗