Claude Code Agents Don't Automatically Read Project Documentation

How Claude Code Agents Handle Project Documentation

When working with Claude Code's agent system, developers should be aware of a specific limitation in how subagents access project documentation. According to a user report from r/ClaudeAI, when Claude Code dispatches agents to handle coding tasks, those agents operate with limited context.

Key Details from the Source

The issue was discovered during a debugging session where an agent repeatedly hit documented gotchas. When asked why it ignored the documented warnings, the agent responded: "I didn't read CLAUDE.md before writing the callback. I had the codebase patterns in my prompt context from the exploration phase, but when I dispatched the Sonnet agent to write the OAuth routes, the agent prompt described what to build, not what gotchas to check against."

The agent further clarified: "The Sonnet subagents only see what I put in their prompt. They don't automatically read CLAUDE.md, MEMORY.md, or any project context unless I explicitly tell them to."

Practical Implications

• Subagents like Sonnet work only with the context provided in their specific prompt
• Project documentation files (CLAUDE.md, MEMORY.md) are not automatically loaded
• Agents write code from scratch without consulting existing gotcha lists unless explicitly instructed
• This can lead to agents repeating documented issues that could have been avoided

This behavior means developers need to be explicit about including documentation references when dispatching agents to handle specific coding tasks. The agents maintain the codebase patterns from the exploration phase but don't automatically reference project-specific documentation files.