开场个人观察

刚开始用 Claude Code 时，我最关心的是“到底有哪些命令”。后来用多了才发现，命令本身不是重点，命令背后的工作流才是重点。一个命令如果不知道什么时候用，很快就会变成收藏夹里的知识；只有放到真实开发场景里，才会变成效率。

Claude Code 的命令主要在会话里用 / 触发。官方文档说明，输入 / 可以看到当前环境可用的命令，也可以继续输入字母过滤。需要注意的是，不同平台、计划、版本、登录状态下，可见命令可能不完全一样，所以不要把网上某一份命令清单当成绝对真理。

这篇笔记按开发阶段整理常用命令：项目准备、任务推进、上下文管理、审查发布、排障恢复。每个命令都配一个我会怎么用的场景。

核心观点

Claude Code 的命令可以理解为“会话控制器”。它们不是替代自然语言，而是帮助你快速切换模式、控制上下文、查看改动、管理风险。

我个人最常用的不是最炫的命令，而是这些朴素命令：

/init：新项目第一次接入时生成项目说明。

/plan：复杂任务先进入计划模式，避免直接乱改。

/context：查看上下文占用，判断是不是该压缩或清理。

/compact：长会话继续推进前压缩上下文。

/diff：查看当前文件改动。

/code-review：提交前让 Claude Code 对 diff 做一次审查。

/rewind：方向错了时回退到前面的检查点。

/skills：查看可用 skill，了解当前环境能调用哪些能力。

实践方法

新项目第一步，我会用：

1

/init

它适合生成项目级说明，但生成之后不要直接信。你应该打开生成的说明文件，把真实规则补上去，比如安装命令、测试命令、不要修改的目录、发布流程、代码风格。AI 写的项目记忆如果不校对，后面会把错误规则越用越熟。

遇到稍微复杂一点的任务，我会先用：

1

/plan 给订单列表增加按状态筛选，先不要修改文件

计划模式的意义，是把“要改什么”提前暴露出来。如果计划里出现了明显不相关的文件，或者准备重构过多内容，就可以及时纠正。

会话变长后，我会用：

1

/context

它能帮助你理解上下文被什么占住了。如果一个会话里混了很多无关问题，我通常不会继续硬聊，而是用：

1

/compact 请保留当前任务目标、已修改文件、未完成事项和验证结果

这个写法比单独 /compact 更稳，因为你告诉它压缩时要保留什么。

准备验收时，我会用：

1

/diff

看 diff 是 AI 编程里最重要的习惯之一。不要只看“我改了三个文件，测试通过”这种总结，要看它到底改了什么。

提交前，可以再跑：

1

/code-review

如果是安全敏感、权限、支付、登录、数据删除这类改动，我还会要求更严格的审查，并手工看关键路径。

如果发现方向错了，不要在错误基础上继续补丁叠补丁，可以考虑：

1

/rewind

这类命令的价值，是让错误回退更可控。相比手动在一堆改动里挑挑拣拣，回到清晰检查点通常更干净。

踩坑提醒

第一个提醒：命令要放在消息开头。Claude Code 文档里说明，命令只有在消息开头才会被识别，后面的内容会作为参数传给命令。所以不要写成“请帮我 /plan …”，而应该直接以 /plan 开头。

第二个提醒：不要迷信命令清单。官方文档也提示，不是所有命令都会出现在每个用户环境中。你本机没有某个命令，不一定是你用错了，也可能是版本、平台、计划或环境差异。

第三个提醒：/clear 和 /compact 的用途不同。/compact 适合当前任务还没完，但上下文太长；/clear 更适合换一个新任务。不要为了“清爽”把一个还在推进的任务直接清掉。

第四个提醒：审查命令不能替代人工 review。/code-review 可以帮你发现很多明显问题，但关键业务逻辑、权限边界、数据一致性，仍然需要开发者自己负责。

