为什么需要可复用工作流

用 AI 编程工具一段时间后，我发现一个很现实的问题：很多提示词会被反复复制。比如“请先读代码不要修改”“请按这个格式输出审查结果”“请运行这些验证命令”“请用我们项目的发布流程”。这些话每次都粘一遍，既麻烦，也容易漏。

Skill 就是为了解决这类问题而出现的。它把一套可复用的工作流程、检查清单、领域知识或工具调用方式，包装成一个可以被 AI 按需加载的能力。你可以把它理解成“给 AI 用的操作手册”，但它比普通文档更强调触发条件和执行步骤。

Claude Code 官方文档里说，skills 通过 SKILL.md 扩展 Claude 的能力，可以在相关时自动使用，也可以通过 /skill-name 直接调用。Codex 这边也有类似的技能机制：一个 skill 通常包含说明文件，以及可选的脚本、参考资料和资源文件。两者的共同点是：把重复经验沉淀为可复用流程。

Skill 的职责与适用边界

Skill 不是越大越好，而是越清楚越好。一个好的 skill 应该回答四个问题：

第一，它解决什么重复问题？

第二，什么时候应该使用它？

第三，使用它时要按什么步骤执行？

第四，输出结果应该如何验证？

如果一个 skill 只是把一大堆资料塞进去，反而会降低效果。因为 AI 每次使用时会消耗上下文，描述越含糊，越容易触发错误；内容越臃肿，越容易淹没真正关键的步骤。

我更喜欢把 skill 做成“小而稳”的工具。比如：

supply-chain-inventory-review：专门审查供应链系统里的库存预占、释放、扣减和流水一致性。

api-review：专门审查接口改动，包括鉴权、错误码、兼容性、日志、测试。

release-check：专门做发版前检查，包括 diff、测试、配置、回滚方案。

这些 skill 都有明确边界，比“我的万能开发助手”更容易生效。

从任务流程到Skill文件

一个最小 skill 通常可以从一个文件夹开始：

1
2

my-skill/
  SKILL.md

SKILL.md 里最重要的是 front matter 和正文说明：

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

---
name: supply-chain-inventory-review
description: Use when reviewing inventory reservation, release, deduction, or stock ledger changes in a Java supply chain system.
---

# Supply Chain Inventory Review

Use this skill when a change touches inventory reservation, inventory release, stock deduction, stock ledger, purchase receipt, shipment, or order fulfillment logic.

## Workflow

1. Read the related Controller, Service, Mapper, DTO, database scripts, and tests.
2. Identify the business scenario: order reservation, payment confirmation, timeout release, shipment deduction, purchase receipt, or adjustment.
3. Check whether idempotency, transaction boundaries, concurrency control, and stock ledger records are defined.
4. List risks before suggesting code changes.
5. Require tests for success, duplicate requests, insufficient stock, concurrent requests, and rollback.
6. Review the final diff against the risk list.

## Rules

- Do not introduce a new lock mechanism unless the existing project pattern cannot satisfy the scenario.
- Do not change stock quantity without a matching stock ledger record.
- Do not treat idempotency as only a frontend concern.
- Any change to stock quantity must explain transaction and rollback behavior.

这里的 description 很关键。它不是给人看的简介，而是帮助 AI 判断什么时候应该加载这个 skill。写得太窄，可能触发不了；写得太宽，又会到处乱触发。

如果流程需要稳定执行脚本，可以加 scripts/：

1
2
3
4

my-skill/
  SKILL.md
  scripts/
    validate_front_matter.js

如果有较长参考资料，可以放到 references/，并在 SKILL.md 里说明什么时候读。这样平时不占上下文，只有需要时才加载。

如果有模板、示例图片、配置样板，可以放到 assets/。例如写报告、生成幻灯片、创建博客配图时，这个目录很有用。

我的生成步骤一般是：

1
2
3
4
5
6

1. 先把重复任务写成普通提示词。
2. 连续使用几次后，找出稳定不变的步骤。
3. 把步骤整理成 SKILL.md。
4. 用一个真实任务测试它。
5. 如果触发太频繁，就收窄 description。
6. 如果经常忘步骤，就把规则写得更明确。

把重复工作流沉淀成 skill

