编写一个好的 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.

注意：这篇文章也适用于 AGENTS.md，它是 CLAUDE.md 的开源等价物，用于像 OpenCode、Zed、Cursor 和 Codex 这样的代理和框架。

## Principle: LLMs are (mostly) stateless

## 原则：LLM（基本上）是无状态的

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.

LLM 是无状态函数。它们的权重在用于推理时已被冻结，因此它们不会随着时间学习。模型唯一知道你代码库的内容是你输入给它的令牌。

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.

同样，像 Claude Code 这样的编码代理框架通常要求你显式管理代理的内存。CLAUDE.md（或 AGENTS.md）是默认情况下进入你与代理 每一个对话 的唯一文件。

This has three important implications:

这有三个重要含义：

1. Coding agents know absolutely nothing about your codebase at the beginning of each session.
2. 编码代理在每个会话开始时对您的代码库一无所知。
3. The agent must be told anything that's important to know about your codebase each time you start a session.
4. 代理必须在每次启动会话时被告知关于您的代码库的任何重要信息。
5. CLAUDE.md is the preferred way of doing this.
6. CLAUDE.md 是这样做首选的方式。

## CLAUDE.md onboards Claude to your codebase

## CLAUDE.md 将 Claude 引入你的代码库

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:

由于 Claude 在每个会话开始时对你的代码库一无所知，你应该使用 CLAUDE.md 将 Claude 引入你的代码库。从高层来看，这意味着它应该涵盖：

• 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
• WHAT：告诉 Claude 关于技术、您的技术栈、项目结构。给 Claude 一个代码库的地图。这在 monorepos 中尤其重要！告诉 Claude 应用程序是什么、共享包是什么，以及一切的用途，以便它知道在哪里查找东西
• WHY: tell Claude the purpose of the project a...