第五个提醒：不要把 /init 当成一次性动作。项目结构变了、测试命令变了、发布方式变了，都应该更新项目记忆，否则后面 Claude Code 会一直按照旧规则工作。

总结

Claude Code 常用指令可以按一句话记：准备时 /init，复杂任务 /plan，长会话 /context 和 /compact，验收时 /diff 和 /code-review，出问题时 /rewind。

真正提高效率的不是记住更多命令，而是知道什么时候该让工具停下来想、什么时候该让它动手、什么时候必须由人来验收。

参考资料

• Claude Code commands reference
• Claude Code interactive mode
• Claude Code CLI reference

开场个人观察

这几年用 AI 写代码以后，我越来越觉得：Java 项目里真正拉开差距的，不是“让 AI 多写几行代码”，而是“让 AI 在写代码前先把需求理解对”。尤其是订单、库存、结算、报表、权限这类业务系统，表面上只是加一个接口，背后可能牵扯状态机、事务边界、幂等、消息补偿、历史数据兼容和测试数据准备。

更准确地说，OpenSpec 安装完成后，主要使用的是 /opsx:* 这一组命令，而不是单独的 /openspec。常用链路是：/opsx:propose 先提出变更并生成规格，/opsx:apply 按规格实现，/opsx:sync 把变更规格同步回主规格，最后用 /opsx:archive 归档完成的 change。

这篇记录一下我会怎么在 Java 项目里使用 OpenSpec/OPSX，重点是怎么让 /opsx:propose 先匹配项目、怎么写变更输入、怎么检查生成的 artifacts，以及怎么用 /opsx:apply 进入后续编码。

核心观点

Spec Coding 的核心不是“多写文档”，而是把模糊需求变成可验收条件。对 Java 后端项目来说，一个可用的 spec 至少要回答这些问题：

业务目标：这次到底解决哪个业务问题，不解决哪些问题。

项目位置：需求落在哪个服务、哪个模块、哪几类包结构里。

接口变化：新增还是修改接口，请求参数、响应字段、兼容性如何。

数据变化：是否新增表、字段、索引、枚举值，是否涉及历史数据迁移。

流程变化：正常流程、异常流程、回滚流程、补偿流程。

工程约束：权限、幂等、事务、锁、消息、日志、监控、告警。

验收标准：什么场景下算完成，哪些测试必须通过。

如果这些内容没有先写清楚，Codex 再强也只能根据上下文去猜。猜对了是效率，猜错了就是返工。

OpenSpec 常用指令

OpenSpec 的新流程里，最常用的是下面这些命令：

1
2
3
4

/opsx:propose  # 创建变更并生成规划 artifacts
/opsx:apply    # 按 artifacts 实现代码
/opsx:sync     # 把 delta specs 合并回主 specs
/opsx:archive  # 归档已经完成的变更

还有一些辅助命令：

1
2
3
4
5

/opsx:explore   # 需求还不清楚时，先讨论和探索
/opsx:new       # 只创建 change 脚手架
/opsx:continue  # 扩展流程中继续生成下一个 artifact
/opsx:ff        # fast-forward，一次性补齐规划 artifacts
/opsx:verify    # 检查实现是否符合 spec

对日常开发来说，我最常用的是这条主线：

1
2
3
4

/opsx:propose add-partial-shipment
/opsx:apply add-partial-shipment
/opsx:sync add-partial-shipment
/opsx:archive add-partial-shipment

/opsx:propose 会在 openspec/changes/<change-name>/ 下生成变更相关文档。不同配置下 artifacts 可能略有差异，但通常会包含 proposal.md、design.md、tasks.md 和 specs/ 目录。后面的 /opsx:apply 就是按这些文档实现，不是让 AI 凭空写代码。

如果你输入 /opsx:propose 也提示没有命令，通常说明 OpenSpec 没有正确初始化到当前 AI 工具里。可以先检查项目里是否有：

1
2
3

openspec/
openspec/project.md
openspec/changes/