真正值得沉淀成 skill 的，不是一次性任务，而是反复出现、容易漏步骤、出错代价高的工作流。Java 供应链系统里最典型的例子，就是库存相关需求。

比如系统里经常会有这些需求：

1
2
3
4
5
6
7

下单时预占库存。
支付成功后确认扣减。
支付超时后释放库存。
取消订单后释放库存。
采购到货后增加库存。
发货出库后扣减库存。
盘点差异后调整库存。

这些需求看起来场景不同，但底层检查点很相似：库存数量不能错，流水必须完整，重复请求不能重复扣减，并发不能超卖，异常时不能留下半条数据。

第一次遇到这类需求时，可以先写普通提示词：

1
2
3
4
5
6
7
8

请先审查这个库存预占需求，不要写代码。
重点检查：
1. 库存数量字段如何变化；
2. 是否需要库存流水；
3. 是否有幂等 key；
4. 并发请求是否会超卖；
5. 事务失败是否会回滚；
6. 需要哪些测试用例。

如果第二次、第三次还在复制同样的话，就说明它适合沉淀成 skill。沉淀时不要急着写成很大的“供应链系统全能助手”，而是先做一个边界清楚的 skill，比如 supply-chain-inventory-review。

这个 skill 可以这样设计：

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

---
name: supply-chain-inventory-review
description: Use when reviewing Java supply chain changes that modify inventory reservation, release, deduction, receipt, adjustment, or stock ledger records.
---

# Supply Chain Inventory Review

## When to use

Use this skill when a change touches inventory quantity, stock ledger, reservation records, purchase receipt, shipment deduction, or inventory adjustment.

## Steps

1. Identify the business action: reserve, release, deduct, receive, adjust, or reverse.
2. Find the existing inventory tables, ledger tables, Mapper/XML, Service, and tests.
3. Check idempotency: request key, order number, message key, or business unique index.
4. Check concurrency: optimistic lock, conditional update, row lock, Redis lock, or message serialization.
5. Check transaction boundary: which records must commit or roll back together.
6. Check ledger consistency: every quantity change must have a matching ledger reason.
7. Check tests: success, insufficient stock, duplicate request, concurrent request, rollback, and invalid state.
8. Review diff and report any unrelated refactor.

## Output

Return:
- business scenario summary
- affected files and tables
- risk list
- required tests
- review conclusion

这个例子里，skill 保存的不是某个需求的答案，而是“审查库存变更时必须走的流程”。以后不管是预占库存、释放库存，还是采购到货入库，都可以复用这套检查方式。

更进一步，还可以把它拆成多个小 skill：

1
2
3

supply-chain-inventory-review：审库存数量、流水、幂等、并发。
supply-chain-report-review：审报表口径、SQL 性能、导出权限。
supply-chain-order-state-review：审订单状态机、允许操作、异常流转。

这样做的好处是，每个 skill 都很清楚，触发条件也更准确。AI 不需要一次加载一大堆供应链知识，只在相关场景加载对应流程。

我判断一个重复流程能不能变成 skill，通常看三个问题：

1
2
3

这件事是否每次都要重复说？
这件事漏掉以后是否容易出事故？
这件事是否能写成稳定步骤和检查清单？

如果三个答案都是“是”，就值得沉淀。

设计与维护中的常见问题

第一个坑，是把 skill 写成百科。Skill 不是知识库全文，它应该优先保存流程、约束和关键判断。长资料可以放 references，需要时再读。

第二个坑，是 description 写得太虚。比如“帮助开发”这种描述几乎没有意义。更好的写法是“Use when reviewing API changes for authentication, compatibility, error handling, and tests.”

第三个坑，是没有真实任务验证。一个 skill 看起来写得很好，不代表实际会触发，也不代表输出稳定。一定要拿真实项目试一次。

第四个坑，是把易变信息写死。比如某个临时分支、一次性需求、当天的部署地址，不适合写进长期 skill。Skill 应该保存长期有效的规则。

第五个坑，是让 skill 绕过人工判断。Skill 可以让 AI 更熟悉流程，但不能替你承担最终责任。尤其是部署、删除数据、改权限、处理密钥，仍然要有人确认。

总结

Skill 的本质，是把反复出现的 AI 协作经验产品化。它不神秘，也不一定复杂。只要你发现自己第三次复制同一段提示词，就可以考虑把它做成一个 skill。

