How I structure CLAUDE.md for real projects

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 pro