也可以重新确认是否执行过 openspec init，以及当前工具是否加载了 OpenSpec 生成的 slash commands。

先让 propose 匹配项目

很多人用 /opsx:propose 时只写一句“帮我设计一下”，这样很容易得到一份看起来完整、但和项目完全对不上的文档。正确做法是先让 Codex 读取项目规则，再生成 change artifacts。

我一般会让它先看这些内容：

项目规则：AGENTS.md、README.md、团队开发规范、接口规范。

构建配置：pom.xml、父子模块关系、Spring Boot 版本、依赖版本。

代码结构：src/main/java 下的 controller、service、repository、mapper、domain、dto、vo。

同类功能：已经存在的订单、库存、报表、审批、结算接口。

数据层：MyBatis XML、JPA Entity、Flyway 或 Liquibase 脚本、表结构说明。

测试方式：src/test/java、MockMvc、JUnit、Testcontainers、集成测试脚本。

运行命令：mvn test、mvn -pl xxx test、项目自带的脚本。

把这些信息读完，/opsx:propose 输出的内容才会贴近当前项目，而不是空泛地讲“新增 controller、service、dao”。

一个比较实用的项目匹配提示词是：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

/opsx:propose add-partial-shipment

项目匹配要求：
1. 先读取 AGENTS.md、README.md、pom.xml，理解项目规则和模块关系。
2. 再读取和需求最接近的已有功能，优先参考同类 Controller、Service、Mapper、DTO、测试。
3. 如果项目使用 MyBatis，就按现有 Mapper/XML 风格设计；如果使用 JPA，就按现有 Entity/Repository 风格设计。
4. 不要引入项目里没有使用的框架、注解、依赖和目录结构。
5. 只生成 OpenSpec artifacts，不要写业务代码。

需求：
这里填写本次业务需求。

artifacts 需要覆盖：
proposal、design、tasks、specs。内容必须包含背景、术语、现状、目标、非目标、影响范围、接口设计、数据模型、核心流程、异常流程、权限、幂等、事务、消息、日志、测试、验收标准、开放问题。

这段提示词的关键是“先读项目，再生成 artifacts”。如果不加这个约束，AI 很可能会按照通用 Java 项目想象出一套不存在的架构。

例子一：订单支持部分发货

假设需求是“订单支持部分发货”。不要直接让 Codex 改代码，可以先这样用：

1
2
3
4
5
6
7
8
9
10

/opsx:propose add-partial-shipment

项目匹配要求：
- 先读取订单模块已有的发货、取消、完成订单代码。
- 找出订单状态枚举、订单明细表、库存扣减逻辑、发货单相关表。
- 参考现有接口命名、异常返回格式和测试写法。
- 只生成 proposal/design/tasks/specs，不修改业务代码。

需求：
订单支持部分发货。当前订单只能整单发货，订单明细里有多个 SKU。仓库可能只发其中一部分 SKU，剩余 SKU 后续再发。

我希望它生成的 OpenSpec artifacts 至少包括这些内容：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

1. 业务定义
- 部分发货：订单明细中部分 SKU 已生成出库记录，订单整体未完成。
- 待发数量：订单明细购买数量 - 已发数量 - 已取消数量。

2. 状态流转
- 待发货 -> 部分发货 -> 已发货
- 部分发货允许继续发剩余明细
- 已取消、已关闭订单不允许发货

3. 接口
- POST /orders/{id}/shipments
- 请求包含明细 ID、发货数量、仓库 ID、幂等 key
- 响应返回发货单号、订单状态、每个明细的已发数量

4. 数据
- shipment 表记录发货批次
- shipment_item 表记录每个 SKU 的发货数量
- order_item 可以增加 shipped_qty，也可以通过发货明细汇总，必须说明选择原因

5. 事务和幂等
- 发货记录、订单状态、库存扣减要么同事务完成，要么设计补偿流程
- 同一幂等 key 重复请求不能重复扣库存

