Writing a Good Claude.md

Summary

Note: this post is also applicable to AGENTS.md, the open-source equivalent of CLAUDE.md for agents and harnesses like OpenCode, Zed, Cursor and Codex. ## Principle: LLMs are (mostly) stateless LLMs are stateless functions. Their weights are frozen by the time they're used for inference, so they don't learn over time. The only thing that the model knows about your codebase is the tokens you put into it. Similarly, coding agent harnesses such as Claude Code usually require you to manage agents' memory explicitly. CLAUDE.md (or AGENTS.md) is the only file that by default goes into every single conversation you have with the agent. This has three important implications: Coding agents know absolutely nothing about your codebase at the beginning of each session. The agent must be told anything that's important to know about your codebase each time you start a session. CLAUDE.md is the preferred way of doing this. ## CLAUDE.md onboards Claude to your codebase Since Claude doesn't know anything about your codebase at the beginning of each session, you should use CLAUDE.md to onboard Claude into your codebase. At a high level, this means it should cover: WHAT: tell Claude about the tech, your stack, the project structure. Give Claude a map of the codebase. This is especially important in monorepos! Tell Claude what the apps are, what the shared packages are, and what everything is for so that it knows where to look for things WHY: tell Claude the purpose of the project and what everything is doing in the repository. What are the purpose and function of the different parts of the project? HOW: tell Claude how it should work on the project. For example, do you use bun instead of node? You want to include all the information it needs to actually do meaningful work on the project. How can Claude verify Claude's changes? How can it run tests, typechecks, and compilation steps? But the way you do this is important! Don't try to stuff every command Claude could possibly need to ru...