How to Write CLAUDE.md Files That Actually Work (Harness Engineering #2)

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 Read the full article → If you found this useful, check out my blog for more AI engineering guides.