团队工作流：从 Issue 到合并请求

Codex 的速度只有进入团队现有的评审、测试和发布制度后才有价值。一个成熟流程不追求“让智能体做得最多”，而是让每一步都有输入、权限边界、验证证据和明确责任人。

工作流总览

Issue 准入
  -> 调查与复述
  -> 计划和风险门槛
  -> 小步实现
  -> 自动验证
  -> 独立审查
  -> 人工批准
  -> 合并与复盘

每个阶段都应能回答三个问题：当前在解决什么、Codex 可以做什么、谁根据什么证据批准进入下一步。

1. 先给 Issue 设置准入标准

适合直接交给 Codex 的任务通常具备：

• 可复现的问题或清晰的用户行为；
• 有限的代码范围和依赖边界；
• 可以运行的测试、构建或人工验收步骤；
• 不需要隐含的组织决策；
• 失败后容易回退。

不适合直接进入实现的任务：

• “重做整个架构”“全面优化性能”这类目标未定义的工作；
• 需要产品、法务、安全或数据治理决策；
• 生产删库、密钥轮换、不可逆迁移；
• 没有测试环境、无法观察成功与否；
• 会同时修改多个团队拥有的公共契约。

Issue 模板

## Background
为什么需要这个改动，谁受到影响。

## Current behavior
复现步骤、输入、日志或截图。

## Expected behavior
用户或系统可观察的结果。

## Scope
允许修改的模块，以及明确不在范围内的内容。

## Constraints
兼容性、依赖、安全、性能和发布时间要求。

## Acceptance criteria
- [ ] 行为标准
- [ ] 自动测试
- [ ] 人工验证
- [ ] 文档或迁移说明

## Risk and rollback
高风险操作、审批人、回滚方式。

2. 按风险选择 Codex 使用方式

任务	推荐方式	原因
解释当前文件、局部修改	IDE 扩展	自动利用打开文件和选区，上下文紧凑
仓库级排查、运行命令、连续调试	CLI 或桌面应用本地任务	适合显式路径、命令记录和快速反馈
边界清晰、耗时较长的独立任务	云端任务	可在隔离环境后台运行，适合异步交付
规则明确的一次性批处理	codex exec	便于脚本化和结构化输出
合并前寻找具体回归	codex review 或独立审查任务	与实现上下文分离，减少确认偏差

选择方式时先看数据和权限边界，再看便利性。需要访问私有依赖、内部服务或凭据的任务，应遵循组织策略配置环境，不把密钥直接写进提示词或仓库。

3. 把调查与实现分成两个关口

调查阶段

先不要修改文件。阅读 Issue 和相关代码，复现问题并报告：
- 根因假设及证据；
- 最小修改范围；
- 可能受影响的公开契约；
- 当前测试覆盖和缺口；
- 仍需人工决定的问题。

调查阶段的输出由负责人确认。根因、范围或验收标准不清楚时，任务不进入实现。

实现阶段

按已确认计划实现。每完成一个行为变化就运行最相关的检查。
若出现以下情况请停止并报告：
- 需要新增生产依赖；
- 需要改变公开 API、数据格式或数据库结构；
- 修改范围超出已确认模块；
- 基线测试与 Issue 描述冲突；
- 需要访问生产或执行不可逆操作。

“停止条件”比泛泛要求“小心”更容易执行，也给团队留下明确的审批点。

4. 用 AGENTS.md 固化团队约定

仓库根目录可以维护：

# Engineering guidance

## Required checks
- Run targeted tests after each behavioral change.
- Before handoff, run `pnpm lint`, `pnpm test`, and `pnpm build`.
- Report failures and unverified behavior; do not claim skipped checks passed.

## Change boundaries
- Preserve public APIs unless the issue explicitly approves a breaking change.
- Do not add production dependencies without approval.
- Do not edit generated files directly.
- Keep migrations reversible and include a rollback note.

## Review expectations
- Findings must include file/line evidence and a concrete impact.
- Treat security, data loss, and compatibility regressions as highest priority.

子项目有不同命令或规则时，在对应目录放更具体的 AGENTS.md。不要让根文件增长成无人维护的制度大全；只保留能改变日常决策、可以验证的规则。

5. 设计小步提交与验证金字塔

推荐从最便宜、最相关的检查开始：

1. 单个测试或最小复现；
2. 受影响模块的测试、类型检查或 lint；
3. 全量单元/集成测试；
4. production build；
5. 浏览器、设备、性能或预发布环境验证。

不要每改一行就跑半小时的全量流水线，也不要只跑一个快乐路径测试就宣布完成。验证范围应随着改动范围和风险扩大。

