How CLAUDE.md actually works

Most engineers write CLAUDE.md like a README. They put their stack, a few preferences, maybe a note about testing. The agent reads it and proceeds to write code shaped by its training data rather than their codebase. The file exists. It doesn't do much. The problem is category. A README describes a project. A specification constrains behavior. This post covers three dimensions of getting it right: how to structure the file across a real directory hierarchy, how to write rules the agent actually follows instead of weighs, and how to keep the file current as the codebase evolves.