Writing a Good CLAUDE.md

An CLAUDE.md or (AGENTS.md, GEMINI.md) file is the single highest-leverage configuration point for coding agents. It’s injected into every conversation, acting as the agent’s onboarding document to your codebase. But reasearch shows that doing it wrong actively hurts performence. Here’s how to do it right, backed by data from “Evaluating AGENTS.md” (ETH Zurich, 2025). The Data Says: Less Is Auto-generated AGENTS.md files reduce task success rates by ~3% on average across multiple agents and models, while increasing inference cost by over 20.