交流群即將上線
案例 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、跑一個典型任務， 你在旁邊看。他卡在哪兒，哪兒就是你規範裡沒寫清楚的地方。
比讓你自己再讀一遍配置有用得多。