6. 异常
- 发货数量超过待发数量
- 库存不足
- 明细不属于该订单
- 重复请求
- 订单状态不允许发货

7. 验收
- 部分发货后订单状态为部分发货
- 全部明细发完后订单状态为已发货
- 重复请求不重复创建发货单
- 异常时不产生半条发货记录

这份 change 不是最终代码，但它能让后续实现少走很多弯路。确认 artifacts 没问题以后，再进入实现：

1

/opsx:apply add-partial-shipment

实现完成并验证后，再同步和归档：

1
2

/opsx:sync add-partial-shipment
/opsx:archive add-partial-shipment

例子二：库存预占和释放

库存类需求更适合先走 /opsx:propose，因为它经常涉及并发和补偿。提示词可以这样写：

1
2
3
4
5
6
7
8
9
10

/opsx:propose inventory-reservation

项目匹配要求：
- 先读取库存模块现有的扣减、释放、流水表和库存锁实现。
- 找出项目使用的是数据库乐观锁、Redis 锁，还是消息队列异步扣减。
- 参考已有库存异常码、日志格式和事务注解位置。
- 只生成 proposal/design/tasks/specs，不写业务代码。

需求：
下单时预占库存，支付超时后释放库存，支付成功后确认扣减。

这里我会特别检查 artifacts 是否写清楚三件事：

第一，库存数量字段怎么定义。比如 available_qty、locked_qty、sold_qty 各自代表什么。

第二，状态和消息如何流转。下单预占、支付成功确认、支付超时释放、取消订单释放，每个动作都要有幂等判断。

第三，并发怎么处理。是用数据库条件更新 where available_qty >= ?，还是用版本号乐观锁，还是结合 Redis 锁。不能只写“加锁保证并发安全”这种空话。

例子三：ERP 报表统计

报表需求看起来只是查 SQL，其实最容易变成慢查询。用 /opsx:propose 时可以这样限制：

1
2
3
4
5
6
7
8
9
10

/opsx:propose supply-chain-fulfillment-report

项目匹配要求：
- 先读取现有报表模块、统计任务、Mapper XML、索引和分页实现。
- 找出项目是实时统计、离线汇总，还是混合方案。
- 参考已有导出权限、租户隔离、数据权限和缓存策略。
- 只生成 proposal/design/tasks/specs，不写业务代码。

需求：
新增供应链订单履约报表，按供应商、仓库、商品类目统计下单数、发货数、缺货数、履约率。

这类 spec 必须明确数据口径。比如“履约率”的分母是订单数、订单明细数，还是商品数量；缺货数是下单时缺货，还是发货时缺货；跨天订单归属到下单日期还是发货日期。口径不清楚，代码写得再快也没有意义。

从 spec 进入编码计划

/opsx:propose 生成 artifacts 后，不要马上 /opsx:apply。我更推荐先让 Codex 复核 tasks.md 是否已经能映射到项目内的修改计划：

1
2
3
4
5
6

请根据 openspec/changes/add-partial-shipment 下的 proposal、design、tasks、specs，先复核实现计划，不要改文件。
请按当前 Java 项目结构列出：
1. 需要修改或新增的 Controller、Service、Mapper、Entity、DTO、VO。
2. 需要新增或调整的数据库脚本、索引和枚举。
3. 正常流程、异常流程、幂等、事务分别对应哪些测试。
4. 每一步的风险点和回滚方案。

如果计划里出现项目没有的目录、框架、命名方式，就让它回去重读项目：

1
2
3

这个计划里出现了项目不存在的 Repository 风格。
请重新读取现有 mapper/xml 写法，按当前项目风格修正计划。
仍然不要写代码。

这个过程看起来多了一步，实际上是在编码前做了一次轻量 review。越是复杂需求，越值得这样做。

我会怎么检查 propose 的输出

一组 OpenSpec artifacts 看起来长，不代表它有用。我一般按下面这个清单检查：

