Task subagents do not load project CLAUDE.md or .claude/rules/ -- project configuration silently ignored

Resolved 💬 12 comments Opened Feb 27, 2026 by nobul-jose Closed Jun 16, 2026

Description

Task subagents (launched via the Task tool) do not load project-level configuration files:

  • CLAUDE.md (project root)
  • .claude/rules/*.md
  • ~/.claude/CLAUDE.md (user-level)

These files define HOW the agent should behave in a project -- code conventions, error handling rules, cross-platform requirements, protected file review gates, etc. When a subagent works in the same project directory, it should get the same configuration loaded as the main agent. Currently it operates with no project context at all.

Distinct from existing issues

  • #12790 asks for optional conversation context forking (complex feature -- sharing chat history)
  • #26429 asks for CLAUDE_PROJECT_DIR env var (path access)
  • This issue: project configuration files that define behavioral rules are not loaded. This is baseline configuration loading, not optional context sharing.

Real-world impact

We maintain a cross-platform tooling project with ~15 rule files in .claude/rules/ covering error handling, script standards, cross-platform dispatch, protected file review gates, and more.

We wrote new error handling rules in .claude/rules/error-handling.md and .claude/rules/script-standards.md, then delegated a full audit of ~89 error-suppression patterns across all scripts to 6 parallel Task subagents. The subagents reported 10 violations found. A manual re-audit with the rules in main-agent context found 5 additional violations, 4 logic bugs, and 1 missing error path that the subagents missed entirely.

Root cause: The subagents did not have the rules loaded -- they applied their own interpretation of "error handling" rather than the specific requirements defined in the project's rule files. The subagent prompts included a summary of what to look for, but summaries lose precision compared to the actual rule language.

Current workaround

We maintain a coaching item: "Never delegate code-writing to subagents in projects with cross-cutting rules. Use subagents for research only, or include the critical rules verbatim in the subagent prompt."

This is unsustainable -- it means subagents can never be used for their most valuable purpose (parallel work on the same codebase) in any project that has meaningful rules. Including rules verbatim in every subagent prompt is error-prone and doesn't scale as rule files change.

Expected behavior

When a Task subagent is launched, it should automatically load:

  1. CLAUDE.md in the project root (and subdirectories as applicable)
  2. .claude/rules/*.md files
  3. ~/.claude/CLAUDE.md (user-level)

This matches what happens when a user starts a new claude session in the same directory.

Environment

  • Claude Code 2.1.62
  • Windows 11 (Git Bash) and macOS
  • Observed across multiple sessions

View original on GitHub ↗

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