建议提交保持一个可解释意图：

• test: reproduce duplicate checkout request
• fix: guard checkout submission while pending
• docs: document retry and rollback behavior

是否真的拆成多个 Git commit 由团队规范决定，但思考和验证最好按这些边界进行。

6. 多任务和并行工作的边界

适合并行：

• 一个任务复现后端错误，另一个任务补充独立前端测试；
• 分别调查互不重叠的模块；
• 实现完成后，独立任务做安全或兼容性审查；
• 文档更新与不修改同一文件的代码工作并行。

不适合并行：

• 多个任务同时重写同一个核心文件；
• 一个任务依赖另一个尚未稳定的接口；
• 数据库迁移与调用方修改缺少统一设计；
• 为了“多智能体”而拆出没有独立验收标准的子任务。

并行前写清每个任务的输入、拥有文件、输出和合并顺序。最后必须回到一个集成分支统一运行测试；各自通过不等于组合后通过。

7. 将安全审批放在真正的风险点

本地 Codex 的沙箱模式决定技术上能做什么，审批策略决定何时需要停下询问。团队可以采用以下分层：

操作	默认策略
阅读仓库、运行只读检查	自动允许
修改当前工作区、运行项目测试	在受信任仓库中允许
下载依赖、访问外网	按任务和目标域名审批
写工作区外文件、使用连接器产生副作用	明确审批
生产部署、数据删除、密钥操作	人工执行或双人审批

不要把 danger-full-access 或绕过审批作为团队默认配置。减少提示框的正确方法是收窄且固化可信命令/域名，而不是取消边界。

8. PR 必须携带证据

PR 描述模板

## What changed
- 说明行为变化，而不是只列文件。

## Why
- 对应 Issue、根因和关键设计选择。

## Verification
- `command` - passed/failed/skipped
- 人工验证的环境、视口或场景

## Risk
- 兼容性、数据、安全、性能或发布风险

## Not verified
- 明确没有条件验证的部分

## Rollback
- 回退 commit、关闭开关或恢复数据的方式

禁止模糊表述：“测试应该通过”“已优化性能”“没有风险”。如果没有前后测量，就不要写性能提升；如果检查未执行，就标记 skipped 并解释原因。

9. 实现者与审查者使用不同提示

实现提示关注目标和约束；审查提示应主动寻找反例：

作为独立审查者检查此 diff。不要复述实现摘要。

优先寻找：
1. 会返回错误结果或破坏数据的逻辑；
2. 身份认证、授权、输入校验或敏感信息问题；
3. 并发、重试、事务和部分失败；
4. API、数据库和序列化兼容性；
5. 测试无法捕获的回归。

每条发现提供文件与行号、触发条件、影响和建议修复。
没有具体问题时，明确说明剩余测试盲区。

高风险 PR 仍需领域负责人、安全或数据库负责人审查。Codex 可以增加审查覆盖面，不能成为责任主体。

10. 用质量指标评价流程

不要只统计“生成了多少代码”或“节省了多少时间”。更有用的指标：

• 从 Issue 到首个可审查 PR 的时间；
• PR 被要求返工的次数及原因；
• 合并后回滚率、缺陷逃逸率；
• 验证命令和未验证项的披露完整度；
• diff 中无关修改的比例；
• 团队 AGENTS.md 规则被复用和更新的情况。

先挑低风险、高重复任务试点两到四周，记录基线，再决定是否扩大。不要用单个成功演示推断整个团队的产能变化。

常见反模式

反模式	后果	修正
Issue 只有一句标题	大量猜测、范围漂移	补复现、边界和验收
让 Codex 自己批准高风险变化	决策责任模糊	设停止条件和人工审批人
实现和审查使用同一段上下文	容易确认原方案	使用独立审查任务
只看最终摘要不看 diff	越界修改被忽略	PR 必须人工读 diff
默认开放网络与全磁盘	暴露面过大	按工作区、命令和域名授权
同时开很多重叠任务	合并冲突和行为不一致	按文件所有权与依赖拆分
只衡量代码产量	鼓励更大、更难审的 diff	衡量交付质量和返工

资料来源

OpenAI 官方

• Prompting Codex
• Agent approvals & security
• Configuration Reference
• Developer commands
• Code review

工程作者经验

• Simon Willison：How I use LLMs to help me write code
• Addy Osmani：My LLM coding workflow going into 2026

本文把社区实践转化为团队可执行的准入、停止、验证和复盘机制。涉及具体产品能力、权限和配置时，以 OpenAI 官方资料及组织管理策略为准。

最后校对：2026 年 7 月 22 日