Codex 团队化：怎样共享 AGENTS.md、Skills、项目规则与发布边界

这是 Codex 系列的第 16 篇。

前 15 篇基本都从个人使用者出发：怎样读项目、写 Prompt、沉淀 Skill、连接外部系统、做资料调研，再把文章审稿、配图和发布跑成一条流水线。

当这些做法开始进入团队，问题会突然变形。

个人工作流里，一句“我习惯先跑测试再改代码”可以留在自己的 Prompt；团队协作里，同一句话会变成一串更难回答的问题：

这个规则对所有目录都适用吗？
谁能修改？
怎样知道 Codex 真的读到了？
它是建议，还是必须执行的门禁？
Claude Code、GitHub Agent 和 Codex 是否共用？
规则过时以后，谁负责删除？

因此，这一篇不讨论“怎样让全员使用同一段万能 Prompt”，而是解决一个更具体的问题：

怎样把团队希望 Codex 遵守的规则、重复工作流、确定性检查和权限边界放在正确的载体里，并建立可验证、可评审、可回滚的变更过程？

贯穿全文的案例是一个常见任务：PR 就绪检查。目标不是让 Codex 自动合并代码，而是让不同成员都能得到结构一致的检查结果，同时保留 CI、维护者和安全负责人各自的权力。

下载 codex-team-governance-kit 配套包

版本说明

Codex 的配置键、权限模型和企业托管能力仍会变化。本文涉及 AGENTS.md、Skills、项目配置和 managed requirements 的描述，以 2026-07-23 的 OpenAI 官方文档为准。复制配置前，应重新核对当前客户端版本和配置参考。

一分钟概览

团队化不是增加一份更长的说明书，而是把不同性质的控制拆成五层：

图 1：Codex 团队协作的五层控制面

移动端可打开图 1 原始 SVG放大查看。

最重要的判断只有一句：

自然语言负责指导；代码与策略负责执行；人负责目标、例外和最终责任。

本文配套包把这五层分别落成文件：

codex-team-governance-kit/
├── AGENTS.template.md
├── .agents/skills/pr-readiness/SKILL.md
├── docs/codex-ownership.md
├── docs/codex-change-proposal-template.md
├── policy/requirements.toml.example
└── scripts/audit-governance.mjs

第一次阅读可以这样选：

• 想先解决团队 Prompt 不一致：看第 2、3、4 节。
• 想分清指导和强制门禁：看第 5、6 节。
• 正在设计团队推广：看第 7、9、12 节。
• 同时使用 Claude Code 或 GitHub Agent：看第 10 节。

1. 团队化的目标不是“输出一样”

两位开发者使用同一个模型、同一个 Prompt，也可能得到不同路径。原因不只来自模型随机性，还包括：

• 当前工作目录不同；
• 打开的文件和对话历史不同；
• 本地全局配置不同；
• 仓库是否被标记为 trusted 不同；
• 可用 Skills、插件和 MCP 不同；
• 权限、网络和账号工作区不同；
• 一个人运行了测试，另一个只看了 diff。

所以团队一致性不应该定义为：

每个人得到完全相同的回答。

更可操作的定义是：

面对同一类任务，团队能看到相同的项目约束，
得到结构一致的交付物，
经过相同的确定性门禁，
并由明确的人承担批准与例外责任。

这也是为什么“把最好的 Prompt 发到群里”通常只能维持几天。群消息没有作用域、版本、评审记录、自动验证和删除机制；它解决了传播，没有解决治理。

2. 先做规则路由：这条要求应该放在哪里

团队最容易犯的错误，是把所有要求都塞进根目录 AGENTS.md：

代码风格、发布流程、安全命令、PR 模板、架构背景、
某次事故、某个人的表达习惯、所有工具配置……

文件会越来越长，但可执行性反而下降。更稳妥的做法是先问四个问题。

图 2：团队规则应该进入 AGENTS、Skill、CI 还是权限策略

移动端可打开图 2 原始 SVG放大查看。

2.1 每次进入这个目录都要知道吗

是，就放在该作用域的 AGENTS.md：

真实构建命令；
目录结构和入口；
不能随意改变的 API；
验证和 review 期望；
何时必须停止并找负责人。

2.2 只在某类任务中需要吗

是，就做成 Skill：

