原文名称是[Writing a good CLAUDE.md]，一位外国博主写的一篇关于如何写好CLAUDE.md的文章，我这里翻译为[如何写好项目规则]，因为这篇文章同样适用于Cursor等AI IDE的 project rules 编写。文章没有完全直译，而是按照我的理解做的本土化意译。

一、大模型（LLMS）是无状态的

大模型是无状态并且有上下文限制的，每次调用大模型，他对我们的项目都是一无所知的，想让大模型理解我们的代码库，需要我们给他提供信息。AI IDE 或者 agent 也是一样的道理，每次打开一个会话我们都需要给他提供一份代码库的信息，才能让大模型更好的理解我们的代码，给出符合场景的预测。

所以，在实践的时候，我们可以总结为以下三点：

  • Coding Agent 在每次开启会话时，对我们的项目代码是一无所知的。
  • 每次使用 Coding Agent 之前，我们都需要给他提供一份项目信息，这份项目信息需要包含项目的一些关键信息，比如技术栈，架构等。
  • 规则文档比如 Claude.md 或者 Cursor 的 rules 可以很完美的帮我们解决这个问题。

二、项目规则需要包含哪些内容

这里我们用经典的三W回答这个问题

1.是什么(What)

告诉大模型我们的项目是什么，基本信息应该包含：技术栈、项目架构等，有了这些信息，大模型可以对我们的项目有个大致了解，当我们跟他说要改什么模块时，他可以有路径可循，而不是瞎子摸象。

2.为什么(Why)

告诉大模型我们的项目是做什么的，哪些模块负责哪些逻辑，比如说我们有一个项目管理系统，这个项目管理系统是以工作项为基础的，然后还有配套的工作项详情，工作项新建等大的复用率高的模块，这些信息可以提供给大模型，让他对我们的业务有一定的了解。

3.怎么做(How)

约束大模型的行为，描述我们使用 Coding Agent 时需要做哪些工作，不需要他做哪些，比如我们可能不希望他去阅读一些配置文件或者修改 md 文件。

此外，记住不要试图把各种奇怪的信息都塞到项目规则文件，并不是说信息越多越好，太多不相关信息会让大模型吐出的结果更差，Claude 经常会忽略给他的上下文信息，因为他内部加了一条规则，若是与当前任务相关性不大的上下文，就忽略，目的是为了提高模型输出内容的质量。

三、如何写好项目规则

下面列举一些如何写好项目规则的守则，大模型在不断进化，我们的使用场景也各种各样，这些守则并不一定各种场合一直适用，大家可以根据环境的变化或者自己的使用场景调整策略。

1.宁缺毋滥

我们可能会想，既然大模型不懂我们的项目，我们就把整个项目文档都塞到项目规则里就好了，上面也提到了，信息并不是越多越好，下面是研究显示的一些内容，也许可以帮我们破除这种误解。

  • 前沿思考型大模型（Frontier thinking LLMs）能够处理的上下文边界是150-200条指令，更小的模型能处理的指令数甚至更少，非思考型大模型上下文边界小于思考型大模型

  • 较小的模型性能下降得非常快、非常严重。具体来说，随着指令数量增加，较小模型的指令遵循能力呈现指数级衰退，而前沿思考型大模型则表现为线性衰退。因此，建议尽量不要使用较小模型执行多步骤任务或复杂的计划。

  • 大模型对提示词中位于边缘位置的指令存在明显偏好：即最开头部分（Claude Code 的系统提示和 CLAUDE.md/上下文规则文件），以及最末尾部分（最近的用户消息）

  • 随着提示词总数增加，提示词遵循质量会均匀的下降。这意味着当我们试图给模型更多提示词时，它并不是简单地忽略最新的提示词，而是开始均匀地忽略所有提示词。

对 Claude Code 框架的分析显示，其系统提示中已包含约50条内部指令。根据我们使用的模型不同，这已经占到智能体能够可靠遵循指令总数的三分之一左右——而且这还不包括后续的规则、插件、技能或用户消息。

通过上面的分析，我们可知，项目规则文件应尽可能少地包含指令——理想情况下，只保留那些对当前任务普遍适用的核心内容。

2.项目规则文件的长度和适用性

大模型在上下文包含任务相关信息、工具等内容时，表现会比非相关信息上下的情况下更优。所以在写项目规则时，尽量写得适用性高一点，避免写过于具体的内容，可能会降低大模型输出的内容质量。

项目规则的内容简洁，一般小于 300 行，尽量短一点能把信息描述清楚，效果会更好。

3.规则渐进

要把我们的项目信息在一份文档里描述清楚很难，特别是还要限制上下文的情况下。我们可以分模块去写适用不同模块的规则，在特定模块下才使用该规则，比如使用 Cursor 我们可能会有一个项目规则文件夹，每个规则文件可以设置在什么情况下适用。但是记得不要把具体代码内容或者函数写进去，因为我们经常改动，很快就会过时，尽量描述一些确定性的内容。

4.不要试图让大模型做代码风格相关的工作

大模型消耗 token 目前来看还是很昂贵的，我们可以用格式化插件去做代码风格相关的工作，这样可以节省不少的成本，此外，大模型是有学习能力的，在编码过程中可以了解我们的代码风格，在输出时也会模仿我们的风格输出，所以没必要把代码风格相关的规则放到项目文档。

5.不要使用自动生成项目规则或者是相关模板

项目规则作为顶层上下文，将影响到我们每次的 AI 交互，如果说项目规则质量不好的话，大模型输出的内容质量可能也会不好，影响到我们的编码体验。

参考文献：

Writing a good CLAUDE.md