Allow per-subagent exclusion of CLAUDE.md / .claude/rules (parity with built-in Explore/Plan)

Resolved 💬 2 comments Opened May 30, 2026 by burkeyb Closed Jul 16, 2026

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:

  • claudeMdExcludes is 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 allowlist loadRules: ["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.

View original on GitHub ↗

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