Codex 落地 Checklist：上线前必须完成的 10 项配置

别急着给全员发账号。在按下“Run Task”之前，请对照这份清单，确保你的仓库已经做好了迎接“硅基实习生”的准备。

1. 确立 AGENTS.md的“宪法地位”

这是最重要的一步。在仓库根目录创建 AGENTS.md，并将其视为代码规范的一部分。

• 必须包含：技术栈版本（Node/Python/Go）、包管理器（pnpm/npm）、禁止修改的文件路径（如 config/、 .env）。

• 必须排除：代码中显而易见的常识（如“使用 TypeScript 类型”）。

• 黄金法则：控制长度在 300 行以内，子目录可放置自己的 AGENTS.md覆盖父级规则。

2. 固化 setup.sh环境引导脚本

Codex 启动沙箱后的第一件事就是运行 setup.sh。这个脚本决定了 Agent 能不能“醒过来”。

• 核心任务：安装依赖、编译 Proto/Thrift、生成数据库客户端代码。

• 避坑点：确保脚本是 幂等的（重复运行不会报错），且执行时间在 3 分钟以内。太慢会拖垮并行效率。

• 示例： pnpm install --frozen-lockfile && pnpm build:generated

3. 设定“测试门禁”为唯一真理源

Codex ( codex-1) 的训练目标是“让测试通过”。如果测试本身是垃圾，产出的代码就是垃圾。

• 最低要求：核心业务逻辑单元测试覆盖率必须 > 60%。

• CI 对齐：确保 Codex 运行的测试命令（ npm test）与生产 CI 环境完全一致。不要出现“本地能过，CI 不过”的情况，这会逼疯 Agent。

4. 配置 .codexignore保护敏感区域

类似于 .gitignore，告诉 Codex 哪些地方绝对不能碰。

• 必加项： .env*、 *.pem、 secrets/、 production.config.js。

• 作用：防止模型在“自主探索”时意外读取或修改敏感配置，即使 AGENTS.md写了禁止，这也是一层物理防线。

5. 开启并校准“审批模式”（Approval Mode）

在 Codex Web/App 设置中，找到 Sandbox 权限设置。

• 初始阶段：设置为 "Always ask"（总是询问）。让人类确认每一次 Shell 执行和网络访问。

• 信任建立后：对于 npm install、 pnpm build等白名单命令，可以设置为自动放行，但对 curl、 wget、 rm -rf保持警惕。

6. 建立“坑点库”反馈闭环

不要指望一次写完 AGENTS.md就能高枕无忧。

• 机制：每当 Review PR 发现 Codex 犯了低级错误（如忘记处理边界条件、误删 Mock 数据），立即将该案例记录到 AGENTS.md的 # Gotchas章节。

• 效果：这相当于给 Agent 建立了“错题本”，随着时间推移，它犯同样错误的几率会指数级下降。

7. 拆解 Issue 颗粒度（Task Scoping）

Codex 擅长处理边界清晰的单点任务，不擅长宏大的架构愿景。

• Bad：优化用户模块的性能。

• Good：将 UserService.getUserById函数的数据库查询从 N+1 改为 Batch Request，并补充相关单元测试。

• 建议：一个任务的生命周期控制在 1-2 小时内，Diff 不超过 500 行。

8. 预置 wait_agent指令（针对并行任务）

如果你打算使用多 Agent 并行处理复杂任务，务必在 AGENTS.md中明确规定子 Agent 的同步指令。

• 关键点：新版本 Codex 废弃了 wait，必须使用 wait_agent来等待子任务完成，否则父进程会提前结束导致任务悬空。

9. 配置日志与监控（Observability）

虽然 Codex 提供了终端日志，但你需要更高维度的观察。

• 监控指标：跟踪 Codex 提交 PR 的通过率（Pass Rate）、平均修复时长（MTTR）。

• 告警：如果一个 Agent 连续 3 次提交未能通过 CI，应自动暂停该任务并通知人类介入，防止模型陷入无效的自我修复循环。

10. 制定“回滚”预案

无论 AI 多么强大，必须有兜底方案。

• Git 策略：确保所有 Codex 提交的 PR 都使用 Squash and Merge，保持主干历史的整洁。

• 回滚练习：在正式使用前，演练一次“Revert Codex PR”的流程，确保当 AI 引入隐蔽 Bug 时，团队能在一分钟内恢复服务。