发版检查；
数据库迁移 review；
技术文章审稿；
PR 就绪检查；
事故复盘整理。

Skill 可以携带步骤、模板、references 和脚本，不必让所有任务都提前加载完整内容。

2.3 能由程序确定真假吗

是，就交给脚本或 CI：

格式是否正确；
测试是否通过；
资源是否存在；
迁移文件是否成对出现；
frontmatter 是否完整；
敏感文件是否进入 diff。

“必须跑测试”写在 AGENTS.md 是指导；受保护的 CI check 才是合并门禁。两者并不重复：前者帮助 Codex 早点做对，后者防止任何贡献者绕过。

2.4 属于不能靠模型自觉遵守的安全边界吗

是，就交给权限、策略或外部系统：

禁止 full access；
限制可用 MCP；
禁止读取 secrets；
部署必须批准；
主分支不能直接 push；
生产数据库只允许特定身份访问。

把安全要求只写成“请不要”没有强制力。它可以解释原因，但不应是唯一防线。

3. 共享 AGENTS.md：写给新队友，而不是写给模型猜

OpenAI 当前文档把 AGENTS.md 描述为可随仓库共享的项目指导。Codex 从项目根目录向当前工作目录收集指导，越接近当前目录的文件越晚加入，因而可以覆盖更早的规则；指导链在每次 run 或 TUI session 开始时重建。OpenAI：Custom instructions with AGENTS.md

这带来三个团队设计原则。

3.1 根规则只保留共同基线

根目录适合放：

## Commands

- Install: `npm ci`
- Fast tests: `npm test`
- Lint: `npm run lint`
- Build: `npm run build`

## Change Boundaries

- 不改变任务以外的文件。
- 不新增生产依赖、修改迁移或部署，除非维护者明确批准。

## Verification

- 先复现，再修复。
- 报告实际运行命令、结果和未验证项。

它不适合保存某个成员的个人偏好，例如“回答都用三句话”或“我喜欢某种终端工具”。个人偏好留在全局配置，团队仓库只保存影响共同交付的规则。

3.2 局部规则靠近拥有它的目录

假设一个 monorepo 同时包含前端和支付服务：

repo/
├── AGENTS.md
├── apps/web/AGENTS.md
└── services/payments/AGENTS.md

支付目录可以增加：

## Payments Service

- 使用 `make test-payments`，不要运行根目录的前端测试代替。
- 任何账务字段变更都需要迁移、回滚说明和支付负责人 review。
- 不使用真实卡号、生产订单或访问令牌制作测试数据。

局部文件应明确“只覆盖哪些规则”，避免让读者误以为它替代了全部根指导。

3.3 规则必须包含可观察行为

下面两条很难验证：

遵循最佳实践。
小心修改支付代码。

改成：

修改支付计算前，先运行 `make test-payments` 复现失败；
任何金额字段变化都必须包含边界值测试和回滚说明；
找不到现有测试入口时停止，不要发明命令。

团队规则要能映射到文件、命令、输出或停止条件。否则它只是态度表达。

关于长度

官方文档当前说明，Codex 合并项目指导存在默认字节上限；文件过长时应提高配置上限或拆到更接近工作目录的位置。但“提高上限”不是首选修复，先删除重复、过时和本可由 CI 执行的规则。OpenAI：AGENTS.md discovery

4. 共享 Skill：把任务流程和项目基线分开

OpenAI 当前文档建议把 repo-specific Skills 放在 .agents/skills。Codex 先获得 Skill 的名称、描述和路径，只有任务匹配时才加载完整 SKILL.md，之后再按需读取 references 或运行脚本。OpenAI：Customization、OpenAI：Build skills

这正适合 PR 就绪检查。

根 AGENTS.md 只需要写：

所有变更在提交 PR 前都要运行适用的验证，并按严重程度报告发现。

具体步骤放进 .agents/skills/pr-readiness/SKILL.md：

---
name: pr-readiness
description: Check whether a repository change is ready for a pull request. Use when the user asks to prepare, review, or validate a PR; do not use for deployment or merging.
---

## Workflow

1. 读取适用的 AGENTS.md 和 issue 验收标准。
2. 检查工作树与完整 diff，不回退无关改动。
3. 把变更文件映射到最小验证命令。
4. 运行检查，记录命令、退出码、失败和跳过项。
5. 按行为、安全、数据、兼容性和测试缺口 review。

