如何管理代码库中的上下文文件，让AI编码代理输出更优质的结果
内容提要
该文章介绍如何为AI编码代理管理上下文文件，以解决代理因不了解代码库约定而生成不合规代码的问题。核心方法是采用三层结构：根文件（AGENTS.md）始终加载且精简，目录级文件按需加载，文档通过路径引用。文章强调用脚本同步各工具格式，并通过linter验证文件准确性，确保上下文文件不随时间腐化。
延伸解读
上下文文件的核心是预算分配
文章强调，上下文窗口是有限的，而上下文文件是预算分配问题。每增加一行内容，都会与其他信息竞争有限的注意力，导致“上下文腐烂”。因此，编写上下文文件时，应优先考虑精简，只保留那些删除后会导致代理犯错的信息。
三层结构：按需加载，避免浪费
文章提出三层结构：始终加载的根文件、按目录加载的嵌套文件、按需引用的文档。这种设计模仿新工程师的工作方式，先记住文档存在，需要时再查阅。这样既能保证代理获得必要信息，又不会占用过多上下文窗口。
可验证性：防止上下文文件腐化
上下文文件会像文档一样腐化，因为错误不会导致失败。文章建议通过linter检查文件中的路径和脚本是否存在，并在CI中运行，确保文件始终与代码库同步。一个可验证的普通文件，胜过描述过时架构的漂亮文件。
定义完成标准，让代理自我验证
在上下文文件中明确“完成定义”，例如运行测试和linter，并要求代理粘贴输出，可以让代理自主验证工作，减少人工干预。对于必须执行的操作，使用hook强制运行，而不是依赖代理遵循建议。
Q&A
为什么AI编码代理会生成不符合代码库约定的代码？
因为代理不了解代码库的具体约定，这些约定通常存在于团队成员的头脑、代码审查评论和未记录的旧决策中。代理只能依赖训练数据中的平均模式，因此可能使用错误的库、测试框架或架构模式。
管理上下文文件的三层结构是什么？
三层结构包括：始终加载层（根文件如AGENTS.md，精简且每次会话加载）、作用域层（嵌套文件，仅在特定目录工作时加载）、按需加载层（通过路径引用的文档，仅在需要时加载）。
如何避免为不同AI工具维护多份上下文文件？
以AGENTS.md为唯一事实来源，通过脚本生成其他工具所需的文件（如CLAUDE.md、.github/copilot-instructions.md），并在生成的文件中添加横幅提示不要直接编辑。对于工具特有的功能（如Cursor的glob作用域），可以单独手写。
编写根文件AGENTS.md时，如何判断哪些内容该写？
使用删除测试：如果删除某行不会导致代理犯错，就删掉。应包含代理无法猜测的命令、与语言默认不同的约定、测试运行器、架构决策等；应排除代码中可见的内容、标准约定、详细API文档、频繁变化的信息等。
如何防止上下文文件过时？
通过linter检查上下文文件，验证路径存在、npm脚本存在、token预算不超限，并在CI中运行linter。同时，使用同步脚本确保生成的文件与源文件一致。
什么是上下文腐化？它如何影响AI代理？
上下文腐化是指随着上下文窗口中的token数量增加，模型检索特定指令的能力下降。这会导致代理忽略规则，尤其是在文件过长时。因此，上下文文件应精简，避免臃肿。
如何验证上下文文件是否有效？
可以进行对比实验：在相同任务下，分别在有和没有上下文文件的分支上运行代理，比较测试通过率、需要的纠正次数、代码是否符合分层、是否引入新依赖。
有哪些常见的上下文文件编写错误？
常见错误包括：厨房水槽文件（内容过多）、重复README、记录模型可见的内容、编写无法验证的规则（如“写干净代码”）、各工具维护独立副本导致不一致。