是否引用了真实项目文件：比如具体模块、类名、表名、接口路径，而不是泛泛地说“新增服务层”。

是否区分目标和非目标：这次不做的事情要写出来，避免需求边界无限扩大。

是否有异常流程：库存不足、重复提交、权限不足、状态不允许、下游失败都要覆盖。

是否有幂等设计：尤其是支付、库存、发货、结算、消息消费。

是否有事务边界：哪些操作必须一致，哪些可以异步补偿。

是否有数据兼容：新增字段默认值、历史数据迁移、旧接口响应兼容。

是否有测试和验收：单元测试、集成测试、SQL 解释计划、接口回归都要能落地。

如果这些都没有，说明 spec 还只是“文章”，不是工程规格。

踩坑提醒

第一个坑，是把 /opsx:propose 当成魔法命令。它只是帮助整理上下文和规格，不能替代业务判断。关键口径还是要人来确认。

第二个坑，是不让它读项目。没有项目匹配的 spec 往往很漂亮，但落到 Java 工程里会出现错误包名、错误框架、错误事务模型。

第三个坑，是 spec 只写正常流程。真实系统最容易出问题的是异常流程，比如库存不足、重复请求、事务失败、部分写入、消息重复消费。

第四个坑，是 spec 和实现脱节。写完 spec 后，每轮实现都要让 Codex 对照 spec 和 diff，而不是写完一大堆代码再说“差不多”。

第五个坑，是一次 spec 太大。一个大需求可以拆成多个 spec，比如“状态流转 spec”“库存扣减 spec”“发货单 spec”“报表口径 spec”。每个 spec 能独立验收最好。

总结

OpenSpec/OPSX 的价值，是让 Codex 在写 Java 代码前先把需求说清楚，并且说成当前项目能执行的规格。它适合处理订单、库存、结算、权限、报表这类业务边界复杂的需求。

我的使用顺序是：先用 /opsx:propose 生成 change artifacts，再检查它是否匹配项目规则和同类代码，然后用 /opsx:apply 实现，完成后 /opsx:sync 同步规格，最后 /opsx:archive 归档。

当 spec 能清楚描述接口、数据、流程、异常、幂等、事务和验收时，后面的 coding 才会更准确。否则 Codex 只是更快地写出一批可能不符合业务的代码。

参考资料

• OpenAI Codex best practices
• OpenAI Codex Skills
• OpenSpec OPSX commands
• OpenSpec OPSX workflow

开场个人观察

这两年 AI 编程工具变化很快，从最早的补全、问答，到现在可以进入项目、读文件、改代码、跑命令的 coding agent，开发方式已经明显不一样了。Claude Code 属于这一类工具：它不是单纯的聊天窗口，而是更靠近终端里的协作开发助手。

我觉得普通开发者第一次用 Claude Code，最容易踩的坑不是“不会安装”，而是上来就把它当成万能实习生：丢一句“帮我优化项目”，然后等它自己理解所有背景。这样做偶尔能有惊喜，但很难稳定。更好的方式，是把它放进一个清楚的工作流里：先让它认识项目，再让它计划，再让它小步修改，最后看 diff 和验证结果。

下面这篇笔记不追求把所有功能讲完，而是记录一套适合日常开发的入门流程。只要这套流程跑顺了，后面再去学命令、skills、hooks、MCP，都会自然很多。

核心观点

Claude Code 的价值不在于“一句话生成一堆代码”，而在于把项目上下文、终端命令和代码修改串起来。你给它的任务越像一个可验收的小 issue，它的输出越容易 review。

我会把一次比较稳的 Claude Code 使用过程分成六步：

第一，进入正确的项目目录。AI 工具再强，也需要知道自己应该读哪个仓库、改哪个目录。

第二，先问项目结构，不急着让它改代码。比如让它说明入口文件、构建命令、测试命令、核心模块和风险点。

第三，把需求写清楚。最好包括目标、范围、验收标准、限制条件。

