Originally published at heyuan110.com
This is Part 2 of the Harness Engineering series. Most CLAUDE.md files are bad — not because people don't try, but because they optimize for the wrong thing.
ETH Zurich researchers tested 138 agentfiles across multiple AI coding agents. The results:
- Human-written, concise (<60 lines): +4% success rate
- LLM-generated, verbose (200+ lines): -3% success rate, +20% token cost
LLM-generated files made agents worse.
This guide covers:
- The 60-line principle: what to include, what to leave out
- Anti-pattern gallery (documentation dump, LLM manifesto, everything file)
- Progressive disclosure with Skills
- Templates for 3 project types (monorepo, API, frontend)
- How to measure if your CLAUDE.md is working
If you found this useful, check out my blog for more AI engineering guides.
Top comments (0)