我判断一个 skill 是否值得保留，通常看三个标准：是否减少重复输入，是否降低错误概率，是否让输出更容易验收。满足这三点，就值得沉淀。

参考资料

• Claude Code skills
• Claude Code commands reference
• Codex skills

从规格正确到执行可靠

前面写 OpenSpec/OPSX 的时候，我把重点放在“先把需求写成规格，再让 AI 按规格实现”。但真实项目里还有另一类问题：spec 写得差不多了，AI 也开始改代码了，可过程还是容易跑偏。比如一次性改太多文件、没有先写测试、遇到失败就绕过、没有复盘 diff、没有把经验沉淀下来。

这就是我重新理解 superpowers 的原因。它不是一句“请发挥超级能力”的提示词，而是一套更偏工程实践的开发方法论。参考 obra/superpowers 的定位，它更像是把成熟开发者的工作习惯拆成一组可调用的 skills：需求澄清、计划、测试驱动、调试、代码审查、执行计划、提交纪律、协作沟通等。

如果说 OpenSpec 负责回答“我们要做什么”，那么 Superpowers 更关注“我们怎样稳定地把它做完”。这篇记录一下我会怎么把 Superpowers 用在 Java 后端项目的 Spec Coding 里，尤其是订单、库存、支付、结算、报表这种高风险业务。

Superpowers 解决的工程问题

我现在不把 superpowers 理解成单个命令，而是理解成一套“开发过程护栏”。它的目标不是让 AI 写得更快，而是让 AI 在关键节点停下来做正确动作。

第一层是澄清。需求不清楚时，不急着写代码，先把目标、非目标、约束、验收标准问明白。

第二层是计划。复杂任务不能直接开写，要先拆成小步，每一步都有可验证结果。

第三层是测试。高风险逻辑优先写测试或至少先写测试清单，避免只覆盖 happy path。

第四层是调试。出错时按证据排查，不靠猜，不反复试错，不把失败测试删掉。

第五层是审查。每轮改完都看 diff，检查是否越界、是否引入不必要重构、是否破坏兼容。

第六层是沉淀。做完后把决策、坑点、可复用经验记录下来，下次不从零开始。

这几层能力组合起来，才是 Superpowers 真正有价值的地方。

Superpowers 技能指令速查

Superpowers 安装以后，通常不是靠一个 /superpowers 命令来完成所有事情，而是让 agent 在合适场景自动触发对应 skill。实际使用时，也可以直接点名 skill，让 Codex 或 Claude Code 按这个 skill 的流程工作。

我会把它理解成这些“技能指令”：

1

using-superpowers

用途：让 agent 先说明 Superpowers 的技能系统怎么工作，适合刚安装完验证是否生效。

1

brainstorming

用途：需求还很粗时使用。它会先问问题、澄清目标、探索方案，而不是马上写代码。

1

writing-plans

用途：设计确认后生成实现计划。计划要拆成小任务，写清楚文件路径、修改点和验证步骤。

1

executing-plans

用途：按已经写好的计划执行。适合一个人机协作的节奏：做一批任务，停下来检查，再继续。

1

subagent-driven-development

用途：让子 agent 按任务并行或分阶段推进，并进行两段式检查：先看是否符合 spec，再看代码质量。

1

test-driven-development

用途：强制 RED-GREEN-REFACTOR。先写失败测试，看它真的失败，再写最小代码让测试通过，最后重构。

1

systematic-debugging

用途：遇到 bug 或测试失败时使用。要求先收集证据、定位根因，再做最小修复，避免靠猜。

1

verification-before-completion

用途：完成前确认“真的修好了”。不能只说看起来可以，要跑测试、看输出、验证关键路径。

1

requesting-code-review

用途：改完一轮后请求代码审查。重点看计划符合度、边界场景、测试缺口、是否有越界修改。

1

receiving-code-review

用途：收到 review 反馈后使用。它会帮助逐条处理问题，而不是只挑简单的改。

1

using-git-worktrees

用途：为一个较大任务创建隔离工作区，避免污染主工作区，适合多任务并行或风险较高的改动。

1

finishing-a-development-branch

用途：任务完成后收尾。检查测试、整理变更、决定合并、开 PR、保留或清理 worktree。

1

dispatching-parallel-agents