第四，让它先计划。复杂任务尤其不要一开始就让它写文件。

第五，小步执行。一次只做一个焦点，不要把修 bug、重构、加测试、改样式都塞进同一轮。

第六，看 diff、跑测试、沉淀规则。AI 生成的代码必须被验证，不能只看它的总结。

实践方法

第一次进入一个项目，我会先在项目根目录启动：

1
2

cd /path/to/project
claude

如果是在 Windows 上，路径可能类似：

1
2

cd E:\workspace\your-project
claude

进入会话后，不要马上说“帮我改”。我更建议第一句这样写：

1
2
3
4
5

先不要修改文件。请阅读这个项目的目录结构和关键配置，告诉我：
1. 这是一个什么类型的项目；
2. 入口文件和主要模块在哪里；
3. 安装、测试、构建命令可能是什么；
4. 如果后续要修改代码，哪些目录需要谨慎处理。

这个提示的作用，是先校准 Claude Code 对项目的理解。如果它一开始就找错入口，后面的修改很容易偏。

当你已经知道要做什么，可以把需求写成一个小任务：

1
2
3
4
5

目标：给登录页增加错误提示。
范围：只修改登录页组件、登录请求处理和必要的测试。
验收：输入错误密码时显示明确错误；网络失败时提示稍后重试；原有成功登录流程不变。
限制：不要重构全局请求库，不要改路由结构。
验证：完成后运行 npm test 和 npm run build；如果失败，请说明原因。

如果任务涉及多个文件，我会加一句：

1

先给计划，不要直接改文件。计划里请列出准备阅读的文件、修改步骤、验证方式和可能风险。

计划确认后，再让它执行：

1

按这个计划实现。每一步尽量保持最小改动，完成后总结改了哪些文件，并给出验证结果。

这套节奏看起来慢一点，但实际更省时间。因为你把“方向错了以后返工”的成本提前降下来了。

踩坑提醒

第一个坑，是让 Claude Code 同时做太多事。比如“顺便优化一下代码风格、顺便补测试、顺便升级依赖”。这些“顺便”很容易把任务边界打散。我的做法是：一个任务只保留一个核心目标，其他想法另开任务。

第二个坑，是不看 diff。AI 工具会给你很自信的总结，但总结不等于真实改动。尤其是配置文件、权限文件、构建脚本、数据库迁移脚本，一定要逐个看。

第三个坑，是把测试命令留到最后才想起来。更好的方式是在任务里直接写清楚“完成后要跑哪些命令”。如果项目没有测试，也要写手工验收标准。

第四个坑，是没有项目记忆。Claude Code 官方文档提到可以用 /init 生成项目说明，也可以用记忆文件沉淀项目规则。我的理解是：只要某条规则你重复说了三次，就应该写进项目说明里。

第五个坑，是会话太长还硬撑。长会话里上下文会越来越多，模型可能开始抓不住重点。这个时候应该用上下文管理命令压缩、清理或重新开会话，而不是继续堆提示词。

总结

Claude Code 的入门重点不是背命令，而是建立一个稳定的协作节奏：先读项目，再给计划，小步执行，看 diff，跑验证，沉淀规则。

如果把它当成“替我写代码的人”，你会经常担心它改错；如果把它当成“可以读项目、执行任务、接受 review 的协作助手”，它的价值会稳定很多。

我的建议是：先拿一个低风险项目练习，从文档、测试、小 bug 开始，不要一上来就让它改核心链路。等你熟悉它的节奏之后，再逐渐把更复杂的任务交给它。

参考资料

• Claude Code CLI reference
• Claude Code common workflows
• Claude Code interactive mode

开场个人观察

很多人第一次用 Codex，会把所有项目规则都写在当前对话里：项目用 Maven、不要改数据库结构、测试命令是什么、接口要保持兼容、日志不能打印手机号。这样当然能用，但每次都重复，很快就烦。