## Stop Conditions

- 未经明确要求，不 push、不创建 PR、不 merge、不部署。
- 验证需要生产密钥或破坏性数据操作时停止。

4.1 团队 Skill 还必须回答两个治理问题

个人 Skill 能用就可以继续迭代；团队 Skill 还必须回答：

谁拥有它？
怎样证明修改后没有错误触发或漏触发？

至少做三类测试：

4.2 Skill 不是共享 Prompt 文件夹

一个名为 everything-engineering 的 Skill，包含所有开发、review、发布和运维步骤，看似统一，实际会产生三个问题：

• 触发范围太宽，普通任务也携带大量无关上下文；
• 某个步骤改变时，无法判断影响哪些任务；
• 权限和外部动作混在一起，难以做最小授权。

团队 Skill 应围绕稳定任务合同组织，不围绕“我们团队所有知识”组织。

5. 确定性检查：不要让 Codex 给自己的作业打通过

配套包的 audit-governance.mjs 会检查：

• 所需治理文件是否存在；
• AGENTS 是否包含 Scope、Commands、Boundaries、Verification、Review 和 Escalation；
• Skill 是否有 name、description、Workflow、Stop Conditions 和 Output Contract；
• 责任矩阵是否有 Owner、Reviewer、Change gate 和 Enforcement；
• 变更提案是否包含 Evidence、Rollout 与 Rollback；
• 权限示例是否意外启用了 never 或 danger-full-access。

从配套包目录运行：

npm run check:json

预期输出：

{
  "ok": true,
  "files_checked": 5,
  "errors": [],
  "warnings": []
}

这个脚本故意不做“AI 规则质量评分”。它无法证明：

• 团队命令真的存在；
• 某条规则符合产品目标；
• Codex 一定遵守自然语言；
• Skill 没有隐藏副作用；
• 权限策略满足组织合规。

这些问题需要真实仓库命令、Skill eval、配置检查和人工评审。确定性脚本只负责它能证明的部分。

5.1 把脚本接到 CI 以后，仍要保留 Owner

CI 能阻止缺字段，却不能决定“支付负责人是否应该批准这条新规则”。因此责任矩阵应同时写出：

Artifact → Owner → Reviewer → Change gate → Enforcement

机器检查的是结构，人检查的是意图、例外和组织影响。

6. 权限治理：项目默认值与管理员要求不是一回事

团队常把以下三种东西混在一起：

OpenAI 当前文档说明，项目 .codex/config.toml 只在仓库被信任时加载；系统、托管要求、运行参数和用户配置有各自优先级。OpenAI：Advanced configuration

小团队可以先共享保守的项目默认值，但不要宣称它是不可绕过的安全边界。真正需要组织强制时，Enterprise 管理员可以用 managed requirements 约束 permission profiles、approval、web search、MCP 和 marketplace 等能力。OpenAI：Managed configuration

配套包提供了一个未激活示例：

default_permissions = ":workspace"
allowed_approval_policies = ["untrusted", "on-request"]

[allowed_permission_profiles]
":read-only" = true
":workspace" = true
# 故意不允许 :danger-full-access

这不是让所有读者立即部署的配置。官方文档当前明确提示 permission-profile allowlist 有客户端版本要求；管理员应先确认所有受管客户端支持，再从小范围试点。OpenAI：Control available permission profiles

6.1 为什么不能只在 AGENTS.md 写“不要 full access”

因为 AGENTS.md 影响模型行为，不是操作系统权限。

同样地，Claude Code 官方文档也明确区分 CLAUDE.md 的行为指导和 managed settings / permissions / hooks 的强制控制：前者告诉 Agent 团队怎样工作，后者用于必须阻止的工具、命令或文件访问。Anthropic：How Claude remembers your project

跨工具都成立的原则是：

能造成不可接受后果的边界，不应只依赖自然语言。

7. 责任矩阵：不要让规则成为“大家共同负责”

“大家都可以维护”经常等价于“没人负责删除”。

一份最小责任矩阵可以这样写：

关键不是职位名称，而是避免三个冲突：

1. 规则作者同时成为唯一批准者；
2. 安全负责人拥有规则，却不了解实际开发路径；
3. 工具管理员能安装连接器，却没有数据 owner 的授权。

8. 规则变更也要像代码变更一样有证据