用途：把独立任务分给多个 agent 并行做，比如一个查接口影响，一个查数据库影响，一个补测试。

1

writing-skills

用途：把你自己的流程沉淀成新 skill。比如把“Java 库存接口审查清单”写成团队 skill。

实际对话时，可以这样点名：

1

请使用 brainstorming skill，先澄清这个库存预占需求，不要写代码。

1
2

请使用 writing-plans skill，基于已经确认的设计生成实现计划。
每个任务要包含文件路径、修改内容、验证命令。

1
2

请使用 test-driven-development skill，实现批量库存预占。
必须先写失败测试，再写最小实现。

1
2

请使用 systematic-debugging skill 分析这个失败测试。
先给证据和根因假设，不要直接改代码。

1
2

请使用 requesting-code-review skill 审查当前 diff。
按严重程度列出问题，重点看事务、幂等、并发、兼容性和测试缺口。

如果你的客户端支持 slash command，具体触发形式可能会包装成斜杠命令；如果不支持，直接在提示词里写“请使用 xxx skill”也能表达同样意图。关键是点名具体 skill，而不是只说“用 superpowers”。

Superpowers 和 OpenSpec 的关系

OpenSpec/OPSX 更偏规格管理。比如：

1
2
3
4

/opsx:propose add-inventory-reservation
/opsx:apply add-inventory-reservation
/opsx:sync add-inventory-reservation
/opsx:archive add-inventory-reservation

这条链路解决的是“变更如何被定义、实现、同步、归档”。它适合让需求有结构、有历史、有验收。

Superpowers 更偏过程控制。它解决的是：

1
2
3
4
5
6

实现前是否先澄清？
有没有按小步计划推进？
有没有先补测试？
失败时有没有按证据调试？
改完是否审查 diff？
完成后有没有总结经验？

所以我更推荐把两者组合起来：

1
2

OpenSpec 负责定义变更。
Superpowers 负责约束执行过程。

在 Java 项目里，这个组合尤其有用。因为 Java 后端的麻烦经常不在代码语法，而在业务边界、数据库一致性、并发、事务、历史数据和系统间调用。

一个可落地的 7 步流程

参考 Superpowers 的实践思路，我会把一次 AI 辅助开发拆成 7 步。

第一步，理解任务，对应 brainstorming。

让 AI 先读需求、读项目规则、读同类代码。对 Java 项目来说，至少要看 AGENTS.md、README.md、pom.xml、同类 Controller、Service、Mapper、测试用例。不要让它一上来就改文件。

可以这样提示：

1
2
3
4
5
6
7

请先理解任务，不要改代码。
读取 AGENTS.md、README.md、pom.xml，以及订单模块已有的 Controller、Service、Mapper、测试。
请总结：
1. 这个需求涉及哪些模块；
2. 现有代码风格是什么；
3. 可能影响哪些接口、表、状态机；
4. 还有哪些问题需要确认。

第二步，提出计划，对应 writing-plans。

计划要小步、可验证。不要只写“实现业务逻辑”，而要写到具体层次：

1
2
3
4
5
6

请生成执行计划，不要改代码。
要求：
1. 每一步只改一类文件；
2. 每一步说明验证方式；
3. 标出事务、幂等、并发、兼容性风险；
4. 不做和需求无关的重构。

第三步，先写测试或测试清单，对应 test-driven-development。

很多 Java 项目历史包袱重，不一定能完全 TDD，但至少要先列出测试清单。比如库存预占，不应该只测成功：

1
2
3
4
5
6
7
8
9

测试清单：
1. 单 SKU 预占成功；
2. 多 SKU 全部预占成功；
3. 部分 SKU 库存不足；
4. 同一订单重复请求不重复扣减；
5. 并发请求同一 SKU 不超卖；
6. 数据库异常时事务回滚；
7. 参数为空、数量为负数、SKU 不存在时返回校验错误；
8. 旧接口字段保持兼容。

第四步，小步实现，对应 executing-plans 或 subagent-driven-development。

每次只让 AI 做一个小任务。比如先改 DTO，再改 Service，再改 Mapper，再补测试。不要一句“全部实现”，否则它很容易跨模块乱改。

1
2
3

现在只做第一步：新增请求 DTO 和响应 DTO。
不要修改 Service、Mapper、数据库脚本。
完成后展示 diff，并说明是否符合计划。