Codex 官方文档里把 AGENTS.md 解释成给 agent 用的开放格式 README。我的理解更直白：它是“写给 AI 看的项目交接文档”。对 Java 后端项目来说，AGENTS.md 不是越长越好，而是要把最容易犯错、最常重复、最影响结果的规则写进去。

用户口头上常说 agent.md，但 Codex 约定更常见的是 AGENTS.md。文章里我统一写 AGENTS.md，实际项目里建议按工具识别的文件名来。

核心观点

Java 项目的 AGENTS.md 应该解决三个问题。

第一，让 Codex 快速知道项目结构。比如哪个模块是订单、哪个模块是库存、接口在哪、Mapper XML 在哪、测试放哪。

第二，让 Codex 遵守团队约定。比如 Controller 不写业务，事务放 Service，异常走统一异常码，DTO/VO 不混用。

第三，让 Codex 知道什么叫完成。比如要跑哪些测试，要检查哪些页面，要看哪些日志，要 review 哪些风险。

它不是需求文档，也不是架构百科。它应该短、准、可执行。

实践方法

一个 Java 项目的 AGENTS.md 可以这样写：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

# Project Rules

## Layout

- order-service: 订单业务
- inventory-service: 库存业务
- settlement-service: 结算业务
- mapper XML under src/main/resources/mapper
- tests under src/test/java

## Commands

- Run module tests: mvn -pl order-service test
- Build all: mvn clean package -DskipTests
- Run local app: mvn -pl order-service spring-boot:run

## Java conventions

- Controller only handles request/response mapping.
- Business logic belongs in Service.
- Database access goes through Mapper.
- Keep DTO, BO, Entity, VO separated.
- Use existing Result and BizException types.
- Do not introduce new frameworks without explicit request.

## Safety

- Do not print token, password, phone, address, or ID card in logs.
- Do not change public API response fields unless requested.
- Do not modify database schema unless the task asks for it.
- For inventory and payment changes, explain transaction and idempotency.

## Done means

- Relevant tests pass or failure is explained.
- Diff is scoped to the task.
- Risk points are summarized.

这份文件不需要一开始完美。我的经验是先写基础版，等 Codex 重复犯错时再补。比如它第二次把业务写进 Controller，就把“Controller only handles mapping”写进去；它第二次忘记跑模块测试，就把测试命令写进去。

如果项目很大，可以在根目录放一个总 AGENTS.md，再在子模块放更细的规则。比如 inventory-service/AGENTS.md 专门写库存锁、库存流水、幂等规则；settlement-service/AGENTS.md 专门写金额精度、对账和事务要求。

踩坑提醒

第一个坑，是把 AGENTS.md 写成长篇架构文档。Codex 每次读进去都占上下文，太长反而降低重点。详细资料可以放到 docs/，在 AGENTS.md 里写“需要时参考”。

第二个坑，是写模糊规则。比如“代码要优雅”“遵循最佳实践”。这类话没什么约束力。更好的写法是“新增接口必须补充 Controller 层参数校验和 Service 层单测”。

第三个坑，是不更新。项目命令改了、模块拆了、测试脚本变了，AGENTS.md 也要跟着改。旧规则会让 Codex 稳定地做错事。

第四个坑，是把一次性需求写进去。AGENTS.md 存长期规则，不存“今天新增一个字段”这种临时任务。

总结

Java 项目的 AGENTS.md，本质上是把团队开发习惯沉淀给 Codex。它应该包含项目结构、运行命令、代码约定、安全禁区和完成标准。

写好它以后，你会发现提示词可以短很多，Codex 也更容易按项目风格工作。它不是替代沟通，而是减少重复沟通。

参考资料

• OpenAI Codex best practices
• OpenAI Codex AGENTS.md

开场个人观察

用 Codex 做 Java 系统项目时，我越来越觉得，提示词不是“把需求说给 AI 听”这么简单。Java 后端项目通常有 Controller、Service、Mapper、DTO、数据库表、事务、缓存、消息队列、定时任务、异常码、接口兼容这些东西。你只说一句“帮我加个功能”，Codex 很可能能写出代码，但不一定写在正确的位置，也不一定符合项目习惯。

