Codex 团队协作最佳实践：worktree、审查与 CI 集成

Codex CLI 在团队里用得好，关键是工作流设计——不只是"让 Codex 写代码"，而是"让 Codex 写代码不破坏团队流程"。本文给出从单任务工作流到 CI 集成的团队实践。

1. 单任务工作流：独立 worktree

每个 Codex 任务跑在独立 git worktree 里：

# 在 main 上创建 worktree（-b 显式新分支名）
git worktree add -b codex-fix-bug ../codex-fix-bug main

# 让 Codex 在 worktree 里干活
cd ../codex-fix-bug
codex "修一下 src/foo.ts 里的 NPE"

好处：

• 主分支工作区不被打断（你还在 main 上继续做别的事）
• Codex 在 worktree 里跑命令不会影响你
• 审完 diff 直接 merge 回 main
• 并发跑多个 Codex 任务互不干扰

2. 敏感路径保护（两层防线）

第一层：hook 阻止自动写入

.githooks/pre-push 脚本示例：

#!/bin/bash
# 阻止 push 修改敏感路径
SENSITIVE='package-lock\.json|pnpm-lock\.yaml|yarn\.lock|\.github/|migrations/|Dockerfile|docker-compose'
DIFF_FILES=$(git diff --name-only HEAD~1)
if echo "$DIFF_FILES" | grep -qE "$SENSITIVE"; then
  echo "✗ 检测到敏感路径改动，请人工 review："
  echo "$DIFF_FILES" | grep -E "$SENSITIVE"
  exit 1
fi

第二层：CODEOWNERS 强制 review

.github/CODEOWNERS：

# 默认 owner
*                    @team-lead

# 敏感路径必须有对应 owner 批准
package-lock.json    @team-lead
pnpm-lock.yaml       @team-lead
.github/             @team-lead
migrations/          @db-team
Dockerfile           @infra-team
src/auth/            @security-team

Codex 改动触发 PR 后，GitHub 自动 request review；没 owner 批准不能 merge。

3. Codex 改动谁来 review

CODEOWNERS 流程触发后，owner 看 Codex diff 的关注点：

经验：在 prompt 里要求 Codex 自查：

写完代码后自查：
1. 是否有无关改动？如有，回退
2. 新逻辑是否有测试覆盖？如无，补上
3. 注释是否解释"为什么"而非只"做什么"
4. 是否有不必要的 console.log / debugger
5. 修改范围是否严格匹配任务描述

4. 并发跑多个 Codex 任务

可以，给每个任务一个 worktree + 分支：

git worktree add -b codex-fix-bug      ../codex-fix-bug      main
git worktree add -b codex-add-feature  ../codex-add-feature  main
git worktree add -b codex-update-deps  ../codex-update-deps  main

注意：

• 并发跑会显著消耗 Codex 配额（按 token / 调用计费）
• 任务之间不要修改重叠的文件（避免合并冲突）
• 合并顺序要排好——通常 bug fix 优先于 feature，feature 优先于 deps

5. CI 集成

必跑：lint + 单测 + 类型检查

# .github/workflows/ci.yml
on: pull_request
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pnpm install
      - run: pnpm lint
      - run: pnpm test
      - run: pnpm typecheck

CI 必须通过才能 merge。Codex 改动如果 lint 不通过或测试挂了，PR 自动标红。

可选：让 Codex 写 PR description

.github/pull_request_template.md：

## 变更摘要
<!-- Codex 自动填写 -->

## 关联 Issue
<!-- 关联 issue -->

## 自测环境
<!-- 哪个 Node 版本、哪个浏览器 -->

## 测试覆盖
<!-- 新逻辑加了哪些测试 -->

## 截图 / 录屏
<!-- UI 改动必填 -->

Codex 写 PR 时按模板填——changelog、关联 issue、自测环境一目了然，reviewer 快速理解。

6. 安全注意事项

7. 团队推广节奏

• 第一周：1 个开发者先用，建立工作流
• 第二周：2-3 个开发者加入，迭代流程
• 第三周：CODEOWNERS + CI 跑通，全员加入
• 每月：回顾 Codex 改动质量，调整 prompt 模板与 CODEOWNERS 配置

8. 下一步

• 《OpenAI Codex CLI 入门：从零配置到日常编码流》
• 《OpenAI API 函数调用实战：Responses API 工具使用完全指南》
• 《自己搭一个 MCP Server：从零到发布的完整指南》