考虑与项目代码直接相关的文档，文档中任意足够小部分的作用都至少属于这两类之一：

• 压缩代码信息，使得 Agent 可以先读代码架构，再读所需的代码。（占文档篇幅比较多）

  这样 Agent 不用一下看完所有精细代码以了解完整的信息，只需要阅读自然语言压缩后的信息 + 工作时真正需要精读的部分代码，节省 token 与上下文额度。主要内容是粒度合适的架构信息，除此之外还有需要通过代码思考推断的页面结构等产品信息。

• 补充额外约束，告诉 Agent 那些代码中没有，或者代码中有体现但难以推断设计出，而对于“开发”这件事又需要了解的意图。（占文档篇幅比较少）

  大部分情况下，这部分信息以约束的形式存在。约束一般有两种形式，一是方向性的，比如一些标准、要点。一种是强制性的，比如禁止做某事、必须按某步骤来做。

Agent 维护文档时的写入有两种，代码同步和自然语言叙述：

代码同步为主：（一些例子）

这些场景下通常不需要写入自然语言，或者只需要很少。要求 Agent 进行此类文档更新的约束一般会明确指定 Agent 需要进行的行为。

自然语言为主：（一些例子）

这些场景下以自然语言叙述为主。

本文档主要限制文档维护使用自然语言时的不正确行为，限制文档腐烂。

文档是代码的压缩，不是副本

AI 阅读的每个字都有 token 和上下文长度的成本。文档中的架构信息本质是为了让 Agent 能以更少的 token 和上下文长度了解开发代码所需的信息，而不需要查看全部代码。为此，架构信息的内容应有一定粗粒度。此外，如果架构信息包含非常细致的信息，一是可能让后续开发的 Agent 误以为一些实现是基础、不可轻易删改的架构；二是维护文档时频繁的写入也会占用更多的 token 与上下文长度。

修改后不更新文档是正常的。架构信息中就应只包含架构信息，比如核心数据链路、状态机、关键接口、组件与子系统划分、行为语义。没有特殊情况（如复杂算法等），不应包含实现细节、边缘情况处理等信息。

（正例与反例）

代码本身能做到的约束，不需要在文档中强调

Agent 常常过度防御，对于那些比较底层的架构，或者是涉及安全的架构，Agent 喜欢将安全准则、被禁止的信息流动方向重复在文档中。但实际上，代码本身往往已经起到了这个作用。当一些架构本身就限制或体现出充分约束意图，再在文档中记录等效的约束就是假严谨，实则浪费 token。

对于一段约束，如果它限制的代码能自发地充分展示这种约束意图，就是多余的。不需要再在文档中替代码强调“必须xx/不能xx”。

（正例与反例）

不要将单次指令落盘为通用约束

用户可能要求调整代码，并附带原因以让 Agent 更好地理解需求。Agent 常常误以为原因是通用的，就在文档中记录下来。但是一是未来可能不会再有相关的需求，二是用户给出的原因可能有暗含的未说出的考量，并非能简单套用。如果对所有类似的指令都记录下来且附带原因，文档会迅速膨胀。并且，如果用户下次的指令与过去记录的原因有表面冲突，Agent 可能因此举棋不定或错误理解用户的新指令。

区分指令和真正各任务通用的约束。按照指令要求执行，如有需要将结果在文档中作为信息记录，但不要将指令上升到祈使语气的通用标准，不要记录原因。除非用户明确要求你这么做（将xx写入到文档中/以后有相关需求也都按xx处理）。

改动与拒绝选择要消除过往痕迹，不作虚空强调

如果用户要求删除某个功能，或者把某个功能由A调整到B，文档中完全没必要强调“不具备xx功能”、“xx功能可以做到B，而不能做到A”。

如果 Agent 在开发过程中针对某个问题询问用户的选择，用户选择后，也完全没必要记录“暂不考虑xx”。对于被否定的选择，这个选择应像没有存在过，不应记录到文档中，不应虚空强调。后续 Agent 也不会因为文档没有写“禁止标签”，就自行做出用户未要求的举动。

上述两点的原因：一是没必要浪费文档空间进行虚空强调；二是此类表述虽然意在陈述，但可能被误认为是约束，也有可能让 Agent 因此举棋不定或错误理解用户的新指令。