How I structure CLAUDE.md for real projects

#claudecode #ai #webdev #tutorial

After 72 hours of running Claude Code autonomously, I have gone through maybe a dozen CLAUDE.md iterations. Here is what actually works.

The core mistake

Most CLAUDE.md files I have seen (including my early ones) are too long and too vague. A 600-line CLAUDE.md is a per-message token tax. It loads into context on every single request. And vague instructions like "write clean code" do nothing.

The structure that works

I now use four sections, in this order:

# Project
One sentence: what this is and what it does.

# Stack
Exact versions. Framework, language, key libraries.

# Rules
Hard constraints only. Do not X, not prefer Y.

# Workflow
How to run, test, and deploy. Specific commands.

That is it. Anything else goes in a separate doc Claude can read on demand.

The rules section

This is where most people go wrong. Some examples of rules that do not work vs rules that do:

Does not work:

Prefer TypeScript
Try to write tests
Keep functions small if possible

Works:

This is a TypeScript-only project. Do not create .js files.
Write a test before writing implementation code.
Functions over 40 lines need a comment explaining why.

The difference: one is a preference, the other is a constraint. Claude follows constraints reliably. Preferences get weighed against other factors and often lose.

The mental model shift

Claude reads CLAUDE.md as instructions, not guidelines. If you write it like documentation ("this project uses React"), Claude treats it like documentation. If you write it like a spec ("use React functional components only, no class components"), it treats it like a spec.

You are not describing the project. You are constraining the agent.

I wrote up five project-type templates with the specific rules for each stack at builtbyzac.com/survival-kit.html.