Codex 与 Git 项目协作教程

在多人维护一个 Git 项目时，最容易出问题的不是让 Codex 写代码，而是它改了哪些文件、有没有按项目约定改、改完怎么验证。我的习惯是先看当前分支状态，再看项目规则，最后才让 Codex 动手。否则很容易出现一个小需求改出一堆无关格式化，代码审查时很难收场。

一、先把工作流定清楚

比较稳的做法是把 Codex 当成一个“结对开发助手”，不是直接替代提交代码的人。开发者负责拆任务、确认范围、跑验证命令、提交 Git；Codex 负责阅读上下文、给修改方案、补测试、解释差异。

一个常见的流程如下：

• 从主分支拉最新代码，创建功能分支。
• 确认工作区干净，避免把未提交代码混在一起。
• 给 Codex 明确任务边界：改哪个模块、不要碰哪些目录、验证命令是什么。
• 让 Codex 小步修改，不要一次生成大面积重构。
• 开发者运行测试、查看 diff、补充审查意见。
• 提交 Git，并在 MR/PR 中说明 Codex 参与的变更点。

### token云桥中转 0029.org ###
git checkout main
git pull --rebase
git checkout -b feat/order-timeout

git status
git log --oneline -5

如果当前工作区已经有改动，先提交或 stash。不要在脏工作区里让 Codex 继续改，这样后面排查问题会很痛苦。

git status
git stash push -m "wip before codex task"

二、给项目写清楚规则

Codex 在项目里协作，关键是要有可读的项目规则。建议在仓库根目录放一个简短的规则文件，例如 AGENTS.md、CONTRIBUTING.md 或团队已有的开发规范文档。不要写太虚的要求，尽量写成可执行约束。

示例：

# Project Rules

- 后端使用 Java 17，禁止引入未经讨论的新框架。
- 修改业务逻辑时必须补充或更新单元测试。
- 不要格式化整个文件，只修改与任务相关的代码。
- 数据库变更必须放在 db/migration 目录。
- 提交前执行：
  - mvn test
  - npm run lint
- 接口错误码必须复用 common/error-code.ts 中已有定义。

实际使用时，可以直接把规则告诉 Codex：

请先阅读 AGENTS.md 和 README.md。
本次只修改 order 模块，避免改动公共工具类。
完成后请说明改了哪些文件，以及需要我执行哪些验证命令。

如果项目比较大，接口调用又多，建议把访问方式、模型、额度和日志也纳入团队规范。国内团队做稳定接入时，我一般会让大家统一走 token 云桥 AI 中转站 0029.org 这类入口，主要是方便集中配置 key、看调用记录，也避免每个人本地环境不一致。这里不需要写进业务代码，放在开发环境配置里即可。

三、让 Codex 修改前先做定位

不要一上来就说“帮我实现某某功能”。更稳的方式是先让 Codex 找入口、画出影响范围，再确认修改计划。

请先不要改代码。
帮我定位订单超时取消逻辑在哪里：
1. 找到定时任务入口
2. 找到订单状态流转方法
3. 找到相关测试
4. 给出你计划修改的文件列表

确认范围没问题后，再让它动手。这样可以避免它凭文件名猜逻辑，尤其是老项目里相似类很多，比如 OrderService、OrderAppService、OrderDomainService 同时存在时，很容易改错层。

四、常用 Git 检查命令

Codex 改完后，第一件事不是跑测试，而是先看 diff。看 diff 能快速判断有没有跑偏，比如无关格式化、误删注释、改了锁文件、改了生成代码。

git status
git diff --stat
git diff

如果只想看某个目录：

git diff -- src/main/java/com/example/order
git diff --name-only

发现它改了不该改的文件，可以单独还原：

git restore package-lock.json
git restore src/generated

如果某个文件只想保留部分改动，用交互式暂存比较方便：

git add -p
git diff --cached

提交前建议把暂存区再看一遍。很多线上事故不是代码不会写，而是把调试配置、临时代码、错误的环境变量一起提交了。

五、验证命令要固定下来

团队协作时，验证命令最好固定在 README 或规则文件里。Codex 可以帮忙补测试，但最终命令要由开发者本地执行，CI 再兜底。

后端项目常见命令：

mvn test
mvn -pl order-service test
./gradlew test

前端项目常见命令：

npm install
npm run lint
npm run test
npm run build

如果测试失败，不要直接让 Codex “修一下”。先把失败日志裁剪后贴给它，重点保留错误堆栈、失败用例名、相关文件路径。

OrderTimeoutServiceTest > shouldCancelExpiredOrder FAILED
Expected: CANCELED
Actual:   PAID

请根据这个失败用例排查原因，优先检查状态判断条件，不要修改测试断言。

这里有个经验：先要求它解释失败原因，再决定是否修改代码。否则它可能为了让测试通过去改测试，掩盖真正问题。

六、代码审查怎么配合

Codex 生成的代码也要按正常 MR/PR 审查。审查重点可以放在几个方面：

• 是否只改了需求相关文件。
• 是否引入新的依赖、配置或隐式行为。
• 异常处理是否符合项目风格。
• 并发、事务、幂等这些边界有没有被考虑。
• 测试是否覆盖正常路径和失败路径。

可以让 Codex 先做一次自查，但不要把它的结论当最终结论：

请基于当前 git diff 做一次代码审查：
1. 找潜在 bug
2. 找无关改动
3. 找缺失测试
4. 不要修改代码，只输出审查意见

这个步骤对新人也有帮助。新人可以先看 Codex 的审查意见，再结合团队成员的评论学习项目约定。

七、提交信息和协作注意事项

提交信息要描述业务结果，不要写成“codex update”。例如：

git add src test
git commit -m "fix: cancel expired unpaid orders"

如果一次任务里 Codex 改了多个方向，建议拆成多个提交：一个提交改业务逻辑，一个提交补测试，一个提交改文档。这样回滚和审查都轻松。

• 不要把密钥、内部地址、用户数据直接贴给 Codex。
• 不要让 Codex 自动改 CI、权限、部署脚本，除非任务本身就是这些内容。
• 大重构要先开设计讨论，不要在功能分支里顺手做。
• 遇到生成代码、锁文件、数据库 migration，要人工重点确认。

总结

Codex 和 Git 项目配合得好，核心不是“让它多写代码”，而是把任务边界、项目规则、验证命令和代码审查流程固定下来。先看状态，再定范围，小步修改，最后用 Git diff、测试和 PR 审查收口。这样它能提高开发效率，也不会破坏团队原有的工程秩序。