面向读者：用过 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 Codex（2025.5 起）​ 是一个软件工程智能体系统，包含三件套：

• codex-1：基于 o3 系列、在真实 PR 和测试反馈上做 RL 的专用编程模型（后续还有 GPT-5.x-codex 系列）

• Codex CLI：Rust 写的开源终端 Agent，npm 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 CLI（Java 项目视角）

2.1 安装与登录

npm install -g @openai/codex codex # 首次启动走 ChatGPT OAuth 或 API Key 登录

Plus/Pro/Team/Enterprise 套餐已含 Codex 额度，不单独收费。

2.2 三档审批模式（决定你半夜敢不敢开 full-auto）

codex -a full-auto "把 UserController 的参数校验用 @Valid 补齐并跑通 mvn test"

Linux 下沙箱用 Landlock/seccomp，macOS 用 Seatbelt，WSL2 走 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-offline，AGENTS.md 里强制mvn -o

• 开网白名单：在~/.codex/config.toml给 java-dev profile 放通repo.maven.apache.org和services.gradle.org

4.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是项目要的 17，Codex 继承环境变量。

5. 把 Spring Boot 业务系统暴露成 Codex 的 MCP 工具（高阶）

这是资深工程师才用得到的玩法：让 Codex 在改代码时，能直接查你们内部系统的真实状态。

比如评审系统里「查某个规则当前生效版本」「查某用户历史评审记录」，可以包成 MCP Server 给 Codex 用。

5.1 Spring AI MCP Server 最小骨架

pom.xml：

<dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-starter-mcp-server</artifactId> </dependency>

application.yml：

spring: main: web-application-type: none ai: mcp: server: stdio: true name: review-tools version: 1.0.0

Tool 类：

@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 完」的大 PR

Review Codex 的 PR 时重点看三处：

1. 是不是引入了新依赖（AGENTS.md 禁了就该红）

2. 事务边界有没有被它扩大（最常犯：把 RPC 调用包进 @Transactional）

3. 单测是不是「为了绿而绿」（断言只判非 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.md，Agent 读取本文件。修改本文件必须走 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-web`：ApiResponse / 全局异常处理 / 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 返回。 - **统一返回结构**：所有接口必须返回 `ApiResponse<T>`（位于 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`、删除分支。 - 执行高危 SQL：`DROP 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 消息幂等键 `outTradeNo+tenantId` - 改金额精度必须同步改单测 `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)` - **运算规则**： - 除法必须指定 `RoundingMode`：`divide(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` - DTO：`PaymentCreateReq::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 命名**： - Topic：`PAY_ORDER_EVENT`、`REFUND_EVENT` - Tag：`CREATE`、`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 在此模块的每一次修改，都必须假设**“上线即可能发生真实资损”**。 > 如果你不确定某处改动是否安全，**停止修改，输出风险评估，等待人工确认**。

使用建议（给资深工程师）

1. 提交位置：payment-service/AGENTS.md

2. 配套动作：

   • 在common-core里定义一个MoneyValue Object（封装 BigDecimal），以后让 Codex 强制用Money.add/subtract，彻底消灭原始 BigDecimal 误操作。

   • 在 CI 中加一条规则：如果 PR 修改了payment-service且包含BigDecimal关键字，必须人工 Review。

3. Codex 指令示例：

   • ✅ 好的任务：给 RefundService 补单元测试，覆盖部分退款金额拆分逻辑，确保使用 BigDecimal 且 scale=2；

   • ❌ 坏的任务：优化一下支付代码的性能（太模糊，容易引发资损）。