Learn why auto-generated Claude.md and agents.md files hurt your coding agent's performance. Discover what actually belongs in repository context files, how to structure your codebase for optimal agent discovery, and why minimal documentation is better than comprehensive guides.

Paper: https://arxiv.org/abs/2602.11988
My Guide To Agents.md: https://www.aihero.dev/s/mgEzPP

Sign up for the AI Hero newsletter:

https://www.aihero.dev/s/rEhore

Follow Matt on Twitter

https://twitter.com/mattpocockuk

Join the Discord:

https://aihero.dev/discord

Matt Pocock

Running `claude /init` generates a CLAUDE.md file that bloats the agent's system prompt with auto-discovered codebase documentation. This wastes tokens on every request, distracts the agent with irrelevant context, and quickly goes out of date as code changes. Research confirms that unnecessary requirements in context files make tasks harder. Instead, agents should rely on their built-in explore phase to discover context just-in-time. The only content worth putting in CLAUDE.md is truly global, non-obvious setup information (e.g., 'you are on WSL on Windows') — keep it to a minimum and let the file system and source code serve as the real source of truth.

Never Run claude /init

<p>In an enterprise environment, <a href="http://CLAUDE.md" target="_blank" rel="noopener nofollow">CLAUDE.md</a> proved instrumental to me to keep all of my PRs compliant with company and team conventions and well-informed about how different nested “projects” within the repos worked. Meticulously and carefully crafted, very much worth the context cost. My PRs were easy for the team to approve, and for me to produce.</p>


<p>Thanks for the information 👍🏼</p>
