CLAUDE.md: It's Not a README, It's a Directive for Your AI Intern

Ever noticed how many developers treat CLAUDE.md like yet another README? They dryly list the stack, a couple of preferences, and hope for the best. But in reality, it's not documentation — it's a directive for your AI assistant. Imagine hiring an intern who can read all your code but has zero clue about your habits. CLAUDE.md is their first-day instruction manual.

What do people typically put in it? "We use React, Next.js, PostgreSQL." That's it. Then they wonder why the AI suggests solutions that make them twitch. The right approach is to write in the style of: "Never use any, write tests with Vitest, and keep components functional." Yes, it looks more like a style guide, but that's exactly how the AI understands your preferences.

How to actually use it

• Rules over facts: not "stack: X", but "always do Y".
• Pain points: "If you see a DB query in a loop — stop and rewrite with a JOIN."
• Tone: write as if to a smart but inexperienced colleague. No jargon, but clear boundaries.

And no, CLAUDE.md won't replace code review, but it'll cut down the number of fixup commits in your PRs. If your AI still bikesheds, maybe you forgot to add "don't reinvent the wheel"?

METABYTE studio's take: Our devs also wrote CLAUDE.md like a README at first, until they realized AI isn't Google Docs — it's more like an intern who needs a clear "do/don't" list. Now every project has one, and we catch bugs faster than we can say "oh, it's another any".