AI Agent / 系统课时
建立项目协作规范
建立项目协作规范
团队把 Codex 用进真实仓库后,最容易出问题的不是“不会写代码”,而是每个人给出的约束、可执行命令和权限边界不一致。本课把这些约定固化为可审查的项目规范,让 Codex 在不同成员和不同目录中都能按同一套方式工作。
学习目标
- 用
AGENTS.md固化仓库级协作规则、常用命令和完成标准。 - 区分项目规则与 Codex 执行权限,建立保守且可落地的权限基线。
- 通过一次仓库检查验证规范是否完整、可执行、不会互相冲突。
把规范拆成项目规则与执行边界
AGENTS.md 适合写“在这个仓库里应怎样工作”:目录职责、编码约定、测试命令、文档要求和交付标准。Codex 会按目录层级读取项目指令;更深目录中的 AGENTS.md 可以为该子树补充或覆盖更上层规则,因此根文件应保持通用,局部规则放到对应子目录。:contentReference[oaicite:0]{index=0}
权限基线回答的是另一件事:Codex 能做什么。沙箱决定文件写入、网络等技术边界,审批策略决定越过边界时是否需要人工确认。团队不应把“允许执行什么”只写成一句自然语言,而应由 Codex 配置或组织级策略实际约束。:contentReference[oaicite:1]{index=1}

写出可执行的 AGENTS.md
根目录规则要短、明确、可验证。不要写“保持高质量”这类无法检查的口号,而要告诉 Codex 改动范围、必须运行的命令以及什么情况下需要停下来说明风险。
下面是一份适合 Node.js 仓库的主示例;命令名应替换为项目真实存在的脚本。
# Repository instructions
## Scope
- Work inside this repository unless the task explicitly requires otherwise.
- Do not change public APIs, database schemas, or release workflows silently.
## Commands
- Install: npm ci
- Lint: npm run lint
- Test: npm test
- Build: npm run build
## Definition of done
- Run lint and tests for affected code.
- Update documentation for user-visible behavior.
- Report commands that could not be run and the reason.
- Review the final diff for unrelated changes.这份文件的生效结果不是一段固定控制台输出,而是 Codex 在该作用域内把这些规则作为项目指令使用。验证时,应从仓库根目录发起任务,并观察它是否引用了正确命令;如果某个子目录需要不同测试方式,再在该目录增加更具体的 AGENTS.md,不要把所有例外都塞回根文件。
建立可共享的权限基线
对日常代码修改,一个常见的安全起点是允许工作区写入,但让越过沙箱边界的动作走审批。当前 Codex 可以用 approval_policy 与 sandbox_mode 表达这两层控制;受信任仓库还可以通过项目级 .codex/config.toml 提供可共享的覆盖配置。:contentReference[oaicite:2]{index=2}
# .codex/config.toml
approval_policy = "on-request"
sandbox_mode = "workspace-write"这份配置把普通工作区修改与越界操作分开处理,适合作为团队起点。不要把认证信息、个人令牌或机器专属路径提交进项目配置,也不要为了减少提示而默认切到无沙箱、无审批模式;若组织还有托管策略,应以组织限制为上限,而不是由项目自行放宽。
把常用命令变成团队共同的验收入口
规范只有能执行才有价值。提交 AGENTS.md 后,至少用仓库已有的检查命令跑一次,确认命令没有过期、脚本名称没有写错,并让“完成标准”与 CI 保持一致。
git status --short
git diff --check
npm run lint
npm test预期输出
<git status --short 在干净工作区时无输出>
<git diff --check 无格式错误时无输出>
<lint 命令退出码为 0>
<test 命令退出码为 0;具体测试日志取决于项目>如果本地命令和 CI 使用不同入口,优先统一入口,而不是在 AGENTS.md 里维护两套含义接近的流程。最终目标是:成员、Codex 和 CI 对“该跑什么、什么算完成、哪些操作必须停下确认”得到同一个答案。