第五步，基于证据调试，对应 systematic-debugging。

测试失败时，不要让 AI 直接猜。要让它先读错误日志、定位失败断言、说明假设，再做最小修复。

1
2
3
4
5
6
7

测试失败了。请先分析失败日志，不要马上改代码。
输出：
1. 失败测试名称；
2. 期望值和实际值；
3. 最可能的原因；
4. 需要查看的文件；
5. 最小修复方案。

第六步，审查 diff，对应 requesting-code-review。

这一点非常关键。AI 很容易顺手改命名、调格式、移动代码、引入新依赖。审查 diff 要看三件事：有没有完成需求，有没有越界，有没有留下风险。

1
2
3
4
5
6
7
8

请审查当前 diff。
重点检查：
1. 是否只修改了计划内文件；
2. 是否引入新依赖或新框架；
3. 事务边界是否正确；
4. 幂等和并发是否覆盖；
5. 是否有兼容性风险；
6. 测试是否覆盖异常场景。

第七步，总结和沉淀，对应 verification-before-completion 和 finishing-a-development-branch。

做完以后，不只是提交代码。应该把这次的决策、坑点、命令、测试经验沉淀下来。对长期项目来说，这一步会让 AI 后续越来越贴合项目。

1
2
3
4
5
6
7

请总结这次变更：
1. 业务决策；
2. 技术决策；
3. 关键风险；
4. 测试覆盖；
5. 后续维护注意事项；
6. 哪些内容适合补充到 AGENTS.md 或项目文档。

我常用的技能组合

Superpowers 的价值在于把“好习惯”变成可以重复调用的技能。我在 Java 项目里会重点用这些能力。

任务澄清：适合需求刚开始时使用。让 AI 主动问缺失信息，不要把不确定性藏到代码里。

分步计划：适合任何超过 30 分钟的任务。计划必须能映射到文件、测试和验收标准。

测试驱动：适合库存、支付、结算、权限、状态机。能先写测试就先写测试，不能先写测试也要先写测试清单。

系统性调试：适合测试失败、线上 bug 复现、SQL 慢查询。要求 AI 先收集证据，再给修复方案。

代码审查：适合每轮实现后使用。重点看越界修改、隐藏风险、兼容性和测试缺口。

执行计划：适合大需求。把大任务拆成多个可提交的小任务，每个任务都能独立回滚。

文档沉淀：适合完成后使用。把项目约定、接口口径、踩坑经验补到文档里。

这些技能听起来朴素，但它们正是普通开发者日常最容易省略的步骤。AI 写代码越快，越需要这些步骤把节奏稳住。

Java 项目里的具体用法

以“库存预占接口支持批量 SKU”为例，我会这样组合 OpenSpec 和 Superpowers。

第一轮，先用 OpenSpec 定义变更：

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

/opsx:propose batch-inventory-reservation

需求：
库存预占接口支持批量 SKU。
同一订单请求必须幂等。
库存不足时返回明细级失败原因。

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

第二轮，用具体 skill 审这个变更：

1
2
3
4
5
6
7
8

请使用 requesting-code-review skill 审查 openspec/changes/batch-inventory-reservation。
重点输出：
1. 需求是否清楚；
2. 是否遗漏异常流程；
3. 是否遗漏幂等、并发、事务、回滚；
4. tasks 是否能小步执行；
5. 测试是否覆盖成功、失败、重复、并发、回滚；
6. 哪些问题必须在 apply 前确认。

第三轮，再进入实现：

1
2
3
4
5
6
7
8
9

/opsx:apply batch-inventory-reservation

请结合 executing-plans skill 执行。
执行要求：
- 严格按照 tasks.md 小步实现；
- 每完成一个步骤先展示 diff；
- 测试失败时先分析日志，不要猜；
- 不做无关重构；
- 不引入项目没有使用的新框架。

第四轮，改完后做 diff 审查：

1
2
3
4
5
6
7
8

请使用 requesting-code-review skill 检查当前 diff。
重点看：
1. 是否符合 proposal/design/tasks/specs；
2. 是否有超卖风险；
3. 幂等记录是否和库存事务一致；
4. 异常时是否会留下脏数据；
5. 是否兼容旧接口；
6. 测试是否覆盖明细级失败原因。

