面向人工智能编程代理的指导文件需要持续审查，而不是无限扩展。模型每犯一次错误，就新增一条规则；工具每发生一次变化，就新增一种变通方法；而旧模型的指导在更新模型出现后仍然保留。最终，文件可能同时包含开发者设置指南、风格指南、故障排查记录，以及一组过时的提示词编写方法。
本文指出，这种累积可能使编程代理的效率降低。现代模型越来越能够探索代码库、识别常见框架、遵循现有模式并处理常见错误。但它们不知道团队特有的决策、隐藏的约束或团队内部积累的运行经验。因此，目标并不是让指导文件尽可能短，而是保留真正会改变结果的、最小的一组高信号信息。
将上下文视为有限资源
指导文件会在每个适用的请求中加入模型可用的上下文，其各行内容会与开发者的任务、相关代码、工具输出、对话记录和其他指令争夺模型的注意力。上下文窗口变大，并不意味着每增加一个符号都没有成本。
实际问题不是：可以向模型介绍代码库的哪些内容？而是：模型需要知道哪些内容，却无法可靠地发现、推断或检索？本文建议重点关注具体、有影响且难以推断的信息。
文件中应保留哪些内容？
价值最高的信息包括系统中不明显的事实，例如代码库组件之间的所有权边界、某个旧目录仍在生产环境中使用，或某些文件是生成的、不得手动修改。与其让模型从目录名称中推断这些边界，不如明确说明某个接口负责公共 HTTP 合约，或领域规则属于某个特定层。
还应记录最短且可靠的构建与验证路径，只保留经过测试的命令。本文给出的示例包括在首次构建前运行 dotnet restore App.slnx，随后使用 dotnet build App.slnx --no-restore；在更改 API 时运行特定测试，或在修改合约后运行生成文件验证工具。还必须说明特殊要求，例如集成测试需要 Docker，且不得并行运行，因为一个被反复自信执行的错误命令比没有命令更糟糕。
记录代码无法持续自行确定的本地选择也很有用：所采用的测试框架、偏好使用 Minimal APIs 而不是控制器、使用 Result<T> 处理预期的领域错误，或使用 TimeProvider 而不是直接调用系统时钟。这些不是通用编程规则，而是代码库特有的决策，因此适合写入指导文件。
至于严格约束，应将“始终”“绝不”和“必须”等词保留给真正绝对的规则，例如保持公共 JSON 合约、不得将客户数据写入日志、数据库迁移必须与上一版本兼容，或禁止在没有明确部署任务的情况下修改生产环境文件。还可以指向事实来源，而不是复制其内容，例如接口设计指导文件、运行时环境版本定义文件、部署文档和架构决策记录。
哪些内容可以删除或移动？
本文建议删除诸如编写整洁代码、遵循最佳实践、使用有意义的名称以及适当处理错误等一般性建议。这些表述无法决定实际行动，而具体的本地规则更有用；例如，使用现有的 ProblemDetails 工具，将验证错误关联到 400 响应，将不存在的资源关联到 404 响应，并将并发冲突关联到 409 响应。
文件通常不需要完整的目录清单，因为模型能够快速读取代码库结构。同样，也不必重复工具强制执行的格式规则，只需说明适用的验证命令，例如 dotnet format --verify-no-changes。还应避免完整复制 README、架构指南和贡献指南，以免提高维护成本，或造成文档之间的不一致。
本文还警告不要使用过时的“提示词神话”，例如要求模型深呼吸、扮演高级工程师，或在进行任何更改前读取每个文件。这些表述不会增加项目知识，反而可能导致不必要的探索。更好的做法是描述所需结果、约束和验证要求：进行解决根本原因的最小更改，保持公共行为，并运行目标测试。
临时解决方案应在引发它的问题修复后删除。否则，代理会继续避开已经不再损坏的路径。还应让指导内容适用于某一类模型，而不是某个具体版本；随着模型及其行为变化，分支到每个模型专用路径的指令会变得脆弱。
选择指导范围并进行审查
并非每条指导都适合放在通用代码库文件中。GitHub Copilot 支持位于 .github/copilot-instructions.md 的通用指导、位于 .github/instructions/ 下的路径专用文件，以及 AGENTS.md 等代理指导文件。当通用指导文件和匹配的路径专用文件同时存在时，会一并使用。
系统架构、共享命令和通用约束应放在通用范围内；特定部分的框架规则、测试模式和生成文件规则则应移至路径文件。详细说明、决策历史和罕见流程最好保留在相关文档中。这样，在执行数据库迁移任务时，模型就不会被 React 组件测试规则占用注意力。
本文建议根据四种结果审查每条指导：如果内容正确、有影响且难以推断，则保留；如果模型已经知道、工具会强制执行、内容已变得模糊或已经过时，则删除；如果内容有用但属于其他路径或文档，则移动；如果内容涉及某条命令、临时解决方案或可能已经改变的版本，则验证。
适合进行审查的时机包括采用能力更强的模型、改变构建系统、重组代码库，或发现代理忽略指导或错误应用指导。之后，应在特定任务上测试更精简的文件，记录实际失败情况，加入防止其重复发生的最少指导，然后在另一项任务上重新测试。
作为项目维护的一部分
本文倡导在常规拉取请求中审查指导文件的更改，并询问审查者该规则是否可复用，还是只处理单个任务；同时为操作命令和环境要求指定负责人。还应在处理问题根因的同一个拉取请求中删除临时解决方案，并在 SDK 包、框架、测试工具或构建路径更新后重新检查相关命令。
不应以行数来衡量文件的质量。一个包含错误指令的 30 行文件，可能比一个描述多项目代码库边界以及模型无法推断的信息的 100 行文件更糟糕。更好的标准是：文件应让有能力的模型能够快速开始工作，为其提供只有团队才知道的信息：系统是什么、重要边界、本地选择、构建与验证方式、不可破坏的内容，以及在哪里可以找到更深入的细节。