OpenAI Codex 的最佳实践里提到，一个好的任务上下文通常要包含目标、上下文、约束和完成标准。我在 Java 项目里会把它再落细一点：业务目标、涉及模块、现有入口、技术约束、验收标准、验证命令。这样 Codex 才更像一个会读项目的协作开发者，而不是只会生成代码片段的工具。

核心观点

Java 项目的提示词，最重要的是让 Codex 知道“边界”。边界包括三类。

第一类是业务边界。比如这次只是新增订单状态筛选，不是重构订单中心；只是补库存预占失败提示，不是改库存模型。

第二类是技术边界。比如项目是 Spring Boot + MyBatis，不要引入 JPA；事务放在 Service 层，不要在 Controller 里写业务；已有统一异常处理，不要自己返回乱七八糟的 Map。

第三类是验收边界。比如接口返回字段不变，新增筛选条件要兼容旧调用，单测和构建要通过。

提示词写清楚边界，Codex 的发挥反而更稳定。

实践方法

我一般用这个模板：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

目标：
给订单列表接口增加按仓库和状态筛选。

上下文：
请先阅读 OrderController、OrderService、OrderMapper、OrderQueryDTO，以及 mapper XML。
当前项目是 Spring Boot + MyBatis，分页使用 PageHelper。

约束：
1. 不修改接口路径；
2. 不改已有返回字段；
3. 查询条件为空时保持原逻辑；
4. SQL 不要拼接字符串，使用参数绑定；
5. 不要改无关模块。

完成标准：
1. DTO 增加 warehouseId 和 status；
2. mapper 查询支持两个筛选条件；
3. 单元测试或 mapper 测试覆盖空条件和有条件；
4. 运行 mvn test；
5. 最后总结 diff 和风险点。

如果需求复杂，我会加一句：

1

先不要修改文件。请先给计划，列出要看的文件、要改的文件、测试方式和可能风险。

这句话很关键。很多返工都来自 Codex 一开始理解错层次。让它先计划，你可以提前发现它是不是准备改错模块。

如果是线上 bug，我会把错误现象也写进去：

1
2
3
4

现象：
订单列表传 status=已取消 时，页面仍然展示部分已完成订单。

请先定位查询链路，不要直接修。重点看参数从 Controller 到 Mapper XML 是否丢失，以及枚举值是否转换错误。

对于 Java 项目，我还喜欢明确“不要做什么”：

1

不要升级依赖，不要重构全局异常处理，不要修改数据库表结构，不要改 public API。

这比只写“保持最小改动”更有效。

踩坑提醒

第一个坑，是需求太像口号。比如“优化订单模块”。这句话没有验收标准，Codex 只能猜。要拆成“优化订单列表慢查询”“补订单状态变更测试”“修复取消订单库存回滚失败”。

第二个坑，是不给项目上下文。Java 项目里同名概念很多，Order、OrderInfo、SaleOrder、PurchaseOrder 可能完全不是一回事。让 Codex 先读文件，比让它凭名字猜靠谱。

第三个坑，是不写验证命令。Codex 可以跑测试，但它得知道跑什么。mvn test、mvn -pl order-service test、mvn -DskipTests package，写清楚会省很多来回。

第四个坑，是让它一次改太多。Java 系统里的改动常常牵扯数据库、缓存、接口、消息。大需求最好先切片，不要一轮做完。

总结

给 Codex 写 Java 项目提示词，我会坚持五段式：目标、上下文、约束、完成标准、验证命令。提示词不是越长越好，而是要让 Codex 少猜。

一条好的提示词，应该让人类开发者看了也知道怎么做。能达到这个标准，Codex 的输出通常就不会太离谱。

参考资料

• OpenAI Codex best practices
• OpenAI Codex