In the realm of AI coding agents, the effectiveness of CLAUDE.md files is often suboptimal, not due to lack of effort, but rather misdirected optimization. New insights from ETH Zurich researchers highlight critical differences in performance based on how these agentfiles are crafted.
A study conducted by ETH Zurich analyzed 138 agentfiles across various AI coding agents, revealing significant findings:
- Human-written, concise
CLAUDE.mdfiles (under 60 lines) demonstrated a +4% increase in success rate. - Conversely, LLM-generated, verbose files (exceeding 200 lines) resulted in a -3% decrease in success rate and a notable +20% increase in token cost.
The research clearly indicates that overly verbose, LLM-generated agentfiles can actually hinder an AI agent's performance, making them less effective.
To address this, a comprehensive guide, part of the Harness Engineering series, outlines key principles for creating truly effective CLAUDE.md files. This guide covers essential topics such as:
- The 60-line principle, detailing what critical information to include and what to omit for conciseness.
- An anti-pattern gallery, illustrating common pitfalls like documentation dumps, "LLM manifestos," and "everything files."
- Strategies for progressive disclosure using Skills to manage complexity.
- Practical templates for three common project types: monorepos, API services, and frontend applications.
- Methods for measuring the actual performance and effectiveness of your
CLAUDE.mdimplementation.
By adhering to these principles, developers can significantly enhance the success rate of their AI coding agents while optimizing resource usage.