最近看到一个关于 AI 编程全局记忆文件的讨论：项目里使用 Claude.md、AGENTS.md 这类文件之后，效果不一定会变好，甚至可能让成功率下降，同时推理成本还会上升。

这件事乍一看有点反直觉。我们通常会觉得，给 AI 更多项目背景、更多规则、更多说明，它应该更容易写对代码。
但实际问题在于：Claude.md 不是普通文档，而是每次对话都会被塞进上下文的全局记忆。它写得越多，模型每次都要读得越多；它写得越含糊，模型每次都要多做判断；它写进了不该写的流程，模型还可能在不相关的任务里触发多余动作。

所以，Claude.md 真正难写的地方，不是怎么把内容写全，而是怎么判断哪些内容值得长期占用上下文。

Claude.md 到底是什么

在 AI 编程工具里，Claude.md、AGENTS.md 这类文件本质上都是全局记忆文件。

普通对话会进入上下文，但上下文长度有限。对话长了以后，历史内容会被压缩，部分细节会丢失。全局记忆文件的作用，是把一些重要规则固定下来，让模型在每次任务开始时都能看到。

这意味着两件事：

• 写进去的内容更不容易被遗忘
• 写进去的内容也会在每次任务里产生成本

它不像一份 README，只在需要时被阅读。它更像一套长期有效的工作约束。只要放进去，就默认每次都会影响模型的判断。

因此，Claude.md 不是项目介绍，也不是经验合集，更不是把所有开发流程都塞进去的地方。它应该只存放那些模型如果不知道，就容易反复犯错的规则。

为什么写了反而可能变差

全局记忆文件写得不好，主要会带来三类问题。

第一，它会占用上下文。

如果 Claude.md 有一千行，那么这些内容会长期进入模型上下文。真正与当前任务有关的代码、错误信息、需求说明，反而会被挤压。上下文不是免费的空间，越大的全局规则，越容易稀释当前任务的重点。

第二，它会触发多余行为。

比如在全局文件里写：

1
2

每次开始任务前，都要完整阅读项目目录。
每次修改后，都要执行完整链路测试。

这些话看起来很负责，但放在全局记忆里就会变成“所有任务都默认执行”。哪怕只是改一行文案，模型也可能因为这条规则去做不必要的探索和测试。结果就是任务变慢、成本变高，甚至引入新的干扰。

第三，它会增加判断负担。

像“保持代码优雅、简洁、可维护、可扩展”这类话，听起来正确，但实际约束很弱。模型每次生成代码时都要判断什么叫优雅、什么叫可扩展，却没有得到明确边界。

更好的写法不是堆抽象美德，而是写具体禁令或反例。比如：

1
2
3

不要为了单个调用点新增通用抽象。
不要在没有测试覆盖的情况下改动共享解析逻辑。
不要把临时脚本放进业务源码目录。

这些规则更具体，也更容易被执行。

应该写什么

判断一条内容要不要写进 Claude.md，可以用一个简单标准：

如果不写，AI 就会反复犯同一种错误，那它值得写进去。

适合写进全局记忆文件的内容，通常有这些特点：

• 长期有效
• 与当前仓库强相关
• 无法从代码结构自然推断
• 能明确改变模型行为
• 最好是约束、禁令、路径规则或固定命令

比如：

1
2
3
4

所有 Hugo 文章只改 index.zh-cn.md，不自动生成其他语言版本。
文章 front matter 必须包含 title/date/draft/tags/categories/slug/description。
不要修改 public/ 目录里的构建产物。
PowerShell 下执行部署时使用 scripts/deploy.ps1。

这些内容不是泛泛而谈，而是和仓库的真实工作方式绑定。模型如果不知道，就可能做错；模型知道以后，确实能减少误操作。

不该写什么

很多人容易把 Claude.md 写成项目说明书，这通常没有必要。

不太适合写进去的内容包括：

• 项目愿景和背景介绍
• 大段目录结构说明
• 临时任务计划
• 一次性的调试步骤
• 抽象的代码审美要求
• 只在少数情况下才需要执行的长流程

比如“这是一个电商项目，包含商品、订单、用户模块”这种描述，对模型完成具体编码任务帮助有限。真正开发时，模型应该根据当前需求、规格文档、代码结构和测试来判断，而不是靠全局记忆里的粗略介绍。

目录结构也是类似。除非某个目录有特殊约定，比如“共享组件只能从这个目录引用”，否则没必要把整个树形结构写进去。模型可以自己读取项目目录，硬塞一份静态目录说明反而容易过期。

流程更适合做成技能或命令

如果一段内容是“第一步做什么、第二步做什么、第三步做什么”，它未必适合放进 Claude.md。

长期流程可以沉淀成技能、脚本或命令。这样做的好处是：全局记忆里只需要保留名称和触发条件，真正的详细步骤只在需要时加载。

比如：

1
2

当用户要求翻译 Hugo 文章时，使用 post-translate 技能。
当用户要求部署站点时，运行 hugo-rsync-deploy 流程。

这比把完整翻译流程、部署流程都写进 Claude.md 更轻。全局记忆保持短，具体流程交给可触发的工具。

Claude 最近的初始化流程也在往这个方向走：不只是生成一个 Claude.md，还会尝试把可复用流程拆成 skills，把固定事件拆成 hooks。这个变化背后的思路很清楚：全局记忆只做入口，细节按需加载。

Claude.md 需要持续迭代

Claude.md 不应该一次写完就不管。

更合理的方式是先保持简短，让模型在真实任务里暴露问题。某个错误出现一次，可以先人工处理；如果同类错误出现两次以上，就说明它可能值得沉淀为全局规则。

这类迭代比一开始写一大堆规则更有效。因为一开始你不知道哪些规则真的有用，也不知道哪些内容会变成噪音。随着项目变大、协作变多、模型行为逐渐稳定，再慢慢把高频问题写进去。

还有一个重要趋势：模型越强，全局记忆文件反而应该越短。

以前很多需要写进提示词的要求，现在模型已经能自然做到。继续把这些基础要求塞进 Claude.md，只会增加上下文负担。全局记忆应该随着模型能力提升而收缩，只保留这个仓库独有、模型无法自动推断的部分。

一个更实用的写法

写 Claude.md 时，可以按这个顺序思考：

1. 这个仓库有什么特殊约定？
2. 哪些错误模型已经犯过不止一次？
3. 哪些目录、文件或命令绝对不能误用？
4. 哪些流程应该改成技能、脚本或命令，而不是常驻上下文？
5. 哪些内容只是介绍，可以删掉？

最后得到的文件，可能只有几十行。它不需要完整解释项目，而是要精确约束行为。

一个好的 Claude.md，应该像这样：

1
2
3
4
5
6
7

# 工作规则

- 只改与当前任务相关的文件。
- 不要修改 public/、resources/ 这类构建产物目录。
- Hugo 文章改写只处理 index.zh-cn.md，不生成其他语言版本。
- 如果涉及部署，先运行 hugo 构建，再执行既有 rsync 脚本。
- 遇到已有用户改动时，不要回滚，必须基于现状继续修改。

它短，但每一条都能影响实际行为。这样的内容才值得长期占用上下文。

最后一句

Claude.md 的价值不在于让 AI “知道更多”，而在于让 AI “少犯固定错误”。

它不是知识库，也不是项目百科，而是 AI 编程过程里的长期约束文件。
写得越具体、越短、越贴近真实错误，它越有用；写得越泛、越长、越像项目介绍，它越可能拖慢模型，甚至让结果变差。

把全局记忆当成稀缺资源，而不是无限草稿纸。这大概就是写好 Claude.md 最重要的一条原则。