写给 AI 编程助手看的项目说明书，应该怎么写？

基于 Vince 聊开发在 X 长文《写好 CLAUDE.md 的 8 条经验：让 Claude Code 更懂你的项目》整理。

>

- 原文：https://x.com/vincemask/status/2052368318825402507

- 作者：Vince 聊开发

- 发布时间：2026-05-07

- 提取方式：gallery-dl + X public GraphQL TweetResultByRestId

- 本文性质：分享文章。以下为基于原文观点的整理与转述，不是逐段翻译，也不代表原作者逐字表述。

很多人第一次用 Claude Code，会自然地把 CLAUDE.md 当成一个“超级说明书”：项目背景、历史决策、团队偏好、架构说明、个人习惯，全部塞进去。

问题也往往从这里开始。

当一个文件变成几千行上下文时，AI 并不会因此更懂项目。相反，它更容易迷失：真正重要的边界被稀释，具体规则被淹没，最后生成的代码看似合理，却偏离项目实际。

这篇文章的核心提醒是：CLAUDE.md 不是知识库，而是 AI 进入项目时的导航页和护栏。

1. 越短越好：把 CLAUDE.md 控制在 200 行以内

原文引用了 claude-code-best-practice 作者 Boris Cherny 的建议：CLAUDE.md 不要超过 200 行。

这条建议背后的逻辑很简单：Claude Code 每次会话都会加载 CLAUDE.md。你写进去的每一行，都会占用上下文窗口。信息越多，不等于模型越聪明；很多时候只是让它更难判断什么最重要。

一个实用检验标准是：一个没接触过项目的人，读完 CLAUDE.md 后，能不能在 30 秒内回答三个问题：

1. 这是什么产品？
2. 技术栈是什么？
3. 新代码应该放在哪里？

如果回答不了，说明文件不是太短，而是没有聚焦。

2. 不只写“用什么”，还要写“不要用什么”

很多项目说明只写技术栈，例如使用 React、FastAPI、PostgreSQL。问题是，AI 不知道项目背后的历史包袱，也不知道哪些方案曾经被团队明确放弃。

如果没有禁止清单，Claude 可能会出于“帮你优化”的好意，引入它认为更现代、更常见的库或架构。但这些选择可能与当前项目完全冲突，甚至制造后续多轮修复成本。

所以，CLAUDE.md 里应该有一个明确的 Do NOT introduce 区块，写清楚不要引入哪些库、框架、模式或工程做法。

这类规则的价值，不是少解释一次，而是防止 AI 在你没注意时悄悄改变项目方向。

3. 规则要能判断，不能只表达感受

“写干净的代码”对人类有意义，但对 AI 来说太模糊。

AI 更适合执行具体规则，例如：

• 使用 named export，不使用 default export。
• 单个组件不超过 200 行。
• 异步逻辑使用 async/await，不使用 then 链。
• 新增 API 必须补测试。

判断一条规则是否合格，可以用一个简单标准：读完后，能不能在 5 秒内判断一段代码是否符合它？

能判断，就是好规则。不能判断，就需要继续改写。

4. CLAUDE.md 应该是 router，不是图书馆

很多人会想把所有架构文档、历史决策、接口说明都放进 CLAUDE.md。这样做看似完整，实际会让入口文件变得臃肿。

更好的方式是让 CLAUDE.md 成为“文档路由器”：

• 需要理解架构时，去读 docs/architecture.md。
• 需要了解 API 约定时，去读 docs/api.md。
• 需要修改部署逻辑时，先读 infra/README.md。

这样做的好处是渐进式上下文加载：AI 不会在无关任务中浪费上下文，但在真正需要时知道该去哪里找资料。

普通用户把 CLAUDE.md 写成知识整理；高阶用户把它写成导航系统。

5. 高风险目录需要本地 CLAUDE.md

项目里不是所有目录风险都一样。

认证、支付、账单、基础设施这类模块，往往比普通业务页面更敏感。原文建议在这些目录下放本地 CLAUDE.md，例如：

• src/auth/
• src/payments/
• infra/

当 Claude Code 操作这些目录时，会加载更具体的局部规则。这样就像给危险区域加了护栏：普通目录可以轻量协作，敏感目录必须遵守更严格边界。

6. 重要规则不要只靠模型记忆，要变成 Hook

很多人会在 CLAUDE.md 里写：“修改代码后请运行测试。”

但 AI 会忘。尤其在长任务、多文件修改、上下文变复杂时，它很容易跳过验证步骤。

原文的观点是：真正重要的规则，应该通过 Hook 变成强制执行层。

写在 CLAUDE.md 里的规则是“请记住”；变成 Hook 后，才是“必须执行”。

这也是 AI 编程助手从“聊天协作”走向“工程流程”的关键一步：规则不能只存在于文本里，还要进入工具链。

7. 用 MEMORY.md 建立简单可控的长期记忆

跨会话失忆是 AI 编程助手的常见问题。很多人会想到复杂的向量数据库、记忆系统或 MCP。

原文给出的方案更朴素：让 Claude 自己维护一个 MEMORY.md。

这个文件只记录跨会话最有价值的信息，例如反复踩过的坑、稳定项目约定、长期有效的工程偏好。它的优势是简单、可控、可被 Git 追踪。

这不是把所有历史都保存下来，而是把最关键的 5% 留住。

8. 用 CLAUDE.md 替代每次会话的开场白

每次新会话都重复告诉 AI “你要怎么帮我”“我讨厌什么”“这个项目不要怎么做”，本质上是在人工补上下文。

更好的做法是把这些长期偏好写进 CLAUDE.md：

• 你期望它先计划还是直接动手。
• 哪些改法需要先确认。
• 哪些行为你不能接受。
• 汇报时要给什么验证证据。

这样 Claude 从第一句话开始，就能按你的工作方式进入项目。

这篇文章真正想解决的问题

这篇文章表面上讲的是 CLAUDE.md 写法，实际讲的是一个更大的问题：如何把 AI 从“聪明的临时助手”变成“受约束的工程协作者”。

关键不在于让 AI 读更多材料，而在于让它更快识别边界：

• 什么是项目目标？
• 什么技术可以用？
• 什么技术不能用？
• 哪些目录高风险？
• 修改后如何验证？
• 长期经验沉淀在哪里？

如果这些问题没有写清楚，AI 会用自己的默认经验补空白。而工程项目里，最危险的往往就是这些“看起来合理的默认值”。

可以马上做的四件事

如果你已经在项目里使用 Claude Code，可以从这四步开始：

1. 删减 CLAUDE.md：把它压缩到 200 行以内，只保留高频、稳定、真正影响行为的内容。
2. 增加禁止清单：明确写出不能引入的框架、库、架构模式和危险操作。
3. 改写模糊规则：把“写好代码”“注意质量”改成可以快速判断的具体规则。
4. 给敏感目录加局部规则：从认证、支付、基础设施、数据库迁移等高风险区域开始。

结语

CLAUDE.md 不是一次性写完的文件。它应该随着项目和团队经验不断演化。

每当 Claude 反复犯同一个错，每当你发现一条有效约束，每当某个模块暴露出特殊风险，都应该回到 CLAUDE.md 或局部说明文件里更新规则。

真正有价值的 CLAUDE.md，不是把项目解释得无比完整，而是让 AI 在最短时间内知道：该做什么、不要做什么、遇到不确定时去哪找答案，以及改完以后如何证明自己没有搞坏项目。

这才是 AI 编程协作里最值得沉淀的那部分上下文。