背景与动机
CLAUDE.md 的作用可以理解为“给 Claude Code 的项目地图”。它不是普通 README，而是告诉 Agent 在这个仓库里如何工作：先读什么、不能做什么、用什么命令验证、遵循哪些编码规则。
好的项目记忆能减少重复解释；坏的项目记忆会把临时偏好变成长期噪声，让后续任务持续跑偏。
规则应该分层
项目规则可以按稳定程度分成三层：
长期稳定规则 -> 项目协作规则 -> 当前任务约束- 长期稳定规则：编码、目录、测试、提交、权限边界。
- 项目协作规则：本仓库常用命令、模块说明、内容规范。
- 当前任务约束：这次只改什么、不改什么、验收什么。
CLAUDE.md 适合放前两类，不适合放当前任务的临时判断。
CLAUDE.md 适合写什么
可以写：
- 项目技术栈和主要目录。
- 开发、测试、构建命令。
- 修改前必须阅读的规则文件。
- 文件编码、命名、格式化约定。
- 禁止操作，例如不要回滚用户改动、不要直接改生成产物。
- 高风险操作的确认要求。
示例结构：
# Project Instructions
## Required First Steps
- Read this file before changing project files.- Check `git status --short` before edits.
## Common Commands
- `pnpm check`: run Astro content and type checks.- `pnpm build`: build the site.
## Content Rules
- Markdown files must be UTF-8.- New notes live under `src/content/notes`.- Follow existing frontmatter fields.不适合写什么
不要把这些写进长期记忆：
- “这次帮我先不用测试”。
- “今天先忽略某个错误”。
- 某个 Bug 排查过程里的临时猜测。
- 一次性内容选题。
- 尚未确认的个人判断。
这些信息可以放在当前对话里，但不应该沉淀到项目规则。
记忆污染的表现
常见表现：
- Agent 每次都执行某个已经不需要的步骤。
- 新任务被旧任务的业务假设影响。
- 明明是小改动，却总被扩展成系统性重构。
- 输出风格越来越像某次临时要求，而不是项目真实风格。
遇到这种情况，要回头清理长期规则，把临时规则移出 CLAUDE.md。
CLAUDE.md 检查清单
写完后可以按这几条自查：
- 是否说明项目启动、测试、构建命令。
- 是否说明修改前必须读取哪些文件。
- 是否有“不要回滚用户改动”这类安全边界。
- 是否把一次性任务要求误写成长期规则。
- 是否存在互相冲突的规则。
- 是否能被新会话直接理解，而不依赖聊天历史。
如果一个规则只对今天这个任务有效，就不要写进 CLAUDE.md。它应该写在当前 prompt 里。
一句话总结
CLAUDE.md 应该保存稳定、可复用、项目级的协作规则，而不是保存每一次对话里的临时偏好。