图 3：团队 Codex 规则从摩擦到推广的变更闭环

移动端可打开图 3 原始 SVG放大查看。

不要因为一次回答不满意，就立刻把一句新要求加进根 AGENTS.md。先填写配套包的 Change Proposal：

Motivation：哪次重复错误、review 意见或事故触发？
Scope：影响哪个仓库、目录、任务和人？
Proposed Change：改 AGENTS、Skill、脚本、CI 还是权限？
Evidence：修改前后的真实例子是什么？
Conflicts：与哪些已有规则重叠？
Verification：正向、负向和确定性检查是什么？
Rollout：先在哪个目录或小组试点？
Rollback：出问题时恢复哪个文件或设置？

8.1 一个实际变更例子

问题：

连续三个 PR 中，Codex 都只运行根目录 npm test，
没有运行 payments 服务的 make test-payments。

不合理修复：

在根 AGENTS.md 增加“运行所有测试”。

更好的修复路径：

1. 在 services/payments/AGENTS.md 写真实命令和作用域；
2. PR Readiness Skill 根据变更路径选择检查；
3. CI 为 payments 路径增加受保护 check；
4. 用一条 payments PR 和一条纯前端 PR 做正负测试；
5. 观察一周后，再决定是否扩到其他服务。

这里的核心不是“补一条 Prompt”，而是让指导、任务路由和合并门禁共同指向同一事实。

9. 推广顺序：先统一交付物，再统一工具

一个常见误区是第一周就要求所有成员：

安装同一套插件；
使用同一个模型；
切换同一权限模式；
复制同一份全局配置。

这会把产品、账号、操作系统和个人习惯差异放大。更稳妥的三阶段顺序是：

阶段一：只共享仓库合同

• 根 AGENTS.md；
• 真实命令和停止条件；
• PR 输出模板；
• 现有 CI 与人工 review。

验收：不同成员完成同类任务时，交付物字段一致，且不会跳过仓库门禁。

阶段二：沉淀一两个高频 Skill

• 选择重复最多、边界最清楚的任务；
• 做正向、负向和行为测试；
• 指定 owner 与 reviewer；
• 不包含自动部署或破坏性动作。

验收：Skill 比复制 Prompt 少遗漏步骤，同时没有明显误触发。

阶段三：再讨论共享配置和托管策略

• 统计真实 approval 摩擦；
• 列出必须访问的域名、MCP 和路径；
• 从 read-only / workspace 试点；
• 记录客户端版本和回滚；
• 安全负责人参与。

验收：权限变宽是为了已证实的任务需要，不是为了少弹几个确认框。

10. Codex、Claude Code 与 GitHub Agent：共享原则，不强求同一文件

这些工具都在逐渐支持“仓库内持久指导 + 可复用能力 + 权限或外部门禁”，但文件名和加载方式并不完全相同。

GitHub 当前文档已说明，仓库可以放置 AGENTS.md，最近的文件对 Agent 生效；同时也保留 GitHub 自己的 repository-wide 和 path-specific instructions。GitHub：Adding repository custom instructions

Claude Code 则建议把项目文件提交到 Git 供团队共享，把个人配置留在 ~/.claude，并用 /context、/memory、/skills、/permissions 等命令检查实际加载状态。Anthropic：Explore the .claude directory、Anthropic：Debug your configuration

10.1 哪些内容可以共用

适合跨工具共用：

真实构建和测试命令；
目录所有权；
API 和数据边界；
验收标准；
停止条件；
PR 模板；
确定性脚本。

不应假装共用：

具体权限键；
Skill 发现路径；
Hook 事件名；
MCP 配置格式；
账号、套餐和企业策略；
不同 Agent 的工具注解。

可以维护一份人类可读的“团队工程合同”，再为各工具做薄适配；不要通过复制粘贴三份长规则制造新的漂移。

11. GitHub 是团队 Agent 的最后一道协作边界

即使本地 Codex 已经完成测试和 review，PR 仍应经过：

• 独立分支；
• 完整 diff；
• required checks；
• CODEOWNERS 或维护者 review；
• secrets / dependency / security 扫描；
• 合并权限与审计记录。

GitHub 对 cloud coding agent 的风险说明也把“Agent 能推送代码”和“人类 review 后才能 merge”分开；Agent 的内置安全检查不能替代仓库规则和维护者判断。GitHub：Risks and mitigations for cloud agent

