交流群即将上线
案例 04 · 把团队规范固化下来
什么场景
团队里有一堆没写下来的约定：改了 API 要同步更新 docs/api/、 internal/ 下的东西不许被外部包引用、新依赖要过安全组、 提交信息按某个格式写。
这些东西每次新人来讲一遍，每次评审时提醒一遍。现在可以让它们变成 Codex 每次都会读到的东西。
四层，按顺序上
别一次全上。按这个顺序，每一步都能单独产生价值，出问题也容易回退：
| 顺序 | 做什么 | 放哪 | 影响谁 |
|---|---|---|---|
| 1 | 写清怎么干活 | AGENTS.md | 所有在这个仓库用 Codex 的人 |
| 2 | 统一默认设置 | .codex/config.toml | 同上，且仅在项目被信任时 |
| 3 | 沉淀重复流程 | .agents/skills/ | 同上 |
| 4 | 强制安全底线 | requirements.toml | 全公司的设备，管理员下发 |
前三层跟着代码走，谁 clone 谁得到。第四层是管理员的事，走的是完全不同的渠道。
第 1 步：AGENTS.md
从这里开始，因为它成本最低、不改任何人的权限，而且当天就能见效。
md
# AGENTS.md
## 怎么跑
- 测试：`make test`（不是 `npm test`，我们有额外的 fixture 准备步骤）
- Lint：`make lint`，提 PR 前必须过
- 本地起服务：`docker compose up -d && make dev`
## 红线
- 不要修改 `gen/` 下的任何文件，那是 protobuf 生成的
- 不要在 `internal/` 之外引用 `internal/` 的包
- 加新的生产依赖前先问我，不要直接改 go.mod
## 约定
- 改了 `api/` 下的接口定义，同步更新 `docs/api/` 里对应的文档
- 错误一律用 `pkg/errors` 包装，不要裸 `fmt.Errorf`写法上的几个要点（详见 快速上手 05）：
- 写命令，不写介绍。 「我们是一个微服务项目」这种话它自己能看出来。
- 红线要具体到路径。 「注意代码质量」没有任何作用。
- 控制长度。 合并后超过
project_doc_max_bytes（默认 32 KiB）就会被截断， 写太长等于把后面的指令扔掉。
子目录有特殊规矩就在那儿放 AGENTS.override.md。 记住合并规则：越靠近当前目录的文件出现得越晚，覆盖前面的。
第 2 步：仓库配置
toml
# .codex/config.toml
model = "gpt-5.6"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
[sandbox_workspace_write]
network_access = false它只在项目被信任时加载
Codex 出于安全考虑，只有你信任某个项目才会加载它的 .codex/ 层—— 包括项目本地配置、钩子和规则。所以团队成员第一次 clone 之后要确认信任这个项目， 配置才生效。这个提示要写进 README，否则会出现「为什么我这儿行为不一样」。
还要知道这一层的能力上限：仓库配置能给默认设置和可复用工作流， 但授不了工作空间、模型、平台 API 或已连接系统的访问权限。 「让新人 clone 完就有 Codex 用」这件事仓库配置办不到，那是账号和席位的事。
第 3 步：共享技能
把重复流程提交到 .agents/skills/，整个仓库的人都能用。
.agents/skills/
release-notes/SKILL.md
add-endpoint/SKILL.md
migrate-table/SKILL.mdadd-endpoint/SKILL.md 大概长这样：
md
---
name: add-endpoint
description: 在本仓库新增一个 HTTP 接口时使用。涵盖路由注册、请求校验、错误包装、
接口文档同步和测试。不要用于修改已有接口的行为。
---
新增接口时按这个顺序：
1. 在 `api/openapi.yaml` 里先定义，包括所有错误码
2. `internal/handler/` 下加 handler，用 `pkg/validate` 做请求校验
3. 在 `internal/router/routes.go` 注册路由
4. 错误一律经 `pkg/errors.Wrap`，不要直接返回下游错误
5. `docs/api/` 下补一页说明，格式参考 `docs/api/get-user.md`
6. 加集成测试到 `test/integration/`，至少覆盖成功、参数错误、下游超时三种情况
完成后跑 `make test && make lint`。description 那一行决定它什么时候被自动选中，值得反复打磨—— 写清楚什么时候用，也写清楚什么时候不用。
注意技能的选择器有预算：初始技能列表最多占模型上下文窗口的 2% （窗口未知时最多 8000 字符）。装太多技能，Codex 会先压缩描述， 再多就直接省略一部分并给出警告。所以仓库技能保持精简， 别把每个小操作都做成一个技能。
顺手加一节审查规则
如果用 GitHub 上的 Codex 代码审查， 在最贴近相关代码的 AGENTS.md 里加：
md
## Code Review Rules
### Internal package boundaries
- Do not import `internal/` packages from outside the module.
Safe path: expose the needed behavior through `pkg/` with an explicit interface.仓库范围的检查放根目录，服务专属的放嵌套文件里。 格式和 lint 留给 CI，别写进来。
第 4 步：requirements.toml（管理员）
这是唯一有强制力的一层，由管理员通过云端、设备或系统渠道下发， 约束本地运行时的行为。
推荐用权限配置方案来写，不要围绕旧的沙盒模式限制设计：
toml
default_permissions = ":workspace"
[allowed_permission_profiles]
":read-only" = true
":workspace" = true这样 danger-full-access 就不在允许列表里了，谁也 --yolo 不了。
需要全面关掉计算机使用的话，相关功能键要一个个关：
toml
[features]
browser_use = false
browser_use_full_cdp_access = false
browser_use_external = false
in_app_browser = false
computer_use = false这套策略要和 ChatGPT 工作空间的角色、群组分开管理： 一个管设备上的运行时能做什么，一个管谁能登录、能用哪些界面。
推进的时候会遇到什么
「我这儿跟你那儿行为不一样。」 九成是项目没被信任，.codex/ 层没加载。 让对方确认一下信任状态。
「配置写了但没生效。」 想想六层优先级： CLI 标志 > 项目配置 > 配置方案 > 用户配置 > 系统配置 > 内置默认值。 对方 ~/.codex/config.toml 里的设置优先级低于仓库配置， 但他敲的命令行标志优先级最高。
一上来就下发 requirements.toml。 最容易失败的推进方式。 限制还没搞清楚大家实际怎么用就先定死，结果通常是有人转去用 API 密钥登录绕开管控—— 那样连审计都丢了。先跑前三步，看清实际用法，再定强制线。
怎么验收
找一个没参与配置的同事，让他 clone 仓库、装 Codex、跑一个典型任务， 你在旁边看。他卡在哪儿，哪儿就是你规范里没写清楚的地方。
比让你自己再读一遍配置有用得多。