我用 AI 编程助手做项目时，经常会临时补一句：“这个仓库先不要跑测试，改完告诉我哪些地方还没验。”

这句话能解决眼前的问题，也暴露了一个更长期的问题：如果同一类提醒每次都要重说，项目里就缺一份稳定的协作说明。

多仓库项目尤其容易说含糊。比如 CupCheck 的接口、小程序和管理后台各自是独立仓库，父目录还放着项目文档。只说“把这个功能做好”，助手就得猜：该进哪个仓库？接口能不能改？这次允许做哪些检查？最后要交代什么？

猜对功能不等于完成得可靠。改动可能落在错误目录，静态检查也可能被说成“功能已经验证”。对我来说，项目说明最值得写清楚的不是态度，而是协作边界。

先说清楚，这次改哪里

“修一下保存按钮”听起来明确，落到代码上却可能涉及小程序、后台页面和接口。保存流程是否要改请求参数？按钮旁边的图片选择逻辑要不要保留？如果没有边界，助手只能从上下文推测。

路径和限制直接写出来会更省事：

这次只改 MiniAPP 的记录编辑页。接口参数保持不变，管理后台不调整。保留现有图片选择和提交流程。

这几句分别交代了改动位置、不能动的部分和必须保留的行为。它们比“请谨慎修改”具体，因为可以在最终 diff 里逐项核对。

多仓库说明还可以把父目录资料和代码仓库区分开。不要只写“前端”或“接口”，直接写目录名或仓库路径；如果某个子目录只放文档，也标明它不是本次代码修改目标。

这样做不是为了给助手增加流程，而是为了让它先确认位置，再动手。改错仓库，后面代码写得再漂亮也得返工。

把“检查一下”拆成允许执行的动作

“改完检查一下”可能指看 diff，也可能指运行测试、构建、启动服务、连数据库，甚至打开微信开发者工具。它们的耗时和影响差别很大，不该让一句模糊要求替你做决定。

如果这次只希望助手做静态检查，可以把范围写明：

默认只对改动文件做基本静态检查。不要主动运行自动化测试、构建、服务、数据库或微信开发者工具。完成后列出实际做过的检查，并说明尚未验证的部分。

这里表达的是当前协作怎么分工，不是说测试不重要。代码改动和有限的静态检查可以先交给助手；页面表现、设备行为、数据库及外部服务，我再按项目情况验收。

同样重要的是，不要把未知命令写成事实。如果项目里没有明确的检查命令，说明“尚未确定”，比猜一个命令并声称它是标准流程靠谱得多。

交付时，把三种状态分开

“完成了”通常不够。它没告诉我助手改了哪些文件、实际做了什么检查，也没说页面是否在设备上跑过。

我会把状态分成三层：代码已改、约定的静态检查已做、真实环境功能已验收。每一层都需要自己的证据，不能从前一层自动推断后一层。

所以交付说明至少应包含：改动文件、执行过的检查及结果、没有执行或没有验证的项目。如果涉及多个仓库，就分仓库说明。没有明确要求时，也可以写清楚不要提交或推送。

这会让验收变简单：我能先检查改动是否落在允许范围，再决定接下来要不要自己跑测试、看页面或连服务。

一段可以直接改的项目约定

项目说明不必一上来就写成手册。可以先把重复出现的提醒压成一小段，放在 Codex 能读取的项目说明文件里，再按自己的目录和流程调整：

# 项目协作约定  ## 仓库与范围 - 本项目包含 API、MiniAPP、Admin 三个独立仓库；父目录中的 docs/ 仅存放项目文档。 - 开始修改前先确认当前仓库和目标路径；不确定时先说明，不跨仓库修改。 - 只修改任务明确指定的仓库和路径。接口、后台及相邻功能不在范围内时保持不动。  ## 执行边界 - 默认检查改动文件和 diff。 - 未经本次任务明确要求，不运行自动化测试、构建、服务、数据库或设备工具。 - 不确定的检查命令标记为“未确定”，不要猜测或声称已执行。  ## 交付说明 - 列出改动文件、实际执行的检查及结果、尚未验证的事项。 - 多个仓库分别报告状态。 - 未经明确要求，不提交、不推送。

这只是一个起点。比如团队已经明确要求每次运行某条 lint 命令，就把确切命令和适用范围补上；如果不同仓库的流程不同，也分别写，不要用一句“运行项目检查”带过。

说明写短一点，关键处写具体

项目说明很容易越攒越长：碰到一次问题加一句，再碰到一次再加一段。最后真正有用的边界被埋在重复规则里，维护的人和助手都难找。

我更愿意只保留会改变实际操作的内容：有哪些仓库、各自负责什么、哪些路径允许动、默认允许做哪些检查、交付时要提供什么证据。具体需求和验收条件则写在任务里。

Codex 的官方迭代开发工作流也把项目目标、编码约定、测试标准、相关背景和范围边界列为 AGENTS.md 可包含的内容；同时要求验收条件可观察，未知命令或要求应标为未解决，而不是凭空补出来。原文链接

我会从最近最常返工的地方开始写：是不是总要指定仓库？是不是总要提醒别跑某些工具？是不是经常要补一句“还没有真机验收”？先把这些重复提醒变成明确规则，拿一条真实任务试用；出现新的歧义，再调整。

项目说明不能保证助手永远不出错，但它能让错误更容易被发现：是范围越界、执行超限，还是把检查结果说过了头。边界说清楚，双方才知道代码交到哪一步，下一步该由谁来验。

参考：Iterating Development Workflows with Codex。文中 AGENTS.md 示例为结合多仓库协作场景整理的示例条款，不是 Codex 官方模板。