How I Structure CLAUDE.md for Production Projects

If you have been using Claude Code for more than a week, you have almost certainly written a CLAUDE.md file. And if you are like most developers, your first version was not very good — mine was not, either. The file probably read something like: "This is a TypeScript project. We use Express and Prisma. Follow best practices." That is not a CLAUDE.md. That is a README. And it produces the same result as no CLAUDE.md at all, because it tells the agent about the project without telling it how to behave. This article is about the difference between those two things, and the structure I have settled on after iterating through a lot of versions. The mental model shift CLAUDE.md is not documentation. It is a behavioral contract. Documentation describes what something is. A behavioral contract specifies what an agent must do, must not do, and should do by default in the absence of other instructions. When you write "This is a TypeScript project using Prisma," you are writing documentation. The