Writing a Good Claude.md
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…
