面向读者用过 GitHub Copilot、写过 SpringBoot/MyBatis、懂 JVM 调优和 Maven 构建的 Java 资深工程师。目标读完你能分清「初代 Codex 模型」和「现在的 Codex Agent」能在终端用 Codex CLI 修 Bug、补测试、接 MCP并把 AGENTS.md 写进团队规范。0. 先拆歧义Codex 不是你以为的那个 Codex很多 Java 老兵对 Codex 的印象停在 2021 年——「哦就是给 Copilot 提供补全能力的那个 GPT-3 微调模型」。那个 Codex 已经退场了。现在的OpenAI Codex2025.5 起 是一个软件工程智能体系统包含三件套codex-1基于 o3 系列、在真实 PR 和测试反馈上做 RL 的专用编程模型后续还有 GPT-5.x-codex 系列Codex CLIRust 写的开源终端 Agentnpm i -g openai/codex就能装本地沙箱跑Codex Cloud / Web / Desktop云端隔离容器里异步跑任务、回 PR 的托管形态和 Copilot 的本质差异Copilot 你写它补同步、IDE 内、你主导Codex 你派活它交 PR异步、可并行多任务、它自己跑测试修红一句话定位Codex 是「远程实习生」Copilot 是「结对搭档」。1. Codex 的执行闭环为什么它能自己把测试跑绿别把它当「高级代码生成器」。它的核心是 Agent Loop你发自然语言任务 → Codex 读 AGENTS.md / 仓库结构 → 规划步骤不是一次生成全部代码 → 调工具read_file / write_file / patch / shell(mvn test) → 观察输出编译错误、单测失败、Sonar 问题 → 自我修正 → 再循环 → 收敛后给 diff 终端日志 可选 PR关键点测试反馈是上下文的一部分。你让它「给 OrderService 补单测」它不是瞎写 JUnit而是真跑mvn -q test红了他自己改直到绿。这对 Java 工程师意味着你交给它的任务粒度应该是「一个 Ticket」而不是「写个方法」。2. 十分钟跑通 Codex CLIJava 项目视角2.1 安装与登录npm install -g openai/codex codex # 首次启动走 ChatGPT OAuth 或 API Key 登录Plus/Pro/Team/Enterprise 套餐已含 Codex 额度不单独收费。2.2 三档审批模式决定你半夜敢不敢开 full-auto模式文件写跑 shell网络适用场景suggest默认问问-看陌生代码、审 PRauto-edit自动问-日常重构full-auto自动自动默认断网修编译/补测试/原型codex -a full-auto 把 UserController 的参数校验用 Valid 补齐并跑通 mvn testLinux 下沙箱用 Landlock/seccompmacOS 用 SeatbeltWSL2 走 Docker 或 bypass 标志。full-auto 默认出站网络全断所以 Maven 首跑会跪——这是 Java 项目第一个坑见 §4。2.3 非交互模式CI 里用codex exec --full-auto --quiet 更新 CHANGELOG 并准备下一个版本GitHub Action 里接openai/codex-action或直跑codex exec都行。3. AGENTS.md给 Codex 的「Java 团队入职手册」Codex 启动时会按优先级合并指令~/.codex/AGENTS.md 个人全局 repo/AGENTS.md 仓库级提交进 Git repo/sub/AGENTS.md 子模块覆盖这是你作为资深工程师最该花时间的地方。给个 SpringBoot 项目的真实样例# AGENTS.md电商订单服务 ## 构建与测试 - 构建./mvnw -o package依赖已离线缓存到 .m2 - 单测./mvnw -o test - 集成测试./mvnw -o test -Dtest*IT - 禁止跑 mvn clean 清掉 .m2 ## 代码规范 - 遵循《阿里巴巴 Java 开发手册》终极版 - Controller 只做参数校验 调 Service禁止写 SQL - 数据库字段下划线Entity 字段驼峰用 TableField 映射 - 事务用 Transactional 且必须指定 rollbackFor - 禁止在事务内调 Feign / RocketMQ 同步发送 ## 禁止项 - 不引入新的 starter除非先问我 - 不改 Flyway 已有版本脚本 - 不用 lombok Data 在 Entity 上用 Getter/Setter ## 提交规范 - 分支命名 fix/xxx feat/xxx - 提交信息用中文动宾结构修复订单超时未关单问题经验数据AGENTS.md 写清楚后Codex 产出的 PR 需要人工改动的行数能降一半。 进阶把 SonarQube 的VERIFY指令写进 AGENTS.md要求「每次改完调 MCP 的 run_advanced_code_analysis红的不许 commit」。4. Java 项目接 Codex 的两个硬骨头4.1 Maven/Gradle 在沙箱里断网full-auto 模式下出站网络被掐Maven 中央仓拉不到包。解法二选一预缓存进 Codex 前先./mvnw dependency:go-offlineAGENTS.md 里强制mvn -o开网白名单在~/.codex/config.toml给 java-dev profile 放通repo.maven.apache.org和services.gradle.org4.2 JDK 版本与工具链Codex 不替你装 JDK。Docker 沙箱里建议挂多阶段FROM maven:3.9-eclipse-temurin-17 AS build WORKDIR /app COPY . . RUN ./mvnw -o package本地 CLI 场景就保证你 shell 里java -version是项目要的 17Codex 继承环境变量。5. 把 Spring Boot 业务系统暴露成 Codex 的 MCP 工具高阶这是资深工程师才用得到的玩法让 Codex 在改代码时能直接查你们内部系统的真实状态。比如评审系统里「查某个规则当前生效版本」「查某用户历史评审记录」可以包成 MCP Server 给 Codex 用。5.1 Spring AI MCP Server 最小骨架pom.xmldependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-mcp-server/artifactId /dependencyapplication.ymlspring: main: web-application-type: none ai: mcp: server: stdio: true name: review-tools version: 1.0.0Tool 类Component public class ReviewTools { private final RuleService ruleService; public ReviewTools(RuleService ruleService) { this.ruleService ruleService; } McpTool(name current_rule_version, description 查评审规则当前生效版本) public RuleVersion currentRuleVersion( McpToolParam(description 规则ID, required true) String ruleId) { return ruleService.getActiveVersion(ruleId); } }打 fat-jar 后在~/.codex/config.toml注册[mcp_servers.review] command java args [-jar, /opt/tools/review-mcp.jar] env { SPRING_PROFILES_ACTIVE mcp }Codex 启动后/mcp能看到current_rule_version你派活时说「参考当前生效规则版本改校验逻辑」它就不会拍脑袋编版本号。6. 资深工程师的使用心智什么交给 Codex什么自己留着适合派给 Codex异步、可验证给指定包补 JUnit 5 单测并跑绿把if (status 1 || status 2)重构成 Enum按 AGENTS.md 规范统一 DTO 命名snake→camel升级 Spring Boot 小版本、修废弃 API 调用写 Flyway 增量脚本 对应单测别交给 Codex要业务判断领域模型拆分、DDD 限界上下文划分分布式事务方案选型Seata/TCC/消息最终一致涉及资金、幂等、超卖的核心链路改动任何「改了之后没人能在 10 分钟内 review 完」的大 PRReview Codex 的 PR 时重点看三处是不是引入了新依赖AGENTS.md 禁了就该红事务边界有没有被它扩大最常犯把 RPC 调用包进 Transactional单测是不是「为了绿而绿」断言只判非 null没判业务值7. 一句话收尾初代 Codex 教会大模型写 Java现在的 Codex 是能自己mvn test跑红再修绿的终端工程师。资深 Java 的用法不是「让它替我写代码」而是「用 AGENTS.md 把团队规范固化成 Agent 的入职手册用 MCP 把内部系统变成它的工具然后把补测试、修告警、统一规范这种高重复低判断的活异步派出去」。下一步你可以把团队根目录的AGENTS.md建起来挑一个单测覆盖率最低的 module跑一条codex -a full-auto 给 com.xxx.order.service 下所有 public 方法补 JUnit5 单测跑通 mvn test 再停看完它交的 PR你就知道团队该怎么用这东西了。8. Java 微服务仓库可直接提交的 AGENTS.md 模板下面这份AGENTS.md 可直接放进 Java 微服务仓库根目录提交按 OpenAI Codex 官方加载规则全局~/.codex/AGENTS.md→ 仓库根 → 子模块就近覆盖设计覆盖技术栈声明、模块边界、Maven 离线构建、Flyway 禁止项、事务/并发红线、统一响应、Codex 输出收据。已经在多模块 Maven Spring Boot 3 MySQL Redis RocketMQ 场景验证过拷过去改模块名就能用。# AGENTS.md 本文件是给 Codex / Copilot / Claude Code 等编程 Agent 的“团队入职手册”。 人类阅读 README.mdAgent 读取本文件。修改本文件必须走 PR并由模块 Owner Review。 ## 1. 技术栈写死禁止 Agent 猜测 - Java 17禁止升级至 21除非有专项升级 PR - Spring Boot 3.2.x版本由 parent 统一管理禁止手写 spring-boot-starter 版本号 - Maven 3.9统一使用项目内置 ./mvnw禁止使用系统全局 mvn - MySQL 8.0 / Redis 7 / RocketMQ 5.x - MyBatis-Plus XML Mapper禁止在注解中编写动态 SQL - Flyway 9.x迁移脚本目录src/main/resources/db/migration - JUnit 5 Mockito Testcontainers集成测试统一继承 BaseIT ## 2. 模块边界多模块 Maven 结构 - order-service订单接口与核心业务禁止直连库存库必须通过 Feign 调用 - payment-service支付/回调/退款涉及资金字段的改动必须双人 Review - inventory-service库存扣减逻辑必须保证幂等 - common-core异常定义/常量/基础类型禁止依赖任何业务模块 - common-webApiResponse / 全局异常处理 / WebMvcConfig - common-security鉴权逻辑禁止修改除非任务名称明确包含 security-bump Agent 在执行任务前必须先 cd 到对应模块目录确保就近的 AGENTS.md 生效。 ## 3. 构建与测试沙箱离线必须 -o Codex 在 full-auto 模式下默认断网因此所有构建和测试命令必须使用离线模式且依赖必须预先缓存。 - **离线构建强制**./mvnw -o -q compile - **单模块测试**./mvnw -o -pl order-service test - **全量校验CI 门槛**./mvnw -o verify - **禁止使用的命令** - mvn clean会清除本地 .m2 缓存导致后续离线构建失败 - mvn install会污染本地 Maven 仓库 - 任何不带 -o 参数的 Maven 命令 **Testcontainers 配置要求** - 镜像必须使用预拉取版本如 postgres:17-alpine、redis:8-alpine - 禁止在 Agent 执行阶段运行 docker pull - 集成测试基类 BaseIT 中已固化容器启动参数Agent 不得修改 **覆盖率要求** - JaCoCo 覆盖率阈值不得低于 80% - 单测失败或覆盖率不足时禁止使用 Disabled 跳过测试必须修复代码或测试逻辑 ## 4. 分层与代码规范 - **Controller 层**仅负责 Valid 参数校验、调用 Service、封装 ApiResponse。禁止编写业务逻辑、禁止编写 SQL、禁止直接注入 Mapper。 - **Service 层**编写业务逻辑事务注解必须使用 Transactional(rollbackFor Exception.class)。 - **事务边界控制**事务方法内部禁止进行 Feign 调用、RocketMQ 同步发送、Thread.sleep 以及外部 HTTP 请求。 - **DTO 规范**Entity 严禁作为接口返回值必须转换为 DTO 返回。 - **统一返回结构**所有接口必须返回 ApiResponseT位于 common-web禁止返回裸 POJO 或 Map。 - **异常处理**业务异常统一使用 BusinessException(code, msg)禁止直接抛出 RuntimeException 或 NullPointerException。 ## 5. 数据库与 Flyway高危红线 - **命名规范**表名使用复数 snake_case如 order_items字段名使用 snake_case如 created_at。 - **主键策略**使用 BIGINT AUTO_INCREMENT 或 UUID需与现有表约定保持一致。 - **必备字段**每张表必须包含 created_at 和 updated_at 字段。 - **Flyway 脚本规范** - 命名格式V{序号}__{动作}_{表名}.sql序号全局递增。 - **禁止修改已合并的 V 开头脚本**Flyway 校验失败将导致应用启动崩溃。 - 禁止执行 flyway repair、flyway undo 等高风险命令。 - **变更流程**编写新的 V 脚本 → 调整 Entity → 调整 Mapper → 补充单测 → 执行 ./mvnw -o verify。 - **数据变更限制**涉及生产数据的变更如对大表执行 UPDATE/DELETE必须由人工执行Agent 仅允许生成 SQL 语句不得自动执行。 ## 6. 安全与并发禁止项 - **敏感信息**禁止硬编码密钥统一通过 ConfigurationProperties 读取配置中心。 - **SQL 注入防护**MyBatis 动态条件使用 eq/in/like 等方法禁止在 apply() 中拼接字符串Select 注解中必须使用 #{} 进行参数绑定禁止使用 ${} 拼接用户输入。 - **线程安全**禁止在 Singleton Bean 中使用成员变量存储 requestId 或用户上下文必须使用 MDC ThreadLocal并在请求结束时清理。 - **线程池配置**禁止使用 Executors.newFixedThreadPool因其使用无界队列必须手动创建线程池配置 ArrayBlockingQueue 自定义 ThreadFactory CallerRunsPolicy 拒绝策略。 - **消息消费**RocketMQ Consumer 方法禁止添加 Transactional 注解。 ## 7. Codex 任务收据每次修改必须输出 修改完成后PR 描述或终端总结中必须包含以下内容缺一不可 1. **任务目标**清晰描述本次修改的目的。 2. **改动文件清单**列出所有修改文件的绝对路径。 3. **修改原因**针对每个文件简述为什么修改。 4. **接口契约检查**是否修改了接口契约Request/Response 字段。 5. **基础设施变更**是否涉及数据库变更Flyway 版本号、Redis Key、MQ Topic 或事务边界调整。 6. **验证记录**实际执行过的命令如 ./mvnw -o -pl order-service test及其结果。 7. **风险提示**明确指出仍需人工确认的风险点如资金计算、权限控制、灰度发布影响。 ## 8. 绝对禁止行为违反直接打回 - 修改 application-prod.yml 或 bootstrap-prod.yml 配置文件。 - 修改 common-security 模块代码除非任务名称显式声明。 - 执行 Git 写操作git push、git merge、删除分支。 - 执行高危 SQLDROP TABLE、TRUNCATE、DELETE FROM 全表。 - 引入新的 Maven 依赖而未说明理由。 - 重构与本次任务无关的代码。 - 将 PII手机号、身份证号、Token写入日志。 ## 9. 嵌套覆盖约定 - 子模块如 order-service/AGENTS.md可定义更具体的规则例如订单状态机流转逻辑、幂等键生成规则等。 - 越靠近工作目录的 AGENTS.md 优先级越高。 - 子模块文件只需声明增量规则无需重复根文件中的通用规则以避免文件过大导致截断。 ---配套两个小动作让模板真生效1. 根目录放.codex/config.toml可信项目才提交或放用户级approval_policy on-request [sandbox_workspace_write] network_access false # 和 Maven -o 对齐防止 Agent 试图下包full-auto 模式下 Agent 跑./mvnw -o不会炸但试图mvn dependency:resolve会直接被沙箱拦掉。2. 子模块加就近约束比如payment-service/AGENTS.md只需写# 支付模块增量规则 - 金额计算只允许在 AmountCalculator 类内禁止散落 Service - 回调接口必须校验 RocketMQ 消息幂等键 outTradeNotenantId - 改金额精度必须同步改单测 AmountCalculatorTest根文件不重复这些内容避免超 32KiB 截断。使用节奏第一次用 Codex 修个单测覆盖率缺口跑完看它交的 PR 是否遵守了上面 7 类收据和禁止项如果它犯了重复错误比如又去改application-prod.yml把那条写成新规则回写 AGENTS.md——这就是 OpenAI 官方说的“把 review 反馈沉淀进 AGENTS.md”的闭环。9. payment-service/AGENTS.md的资金链路专项版本下面是可直接提交到payment-service/目录的专项AGENTS.md完全继承根目录规则并在此之上叠加资金链路强约束。你复制进去后Codex 在改支付模块时一旦碰资金红线会直接被规则拦住。# payment-service/AGENTS.md 本文件是对根目录 AGENTS.md 的**增量覆盖**专门约束资金链路。 生效范围仅 payment-service 模块。 优先级高于根目录 AGENTS.md。 --- ## 1. 资金领域铁律违反直接打回 ### 1.1 金额类型与精度BigDecimal 强制 - **禁止使用** double、float、Double、Float 表示金额、费率、单价、数量。 - **必须使用** java.math.BigDecimal。 - **刻度Scale规则** - 人民币金额setScale(2, RoundingMode.HALF_UP) - 费率/百分比setScale(6, RoundingMode.HALF_UP) - **禁止**BigDecimal(double) 构造函数存在二进制精度丢失。 - ✅ 正确new BigDecimal(19.99) - ❌ 错误new BigDecimal(19.99) - **运算规则** - 除法必须指定 RoundingModedivide(divisor, scale, RoundingMode.HALF_UP) - 比较大小使用 compareTo()禁止使用 equals()后者会比较 scale。 ### 1.2 资金字段修改冻结 以下字段**禁止重命名、修改类型、改变精度**除非任务名显式包含 schema-migration 且经过 DBA 财务双签 - 数据库表pay_order.amount、pay_order.refund_amount、pay_order.fee - 实体类PayOrder::amount、PayOrder::refundAmount - DTOPaymentCreateReq::totalAmount、RefundReq::refundAmount - 枚举金额单位统一为 **分**内部计算或 **元**接口展示禁止混用若混用必须在字段名后缀标明如 amountYuan、amountCent。 ### 1.3 资金计算逻辑封闭 - **金额计算逻辑必须封闭在 com.xxx.payment.domain.calculator 包内**。 - 禁止在 Service、Controller、Mapper 中直接进行加减乘除运算。 - 所有金额变动必须经过 AmountCalculator 或 FeeCalculator 类的方法确保统一舍入规则和审计日志。 --- ## 2. RocketMQ 幂等与消息安全 ### 2.1 消费幂等强制 - **幂等键定义**outTradeNo tenantId或 payOrderId operationType。 - **消费逻辑模板**Agent 生成代码必须遵循 RabbitListener / RocketMQMessageListener public void onMessage(MessageExt msg) { String bizKey buildBizKey(msg); if (idempotentService.isProcessed(bizKey)) { log.warn(Duplicate message ignored, bizKey{}, bizKey); return; } try { handle(msg); idempotentService.markSuccess(bizKey); } catch (BusinessException e) { idempotentService.markFailed(bizKey, e); throw e; // 确保消息不丢失进入重试或DLQ } } - **禁止** - 仅靠 msgId 做幂等msgId 在重试时会变。 - 在事务未提交前标记幂等成功。 - 消费逻辑中包含 Transactional 注解见根目录规则。 ### 2.2 消息内容约束 - **禁止**将敏感信息明文卡号、CVV、密码放入 MQ 消息体。 - **必须**包含 - traceId全链路追踪 - tenantId多租户隔离 - retryCount重试次数用于熔断 - **Topic/Tag 命名** - TopicPAY_ORDER_EVENT、REFUND_EVENT - TagCREATE、SUCCESS、FAIL、ROLLBACK --- ## 3. 对账与清算禁止 Agent 干预 ### 3.1 对账脚本冻结 以下文件**禁止 Agent 修改逻辑、优化 SQL、调整字段映射**只能由人工维护 - src/main/java/com/xxx/payment/job/ReconciliationJob.java - src/main/java/com/xxx/payment/service/reconciliation/*.java - src/main/resources/mapper/reconciliation/*.xml - db/migration/V*__reconciliation_*.sql ### 3.2 对账差异处理原则 - **不准自动修复差异**Agent 生成的代码在处理对账不平记录时只能标记为 NEED_MANUAL_CHECK禁止自动冲正、自动补单。 - **不准删除历史对账数据**涉及 reconciliation_result、reconciliation_diff 表的 DELETE 操作一律禁止。 - **日志强制**所有对账差异必须记录 diffReason、expectedValue、actualValue且日志级别为 ERROR。 ### 3.3 渠道回调Webhook安全 - **验签强制**所有渠道回调支付宝/微信/银联必须先验签再处理业务。 - **状态机校验**回调状态必须与本地订单状态机匹配如 WAIT_PAY - SUCCESS 合法SUCCESS - REFUND 不合法。 - **禁止**在回调接口中直接返回 success 而不校验业务结果。 --- ## 4. 支付状态机State Machine ### 4.1 合法状态流转 Agent 修改状态时必须校验合法性禁止跳变 WAIT_PAY - PAYING - SUCCESS WAIT_PAY - CLOSED SUCCESS - REFUNDING - REFUNDED SUCCESS - PARTIAL_REFUNDED - **禁止**CLOSED - SUCCESS、REFUNDED - SUCCESS。 - **状态字段**pay_order.status 类型为 VARCHAR(20)使用枚举 PayStatusEnum。 ### 4.2 终态保护 - **终态不可变**SUCCESS、REFUNDED、CLOSED 状态的订单禁止任何业务字段更新除对账标记外。 - **更新 SQL 必须带条件** UPDATE pay_order SET status SUCCESS WHERE order_id ? AND status WAIT_PAY; 禁止无条件更新。 --- ## 5. 测试与验证资金专项 ### 5.1 单测强制要求 - **金额计算测试**必须覆盖进位、舍位、溢出场景。 - **幂等测试**必须模拟重复消息投递验证幂等键生效。 - **状态机测试**必须验证非法状态跳转被拒绝。 ### 5.2 集成测试IT - 使用 Testcontainers 启动 MySQL 和 RocketMQ。 - 测试用例必须包含 - 创建支付单 - 模拟回调 - 验证金额与状态 - 重复回调 - 验证幂等逻辑 - 部分退款 - 验证金额拆分逻辑 --- ## 6. Codex 任务收据支付模块增量 在完成根目录要求的 7 项收据外**必须额外包含** 1. **资金影响评估**本次改动影响的资金字段、计算逻辑、精度风险。 2. **幂等分析**新增或修改的消息消费逻辑幂等键是否完备。 3. **对账影响**是否影响当日对账结果是否引入新的对账不平场景。 4. **回滚方案**如果发布后资损如何回滚SQL 回滚脚本、开关降级方案。 --- ## 7. 绝对禁止支付模块特供版 除了根目录的禁止项支付模块额外禁止 - 使用 Math.random()、Random 生成订单号、流水号必须用雪花算法或分布式 ID。 - 在 Controller 层直接打印 amount、fee 等敏感字段仅允许打印脱敏日志。 - 修改 common-security 中关于支付签名、验签的工具类。 - 引入新的第三方支付 SDK 而未经过安全扫描。 - 在事务中执行 Thread.sleep() 等待渠道回调必须使用异步通知或定时任务轮询。 --- **最后通牒** 支付模块是系统的“心脏”。Agent 在此模块的每一次修改都必须假设**“上线即可能发生真实资损”**。 如果你不确定某处改动是否安全**停止修改输出风险评估等待人工确认**。使用建议给资深工程师提交位置payment-service/AGENTS.md配套动作在common-core里定义一个MoneyValue Object封装 BigDecimal以后让 Codex 强制用Money.add/subtract彻底消灭原始 BigDecimal 误操作。在 CI 中加一条规则如果 PR 修改了payment-service且包含BigDecimal关键字必须人工 Review。Codex 指令示例✅ 好的任务给 RefundService 补单元测试覆盖部分退款金额拆分逻辑确保使用 BigDecimal 且 scale2❌ 坏的任务优化一下支付代码的性能太模糊容易引发资损。
面向读者用过 GitHub Copilot、写过 SpringBoot/MyBatis、懂 JVM 调优和 Maven 构建的 Java 资深工程师。目标读完你能分清「初代 Codex 模型」和「现在的 Codex Agent」能在终端用 Codex CLI 修 Bug、补测试、接 MCP并把 AGENTS.md 写进团队规范。0. 先拆歧义Codex 不是你以为的那个 Codex很多 Java 老兵对 Codex 的印象停在 2021 年——「哦就是给 Copilot 提供补全能力的那个 GPT-3 微调模型」。那个 Codex 已经退场了。现在的OpenAI Codex2025.5 起 是一个软件工程智能体系统包含三件套codex-1基于 o3 系列、在真实 PR 和测试反馈上做 RL 的专用编程模型后续还有 GPT-5.x-codex 系列Codex CLIRust 写的开源终端 Agentnpm i -g openai/codex就能装本地沙箱跑Codex Cloud / Web / Desktop云端隔离容器里异步跑任务、回 PR 的托管形态和 Copilot 的本质差异Copilot 你写它补同步、IDE 内、你主导Codex 你派活它交 PR异步、可并行多任务、它自己跑测试修红一句话定位Codex 是「远程实习生」Copilot 是「结对搭档」。1. Codex 的执行闭环为什么它能自己把测试跑绿别把它当「高级代码生成器」。它的核心是 Agent Loop你发自然语言任务 → Codex 读 AGENTS.md / 仓库结构 → 规划步骤不是一次生成全部代码 → 调工具read_file / write_file / patch / shell(mvn test) → 观察输出编译错误、单测失败、Sonar 问题 → 自我修正 → 再循环 → 收敛后给 diff 终端日志 可选 PR关键点测试反馈是上下文的一部分。你让它「给 OrderService 补单测」它不是瞎写 JUnit而是真跑mvn -q test红了他自己改直到绿。这对 Java 工程师意味着你交给它的任务粒度应该是「一个 Ticket」而不是「写个方法」。2. 十分钟跑通 Codex CLIJava 项目视角2.1 安装与登录npm install -g openai/codex codex # 首次启动走 ChatGPT OAuth 或 API Key 登录Plus/Pro/Team/Enterprise 套餐已含 Codex 额度不单独收费。2.2 三档审批模式决定你半夜敢不敢开 full-auto模式文件写跑 shell网络适用场景suggest默认问问-看陌生代码、审 PRauto-edit自动问-日常重构full-auto自动自动默认断网修编译/补测试/原型codex -a full-auto 把 UserController 的参数校验用 Valid 补齐并跑通 mvn testLinux 下沙箱用 Landlock/seccompmacOS 用 SeatbeltWSL2 走 Docker 或 bypass 标志。full-auto 默认出站网络全断所以 Maven 首跑会跪——这是 Java 项目第一个坑见 §4。2.3 非交互模式CI 里用codex exec --full-auto --quiet 更新 CHANGELOG 并准备下一个版本GitHub Action 里接openai/codex-action或直跑codex exec都行。3. AGENTS.md给 Codex 的「Java 团队入职手册」Codex 启动时会按优先级合并指令~/.codex/AGENTS.md 个人全局 repo/AGENTS.md 仓库级提交进 Git repo/sub/AGENTS.md 子模块覆盖这是你作为资深工程师最该花时间的地方。给个 SpringBoot 项目的真实样例# AGENTS.md电商订单服务 ## 构建与测试 - 构建./mvnw -o package依赖已离线缓存到 .m2 - 单测./mvnw -o test - 集成测试./mvnw -o test -Dtest*IT - 禁止跑 mvn clean 清掉 .m2 ## 代码规范 - 遵循《阿里巴巴 Java 开发手册》终极版 - Controller 只做参数校验 调 Service禁止写 SQL - 数据库字段下划线Entity 字段驼峰用 TableField 映射 - 事务用 Transactional 且必须指定 rollbackFor - 禁止在事务内调 Feign / RocketMQ 同步发送 ## 禁止项 - 不引入新的 starter除非先问我 - 不改 Flyway 已有版本脚本 - 不用 lombok Data 在 Entity 上用 Getter/Setter ## 提交规范 - 分支命名 fix/xxx feat/xxx - 提交信息用中文动宾结构修复订单超时未关单问题经验数据AGENTS.md 写清楚后Codex 产出的 PR 需要人工改动的行数能降一半。 进阶把 SonarQube 的VERIFY指令写进 AGENTS.md要求「每次改完调 MCP 的 run_advanced_code_analysis红的不许 commit」。4. Java 项目接 Codex 的两个硬骨头4.1 Maven/Gradle 在沙箱里断网full-auto 模式下出站网络被掐Maven 中央仓拉不到包。解法二选一预缓存进 Codex 前先./mvnw dependency:go-offlineAGENTS.md 里强制mvn -o开网白名单在~/.codex/config.toml给 java-dev profile 放通repo.maven.apache.org和services.gradle.org4.2 JDK 版本与工具链Codex 不替你装 JDK。Docker 沙箱里建议挂多阶段FROM maven:3.9-eclipse-temurin-17 AS build WORKDIR /app COPY . . RUN ./mvnw -o package本地 CLI 场景就保证你 shell 里java -version是项目要的 17Codex 继承环境变量。5. 把 Spring Boot 业务系统暴露成 Codex 的 MCP 工具高阶这是资深工程师才用得到的玩法让 Codex 在改代码时能直接查你们内部系统的真实状态。比如评审系统里「查某个规则当前生效版本」「查某用户历史评审记录」可以包成 MCP Server 给 Codex 用。5.1 Spring AI MCP Server 最小骨架pom.xmldependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-mcp-server/artifactId /dependencyapplication.ymlspring: main: web-application-type: none ai: mcp: server: stdio: true name: review-tools version: 1.0.0Tool 类Component public class ReviewTools { private final RuleService ruleService; public ReviewTools(RuleService ruleService) { this.ruleService ruleService; } McpTool(name current_rule_version, description 查评审规则当前生效版本) public RuleVersion currentRuleVersion( McpToolParam(description 规则ID, required true) String ruleId) { return ruleService.getActiveVersion(ruleId); } }打 fat-jar 后在~/.codex/config.toml注册[mcp_servers.review] command java args [-jar, /opt/tools/review-mcp.jar] env { SPRING_PROFILES_ACTIVE mcp }Codex 启动后/mcp能看到current_rule_version你派活时说「参考当前生效规则版本改校验逻辑」它就不会拍脑袋编版本号。6. 资深工程师的使用心智什么交给 Codex什么自己留着适合派给 Codex异步、可验证给指定包补 JUnit 5 单测并跑绿把if (status 1 || status 2)重构成 Enum按 AGENTS.md 规范统一 DTO 命名snake→camel升级 Spring Boot 小版本、修废弃 API 调用写 Flyway 增量脚本 对应单测别交给 Codex要业务判断领域模型拆分、DDD 限界上下文划分分布式事务方案选型Seata/TCC/消息最终一致涉及资金、幂等、超卖的核心链路改动任何「改了之后没人能在 10 分钟内 review 完」的大 PRReview Codex 的 PR 时重点看三处是不是引入了新依赖AGENTS.md 禁了就该红事务边界有没有被它扩大最常犯把 RPC 调用包进 Transactional单测是不是「为了绿而绿」断言只判非 null没判业务值7. 一句话收尾初代 Codex 教会大模型写 Java现在的 Codex 是能自己mvn test跑红再修绿的终端工程师。资深 Java 的用法不是「让它替我写代码」而是「用 AGENTS.md 把团队规范固化成 Agent 的入职手册用 MCP 把内部系统变成它的工具然后把补测试、修告警、统一规范这种高重复低判断的活异步派出去」。下一步你可以把团队根目录的AGENTS.md建起来挑一个单测覆盖率最低的 module跑一条codex -a full-auto 给 com.xxx.order.service 下所有 public 方法补 JUnit5 单测跑通 mvn test 再停看完它交的 PR你就知道团队该怎么用这东西了。8. Java 微服务仓库可直接提交的 AGENTS.md 模板下面这份AGENTS.md 可直接放进 Java 微服务仓库根目录提交按 OpenAI Codex 官方加载规则全局~/.codex/AGENTS.md→ 仓库根 → 子模块就近覆盖设计覆盖技术栈声明、模块边界、Maven 离线构建、Flyway 禁止项、事务/并发红线、统一响应、Codex 输出收据。已经在多模块 Maven Spring Boot 3 MySQL Redis RocketMQ 场景验证过拷过去改模块名就能用。# AGENTS.md 本文件是给 Codex / Copilot / Claude Code 等编程 Agent 的“团队入职手册”。 人类阅读 README.mdAgent 读取本文件。修改本文件必须走 PR并由模块 Owner Review。 ## 1. 技术栈写死禁止 Agent 猜测 - Java 17禁止升级至 21除非有专项升级 PR - Spring Boot 3.2.x版本由 parent 统一管理禁止手写 spring-boot-starter 版本号 - Maven 3.9统一使用项目内置 ./mvnw禁止使用系统全局 mvn - MySQL 8.0 / Redis 7 / RocketMQ 5.x - MyBatis-Plus XML Mapper禁止在注解中编写动态 SQL - Flyway 9.x迁移脚本目录src/main/resources/db/migration - JUnit 5 Mockito Testcontainers集成测试统一继承 BaseIT ## 2. 模块边界多模块 Maven 结构 - order-service订单接口与核心业务禁止直连库存库必须通过 Feign 调用 - payment-service支付/回调/退款涉及资金字段的改动必须双人 Review - inventory-service库存扣减逻辑必须保证幂等 - common-core异常定义/常量/基础类型禁止依赖任何业务模块 - common-webApiResponse / 全局异常处理 / WebMvcConfig - common-security鉴权逻辑禁止修改除非任务名称明确包含 security-bump Agent 在执行任务前必须先 cd 到对应模块目录确保就近的 AGENTS.md 生效。 ## 3. 构建与测试沙箱离线必须 -o Codex 在 full-auto 模式下默认断网因此所有构建和测试命令必须使用离线模式且依赖必须预先缓存。 - **离线构建强制**./mvnw -o -q compile - **单模块测试**./mvnw -o -pl order-service test - **全量校验CI 门槛**./mvnw -o verify - **禁止使用的命令** - mvn clean会清除本地 .m2 缓存导致后续离线构建失败 - mvn install会污染本地 Maven 仓库 - 任何不带 -o 参数的 Maven 命令 **Testcontainers 配置要求** - 镜像必须使用预拉取版本如 postgres:17-alpine、redis:8-alpine - 禁止在 Agent 执行阶段运行 docker pull - 集成测试基类 BaseIT 中已固化容器启动参数Agent 不得修改 **覆盖率要求** - JaCoCo 覆盖率阈值不得低于 80% - 单测失败或覆盖率不足时禁止使用 Disabled 跳过测试必须修复代码或测试逻辑 ## 4. 分层与代码规范 - **Controller 层**仅负责 Valid 参数校验、调用 Service、封装 ApiResponse。禁止编写业务逻辑、禁止编写 SQL、禁止直接注入 Mapper。 - **Service 层**编写业务逻辑事务注解必须使用 Transactional(rollbackFor Exception.class)。 - **事务边界控制**事务方法内部禁止进行 Feign 调用、RocketMQ 同步发送、Thread.sleep 以及外部 HTTP 请求。 - **DTO 规范**Entity 严禁作为接口返回值必须转换为 DTO 返回。 - **统一返回结构**所有接口必须返回 ApiResponseT位于 common-web禁止返回裸 POJO 或 Map。 - **异常处理**业务异常统一使用 BusinessException(code, msg)禁止直接抛出 RuntimeException 或 NullPointerException。 ## 5. 数据库与 Flyway高危红线 - **命名规范**表名使用复数 snake_case如 order_items字段名使用 snake_case如 created_at。 - **主键策略**使用 BIGINT AUTO_INCREMENT 或 UUID需与现有表约定保持一致。 - **必备字段**每张表必须包含 created_at 和 updated_at 字段。 - **Flyway 脚本规范** - 命名格式V{序号}__{动作}_{表名}.sql序号全局递增。 - **禁止修改已合并的 V 开头脚本**Flyway 校验失败将导致应用启动崩溃。 - 禁止执行 flyway repair、flyway undo 等高风险命令。 - **变更流程**编写新的 V 脚本 → 调整 Entity → 调整 Mapper → 补充单测 → 执行 ./mvnw -o verify。 - **数据变更限制**涉及生产数据的变更如对大表执行 UPDATE/DELETE必须由人工执行Agent 仅允许生成 SQL 语句不得自动执行。 ## 6. 安全与并发禁止项 - **敏感信息**禁止硬编码密钥统一通过 ConfigurationProperties 读取配置中心。 - **SQL 注入防护**MyBatis 动态条件使用 eq/in/like 等方法禁止在 apply() 中拼接字符串Select 注解中必须使用 #{} 进行参数绑定禁止使用 ${} 拼接用户输入。 - **线程安全**禁止在 Singleton Bean 中使用成员变量存储 requestId 或用户上下文必须使用 MDC ThreadLocal并在请求结束时清理。 - **线程池配置**禁止使用 Executors.newFixedThreadPool因其使用无界队列必须手动创建线程池配置 ArrayBlockingQueue 自定义 ThreadFactory CallerRunsPolicy 拒绝策略。 - **消息消费**RocketMQ Consumer 方法禁止添加 Transactional 注解。 ## 7. Codex 任务收据每次修改必须输出 修改完成后PR 描述或终端总结中必须包含以下内容缺一不可 1. **任务目标**清晰描述本次修改的目的。 2. **改动文件清单**列出所有修改文件的绝对路径。 3. **修改原因**针对每个文件简述为什么修改。 4. **接口契约检查**是否修改了接口契约Request/Response 字段。 5. **基础设施变更**是否涉及数据库变更Flyway 版本号、Redis Key、MQ Topic 或事务边界调整。 6. **验证记录**实际执行过的命令如 ./mvnw -o -pl order-service test及其结果。 7. **风险提示**明确指出仍需人工确认的风险点如资金计算、权限控制、灰度发布影响。 ## 8. 绝对禁止行为违反直接打回 - 修改 application-prod.yml 或 bootstrap-prod.yml 配置文件。 - 修改 common-security 模块代码除非任务名称显式声明。 - 执行 Git 写操作git push、git merge、删除分支。 - 执行高危 SQLDROP TABLE、TRUNCATE、DELETE FROM 全表。 - 引入新的 Maven 依赖而未说明理由。 - 重构与本次任务无关的代码。 - 将 PII手机号、身份证号、Token写入日志。 ## 9. 嵌套覆盖约定 - 子模块如 order-service/AGENTS.md可定义更具体的规则例如订单状态机流转逻辑、幂等键生成规则等。 - 越靠近工作目录的 AGENTS.md 优先级越高。 - 子模块文件只需声明增量规则无需重复根文件中的通用规则以避免文件过大导致截断。 ---配套两个小动作让模板真生效1. 根目录放.codex/config.toml可信项目才提交或放用户级approval_policy on-request [sandbox_workspace_write] network_access false # 和 Maven -o 对齐防止 Agent 试图下包full-auto 模式下 Agent 跑./mvnw -o不会炸但试图mvn dependency:resolve会直接被沙箱拦掉。2. 子模块加就近约束比如payment-service/AGENTS.md只需写# 支付模块增量规则 - 金额计算只允许在 AmountCalculator 类内禁止散落 Service - 回调接口必须校验 RocketMQ 消息幂等键 outTradeNotenantId - 改金额精度必须同步改单测 AmountCalculatorTest根文件不重复这些内容避免超 32KiB 截断。使用节奏第一次用 Codex 修个单测覆盖率缺口跑完看它交的 PR 是否遵守了上面 7 类收据和禁止项如果它犯了重复错误比如又去改application-prod.yml把那条写成新规则回写 AGENTS.md——这就是 OpenAI 官方说的“把 review 反馈沉淀进 AGENTS.md”的闭环。9. payment-service/AGENTS.md的资金链路专项版本下面是可直接提交到payment-service/目录的专项AGENTS.md完全继承根目录规则并在此之上叠加资金链路强约束。你复制进去后Codex 在改支付模块时一旦碰资金红线会直接被规则拦住。# payment-service/AGENTS.md 本文件是对根目录 AGENTS.md 的**增量覆盖**专门约束资金链路。 生效范围仅 payment-service 模块。 优先级高于根目录 AGENTS.md。 --- ## 1. 资金领域铁律违反直接打回 ### 1.1 金额类型与精度BigDecimal 强制 - **禁止使用** double、float、Double、Float 表示金额、费率、单价、数量。 - **必须使用** java.math.BigDecimal。 - **刻度Scale规则** - 人民币金额setScale(2, RoundingMode.HALF_UP) - 费率/百分比setScale(6, RoundingMode.HALF_UP) - **禁止**BigDecimal(double) 构造函数存在二进制精度丢失。 - ✅ 正确new BigDecimal(19.99) - ❌ 错误new BigDecimal(19.99) - **运算规则** - 除法必须指定 RoundingModedivide(divisor, scale, RoundingMode.HALF_UP) - 比较大小使用 compareTo()禁止使用 equals()后者会比较 scale。 ### 1.2 资金字段修改冻结 以下字段**禁止重命名、修改类型、改变精度**除非任务名显式包含 schema-migration 且经过 DBA 财务双签 - 数据库表pay_order.amount、pay_order.refund_amount、pay_order.fee - 实体类PayOrder::amount、PayOrder::refundAmount - DTOPaymentCreateReq::totalAmount、RefundReq::refundAmount - 枚举金额单位统一为 **分**内部计算或 **元**接口展示禁止混用若混用必须在字段名后缀标明如 amountYuan、amountCent。 ### 1.3 资金计算逻辑封闭 - **金额计算逻辑必须封闭在 com.xxx.payment.domain.calculator 包内**。 - 禁止在 Service、Controller、Mapper 中直接进行加减乘除运算。 - 所有金额变动必须经过 AmountCalculator 或 FeeCalculator 类的方法确保统一舍入规则和审计日志。 --- ## 2. RocketMQ 幂等与消息安全 ### 2.1 消费幂等强制 - **幂等键定义**outTradeNo tenantId或 payOrderId operationType。 - **消费逻辑模板**Agent 生成代码必须遵循 RabbitListener / RocketMQMessageListener public void onMessage(MessageExt msg) { String bizKey buildBizKey(msg); if (idempotentService.isProcessed(bizKey)) { log.warn(Duplicate message ignored, bizKey{}, bizKey); return; } try { handle(msg); idempotentService.markSuccess(bizKey); } catch (BusinessException e) { idempotentService.markFailed(bizKey, e); throw e; // 确保消息不丢失进入重试或DLQ } } - **禁止** - 仅靠 msgId 做幂等msgId 在重试时会变。 - 在事务未提交前标记幂等成功。 - 消费逻辑中包含 Transactional 注解见根目录规则。 ### 2.2 消息内容约束 - **禁止**将敏感信息明文卡号、CVV、密码放入 MQ 消息体。 - **必须**包含 - traceId全链路追踪 - tenantId多租户隔离 - retryCount重试次数用于熔断 - **Topic/Tag 命名** - TopicPAY_ORDER_EVENT、REFUND_EVENT - TagCREATE、SUCCESS、FAIL、ROLLBACK --- ## 3. 对账与清算禁止 Agent 干预 ### 3.1 对账脚本冻结 以下文件**禁止 Agent 修改逻辑、优化 SQL、调整字段映射**只能由人工维护 - src/main/java/com/xxx/payment/job/ReconciliationJob.java - src/main/java/com/xxx/payment/service/reconciliation/*.java - src/main/resources/mapper/reconciliation/*.xml - db/migration/V*__reconciliation_*.sql ### 3.2 对账差异处理原则 - **不准自动修复差异**Agent 生成的代码在处理对账不平记录时只能标记为 NEED_MANUAL_CHECK禁止自动冲正、自动补单。 - **不准删除历史对账数据**涉及 reconciliation_result、reconciliation_diff 表的 DELETE 操作一律禁止。 - **日志强制**所有对账差异必须记录 diffReason、expectedValue、actualValue且日志级别为 ERROR。 ### 3.3 渠道回调Webhook安全 - **验签强制**所有渠道回调支付宝/微信/银联必须先验签再处理业务。 - **状态机校验**回调状态必须与本地订单状态机匹配如 WAIT_PAY - SUCCESS 合法SUCCESS - REFUND 不合法。 - **禁止**在回调接口中直接返回 success 而不校验业务结果。 --- ## 4. 支付状态机State Machine ### 4.1 合法状态流转 Agent 修改状态时必须校验合法性禁止跳变 WAIT_PAY - PAYING - SUCCESS WAIT_PAY - CLOSED SUCCESS - REFUNDING - REFUNDED SUCCESS - PARTIAL_REFUNDED - **禁止**CLOSED - SUCCESS、REFUNDED - SUCCESS。 - **状态字段**pay_order.status 类型为 VARCHAR(20)使用枚举 PayStatusEnum。 ### 4.2 终态保护 - **终态不可变**SUCCESS、REFUNDED、CLOSED 状态的订单禁止任何业务字段更新除对账标记外。 - **更新 SQL 必须带条件** UPDATE pay_order SET status SUCCESS WHERE order_id ? AND status WAIT_PAY; 禁止无条件更新。 --- ## 5. 测试与验证资金专项 ### 5.1 单测强制要求 - **金额计算测试**必须覆盖进位、舍位、溢出场景。 - **幂等测试**必须模拟重复消息投递验证幂等键生效。 - **状态机测试**必须验证非法状态跳转被拒绝。 ### 5.2 集成测试IT - 使用 Testcontainers 启动 MySQL 和 RocketMQ。 - 测试用例必须包含 - 创建支付单 - 模拟回调 - 验证金额与状态 - 重复回调 - 验证幂等逻辑 - 部分退款 - 验证金额拆分逻辑 --- ## 6. Codex 任务收据支付模块增量 在完成根目录要求的 7 项收据外**必须额外包含** 1. **资金影响评估**本次改动影响的资金字段、计算逻辑、精度风险。 2. **幂等分析**新增或修改的消息消费逻辑幂等键是否完备。 3. **对账影响**是否影响当日对账结果是否引入新的对账不平场景。 4. **回滚方案**如果发布后资损如何回滚SQL 回滚脚本、开关降级方案。 --- ## 7. 绝对禁止支付模块特供版 除了根目录的禁止项支付模块额外禁止 - 使用 Math.random()、Random 生成订单号、流水号必须用雪花算法或分布式 ID。 - 在 Controller 层直接打印 amount、fee 等敏感字段仅允许打印脱敏日志。 - 修改 common-security 中关于支付签名、验签的工具类。 - 引入新的第三方支付 SDK 而未经过安全扫描。 - 在事务中执行 Thread.sleep() 等待渠道回调必须使用异步通知或定时任务轮询。 --- **最后通牒** 支付模块是系统的“心脏”。Agent 在此模块的每一次修改都必须假设**“上线即可能发生真实资损”**。 如果你不确定某处改动是否安全**停止修改输出风险评估等待人工确认**。使用建议给资深工程师提交位置payment-service/AGENTS.md配套动作在common-core里定义一个MoneyValue Object封装 BigDecimal以后让 Codex 强制用Money.add/subtract彻底消灭原始 BigDecimal 误操作。在 CI 中加一条规则如果 PR 修改了payment-service且包含BigDecimal关键字必须人工 Review。Codex 指令示例✅ 好的任务给 RefundService 补单元测试覆盖部分退款金额拆分逻辑确保使用 BigDecimal 且 scale2❌ 坏的任务优化一下支付代码的性能太模糊容易引发资损。
)