第五轮，验证通过后同步归档：

1
2

/opsx:sync batch-inventory-reservation
/opsx:archive batch-inventory-reservation

这样一套下来，AI 不再只是“帮我写个接口”，而是在规格、计划、实现、测试、审查、沉淀之间形成闭环。

三条关键使用原则

第一条，不清楚就先问，不要让 AI 猜。

比如“库存不足怎么处理”这句话就不够清楚。是整个请求失败，还是允许部分成功？失败原因要不要返回到明细级？是否要写库存流水？是否要发 MQ？这些如果不问清楚，后面代码一定返工。

第二条，大任务必须拆小步。

一个需求如果同时改 Controller、Service、Mapper、表结构、消息消费、定时任务、测试，AI 很容易失控。拆小步以后，每一步都能审查 diff，也方便回滚。

第三条，测试和 diff 是最后防线。

不要相信“代码看起来对”。对于 Java 后端，至少要跑相关测试；没有测试也要做手工验证清单。diff 里如果出现无关重构、新依赖、无说明的表结构变化，都要停下来审。

使用边界与常见误区

第一个坑，是把 Superpowers 当成夸张提示词。比如“请用超级能力帮我写代码”，这种没有实际约束。要明确指定它做澄清、计划、测试、调试、审查。

第二个坑，是只在编码后使用。Superpowers 最有价值的时机其实是编码前：需求不清楚先问，风险不明确先列，计划不稳定先拆。

第三个坑，是让它一次性自由发挥。AI 最擅长补全，但补全太多就可能越界。越复杂的需求，越应该让它分阶段交付。

第四个坑，是不让它看真实项目。没有 pom.xml、同类代码、Mapper XML、测试用例，AI 很容易写出“标准答案”，但不是你项目里的答案。

第五个坑，是跳过复盘。一次需求做完后，如果没有把经验沉淀到 AGENTS.md、OpenSpec specs 或项目文档，下次还会踩同样的坑。

总结

Superpowers 不是让 AI 变神，而是把成熟开发者的工作纪律装进 AI 协作流程里。它提醒我们：先澄清，再计划；先测试，再实现；先看证据，再调试；先审 diff，再合并；最后把经验沉淀下来。

在 Java 项目里，我最推荐把 OpenSpec 和 Superpowers 组合起来：OpenSpec 管规格，Superpowers 管过程。前者让需求变清楚，后者让实现不跑偏。

真正有建设性的 AI 编程，不是让模型替你一路狂写，而是让它在每个关键节点都能停下来问一句：这个需求清楚吗？这个计划可验证吗？这个改动安全吗？这个测试够吗？

参考资料

• obra/superpowers
• Superpowers 实战指南：让 AI 编程从“代码生成”迈向“专业开发”
• OpenAI Codex best practices
• OpenAI Codex customization

指令为什么要按场景使用

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

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

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

指令分类与适用边界

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

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

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

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

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

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

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

审查提示词：提交前明确要求 Claude Code 以只读方式检查 diff；安全敏感改动可使用 /security-review。

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

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

按开发阶段选择指令

新项目第一步，我会用：

1

/init

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

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

1

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

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

会话变长后，我会用：

1

/context

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

1

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

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

准备验收时，我会用：

1

/diff

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

提交前，可以直接要求 Claude Code 只读审查当前 diff。如果改动涉及认证、权限、输入校验或敏感数据，可以运行：

1

/security-review

通用代码质量审查与安全审查不是同一件事。前者还要检查业务正确性、兼容性、性能和测试缺口，不能只依赖安全检查命令。

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

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

1

/rewind

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

版本差异与使用误区

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

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

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

第四个提醒：审查命令不能替代人工 review。/security-review 聚焦安全风险，关键业务逻辑、数据一致性和兼容性仍然需要开发者自己负责。

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

总结

Claude Code 常用指令可以按一句话记：准备时 /init，复杂任务用 /plan，长会话用 /context 和 /compact，验收时先看 /diff，安全敏感改动再用 /security-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 进入后续编码。

OpenSpec 在开发流程中的职责

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 customization
• OpenSpec OPSX commands
• OpenSpec OPSX workflow

为什么需要完整工作流

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

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

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

Claude Code 的职责边界

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