这条原则同样适用于 Codex：

Agent 可以成为贡献者，但不应同时成为需求方、实现者、唯一审稿人和最终合并者。

12. 常见失败，以及应该改哪一层

13. 45-60 分钟团队练习

目标：选择一个真实高频任务，完成最小团队治理闭环，但不修改生产权限。

0-10 分钟：收集一次重复摩擦

从最近 PR 或任务记录中找一个具体问题：

遗漏测试；
错误目录；
重复 review 意见；
忘记发布前检查；
没有报告未验证项。

验收：能给出任务、实际行为和期望行为，不使用“体验不好”作为唯一证据。

10-20 分钟：做规则路由

依次回答：

1. 每次进入目录都要知道吗？
2. 只在特定任务中需要吗？
3. 能否由程序判断？
4. 是否属于安全强制边界？

验收：最终选择的载体不超过两个；不要一次重构所有配置。

20-35 分钟：写最小规则或 Skill

复制配套包中的 AGENTS.template.md 或 pr-readiness Skill，改成真实命令、作用域、输出和停止条件。

验收：至少包含一个正常例子和一个必须停止的例子。

35-45 分钟：指定 Owner 并跑审计

填写 docs/codex-ownership.md，再运行：

cd codex-team-governance-kit
npm run check:json

验收：结构检查通过；一位非作者成员能解释规则作用域。

45-60 分钟：做小范围试点

选两条任务：

• 一条应该触发新流程；
• 一条不应该触发。

记录结果、遗漏和冲突。先保留在草稿 PR，不修改组织 managed requirements，也不自动 merge。

最终应留下：

1 条有证据的重复摩擦
1 个明确载体选择
1 份最小 AGENTS 或 Skill 修改
1 个 Owner + Reviewer
1 组正向 / 负向测试
1 个回滚方式

14. 收藏清单

规则

• 根 AGENTS.md 只保存共同基线。
• 子目录规则靠近实际所有者，并写清覆盖范围。
• 每条要求映射到命令、文件、输出或停止条件。
• 个人表达偏好不进入团队仓库规则。

Skills

• Skill 围绕一种稳定任务合同。
• description 同时说明何时使用和何时不用。
• 有正向、负向和行为测试。
• 外部写入、merge 和部署默认停在人工批准前。

门禁

• 确定性要求进入脚本、测试或 CI。
• 安全边界不只依赖自然语言。
• project default 与 admin-enforced requirement 明确区分。
• 分支保护和人工 review 仍然存在。

维护

• 每个共享资产有 Owner 和 Reviewer。
• 规则变更包含 Evidence、Rollout 和 Rollback。
• 过时、重复和不可验证规则会被删除。
• 先做小范围试点，再扩大权限或安装范围。

写在最后

Codex 团队化最值得追求的，不是让每个人拥有同一个“AI 同事”，而是让 Agent 的参与方式进入团队原本就应该具备的工程系统：

规则有作用域；
流程有产物；
检查有证据；
权限有边界；
变更有责任人；
失败有回滚。

如果一个团队本来没有真实命令、测试、代码所有权和发布门禁，增加 Agent 只会更快地暴露这些缺口。反过来，一旦这些基础存在，Codex、Claude Code 或 GitHub Agent 都更容易成为可审查的贡献者，而不是另一套只存在于聊天记录里的隐性流程。

下一篇是这个系列的最后一篇：Codex 的限制：额度、上下文、幻觉、隐私和工作边界。它会回答“哪些任务可以放心交给 Codex，哪些只能让它辅助，以及什么时候应该立刻停下来”。

参考资料

OpenAI 官方

• Customization
• Custom instructions with AGENTS.md
• Build skills
• Advanced configuration
• Managed configuration
• Agent approvals & security
• openai/codex 的 AGENTS.md 实例

Claude / Anthropic 对照

• How Claude remembers your project
• Explore the .claude directory
• Debug your configuration
• anthropics/skills

GitHub 协作边界

• Adding repository custom instructions
• Risks and mitigations for GitHub Copilot cloud agent

Claude 与 GitHub 资料用于比较项目指导、Skills 和强制门禁的共同原则，不作为 Codex 配置行为的证据；Codex 当前行为以 OpenAI 官方资料为准。