I've been staring at CLAUDE.md files for months, writing them, rewriting them, watching what works and what doesn't. Somewhere along the way I stopped thinking of them as configuration and started thinking of them as product design. That shift changed everything about how I approach AI-assisted work.
The file that tells your AI agent how to behave has become the highest-leverage artifact in your entire workflow. Not the code the agent writes. Not the prompts you type in conversation. The persistent instruction set that shapes every interaction, that's the thing that compounds.
Configuration files were never the right metaphor
We've been treating CLAUDE.md like a config file. Like a .env or a tsconfig.json. Something you set up once, maybe copy from a template, and forget about. That framing is wrong, and it's making people write bad ones.
A config file maps known keys to known values. port: 3000. log_level: info. There's a correct answer and you fill it in. A CLAUDE.md is nothing like that. It's a set of design decisions about how an intelligence should behave in your context. What it should prioritize. What it should avoid. What "good" looks like in your world.
That's product design. Not configuration.
The research confirms what practitioners already felt
ETH Zurich tested this recently. Their findings were uncomfortable: LLM-generated CLAUDE.md files, the kind you get when you ask Claude to "analyze this repo and write a context file," actually made agents perform worse while costing 20% more in inference. The agents explored more, branched more, and failed more.
But human-written files that focused on specific, hard-to-discover requirements improved performance. Short, opinionated, operational. Not a repo tour, a cheat sheet for the non-obvious parts.
The pattern that emerged is exactly what you'd expect from product design: the best instruction sets are curated, not comprehensive. They make deliberate choices about what to include and, more importantly, what to leave out. Every line is load-bearing.
What a good CLAUDE.md actually looks like
The worst CLAUDE.md files read like documentation. They describe the architecture, list the tech stack, explain what each folder does. The agent can figure all of that out by reading your code. You're spending tokens on information the model would discover in seconds.
The best ones read like onboarding notes from a senior team member who knows where the bodies are buried.
"Run make lint before committing, not pylint directly. The Makefile adds flags that CI expects."
"Tests in the integration/ folder need a running database. Unit tests don't. If you're unsure, run make test-unit first."
"We never use em-dashes. In any content. Ever. Use commas instead."
Each of those lines encodes a decision that would be invisible to an agent reading the codebase. They're tribal knowledge made explicit. And tribal knowledge, it turns out, is the highest-value input you can give an AI agent.
The product design lens
Once you see CLAUDE.md as a product, the design principles become obvious.
Constraint over description. Don't tell the agent what your project is. Tell it what it should never do. "Never modify the database schema without explicit approval" is worth more than three paragraphs about your data model. Constraints are cheaper to evaluate and harder to violate.
Specificity over comprehensiveness. A 50-line file that covers the ten things that would actually trip the agent up beats a 500-line file that covers everything including the obvious. The research showed this clearly: more context isn't better context. It's just more expensive context.
Iteration over perfection. Your first CLAUDE.md should be short and wrong. Then you work with the agent, notice where it goes sideways, and add the specific instruction that prevents that failure. Over weeks, you build up a file that reflects the actual friction points, not the ones you imagined.
Voice over rules. This is the part people miss. A CLAUDE.md doesn't just control what the agent does. It controls how the agent communicates. My writing CLAUDE.md specifies tone, forbidden phrases, paragraph length, title patterns. Those aren't style preferences. They're product requirements for the output I'm shipping.
The compounding effect
Here's why this matters more than it seems. A good prompt helps you once. A good CLAUDE.md helps you every time.
Every conversation with your agent starts by reading that file. Every decision the agent makes passes through those constraints. If you spend an hour getting a prompt right, you've improved one interaction. If you spend an hour improving your CLAUDE.md, you've improved every interaction going forward.
This is the same math that makes design systems valuable. You don't build a component library because one button is hard to make. You build it because the hundredth button should be exactly as good as the first one. Your CLAUDE.md is a design system for agent behavior.
The uncomfortable implication
If the instruction file is the product, then the skill that matters most isn't coding. It's the ability to articulate, precisely and concisely, what good work looks like in your context.
That's a writing skill. A thinking skill. A product taste skill. It's knowing which constraints actually matter and which ones are noise. It's understanding your own standards well enough to make them explicit. Most people have never had to do that before, because the only person who needed to understand their standards was themselves.
Now you're explaining your standards to an intelligence that will follow them literally, thousands of times, across every task you give it. The gap between "I know good work when I see it" and "I can specify good work precisely enough for an agent to produce it" is where most people get stuck.
Practical starting points
If you're writing or rewriting your CLAUDE.md today, start here.
Open your last ten agent conversations. Find the moments where you corrected the agent, where the output wasn't right and you had to redirect. Each of those corrections is a candidate for your CLAUDE.md. If you corrected the same thing twice, it definitely belongs there.
Write constraints, not descriptions. "Always run tests before committing" over "Our project uses pytest for testing." The first one changes behavior. The second one states a fact the agent already knows.
Keep it under 100 lines. If you find yourself writing more, you're documenting your project, not designing your agent's behavior. Those are different activities.
Review it monthly. Your understanding of what the agent needs evolves as you use it. The file should evolve too. Treat it like a living product, not a one-time setup.
The real shift
We spent decades writing code that tells computers what to do, step by step, in languages designed for precision. Now we're writing prose that tells intelligences how to behave, in natural language designed for nuance.
The CLAUDE.md file sits right at that boundary. It looks like a config file. It acts like a product specification. And the people who treat it as the latter, who iterate on it, who curate it, who think of it as the most important file in their project, are getting dramatically better results than the people who generated it once and moved on.
Your code is the output. Your CLAUDE.md is the product.