10 KiB
代码助手（zkxw）— 五步工作流 × Superpowers × OpenSpec
在 Cursor / Agent 对话中 @代码助手.md（建议同时 @AGENTS.md），必要时再 @ 本次 openspec/changes/<变更名>/ 下的 proposal.md、tasks.md 等，使助手按本文节奏执行。
指令优先级：你在对话中的明确要求 > AGENTS.md / .cursorrules > 本文件 > Superpowers 技能 > 默认行为。技能与项目 SHALL 冲突时，以项目文档与 OpenSpec spec 为准。若你写明「跳过某步 / 不建 OpenSpec」，仅对当句及你明确指明的范围生效。
当本文件已在上下文中时：会话契约（拉近「自动流程」）
下列约定在本文件已被读取（例如用户 @代码助手.md）且用户请求涉及实现、开发、新增、改造、修复、做功能时，助手 MUST 遵守；除非用户在同一条消息里明确覆盖（例如「只改拼写、不要 OpenSpec」「允许直接改代码」）。
对「帮我实现 XXX」类请求的默认认定
- 默认按 完整五步 + OpenSpec 变更（若无则先创建） 处理；不把「实现」理解为「立刻堆代码」。
- 首轮不得批量修改业务代码、新建多文件路由/API，除非用户已声明「极小改动」且满足下文「压缩流程」条件。
首轮回复 MUST 依次交代（建议用小标题列出，便于你扫读）
- 当前阶段：写明处于五步中第几步（通常从第一步或第二步开始）。
- 目标复述：一句话重述要做的 XXX。
- 待确认问题：逐条列出仍不清晰处；没有则写「无，可继续」。
- OpenSpec：若已有变更，写出目录
openspec/changes/<kebab-name>/；若无，建议kebab-case变更名 并说明将执行openspec new change或按.cursor/skills/openspec-propose/SKILL.md补齐制品。 - 下一步：唯一、可执行的具体动作（例如先问清验收，或跑
openspec status/openspec instructions apply）。
硬性门禁（助手 MUST NOT）
| 在未满足条件前 | 禁止 |
|---|---|
| 需求边界、验收方式仍含混且用户未确认 | 大篇幅编写 tasks.md、直接改 API/库表/核心业务 |
本次走 OpenSpec，但尚未读完 openspec instructions apply --change "<名>" --json 返回的 全部 contextFiles |
开始本次变更的主要实现编码（除为跑通 CLI 的微小编排外） |
当前 tasks.md 条目未约定本条的可验证方式（见第四步：测试或等价检查） |
为该条编写「为通过验收服务」的生产代码 |
未运行 AGENTS.md 中与本次改动相关的验证命令 |
下「已完成」「没问题」「全部搞定」等完成断言 |
每一批改动提交前：自检三问（心中执行，复杂时写入回复）
- 上一小步的 lint / test / build（以
AGENTS.md为准）是否已通过？ - 是否只推进
tasks.md中一项或一小块？ - 行为是否与
spec.md的#### Scenario（若有）一致？
压缩流程（仅当用户明确声明时）
用户写清「单文件小改、不动接口与权限 / 仅文案或格式」等，可 不新建 OpenSpec 变更，但仍须：说明影响面 + 运行相关验证命令 + 不满足上表最后一行门禁。
总览：五步与 OpenSpec、Superpowers 的对应关系
| 步骤 | 你要达到的状态 | OpenSpec（制品 / 动作） | Superpowers（建议 @ 的技能） |
|---|---|---|---|
| 一 | 需求清晰，不清楚就问清 | proposal.md 定边界；必要时新建变更 openspec new change "<kebab-name>" |
.agents/skills/brainstorming/SKILL.md |
| 二 | 懂框架、规范、参考案例 | 读 openspec/config.yaml 的 context；apply 前读 openspec instructions apply --change "<名>" --json 返回的 全部 contextFiles（含 proposal、specs/**/spec.md、design、tasks） |
.agents/skills/using-superpowers/SKILL.md（何时加载其他技能） |
| 三 | 分步实现思路 | design.md + tasks.md 拆条；依赖用 openspec status --change "<名>" --json 看顺序 |
.agents/skills/writing-plans/SKILL.md |
| 四 | 测试驱动开发 | 每条 task 落地时：先测后码；行为写在 spec 的 Scenario 里，测试与之对齐 | .agents/skills/test-driven-development/SKILL.md |
| 五 | 开发—验证循环直到完成 | 按 tasks.md 逐项勾选；每步跑约定验证；全完后 openspec-archive-change / 归档流程 |
.agents/skills/verification-before-completion/SKILL.md |
OpenSpec 技能入口（本仓库）：.cursor/skills/openspec-propose/SKILL.md（立项与生成制品）、.cursor/skills/openspec-apply-change/SKILL.md（按 tasks 实现）、.cursor/skills/openspec-explore/SKILL.md、.cursor/skills/openspec-archive-change/SKILL.md；命令说明见 .cursor/commands/opsx-*.md。
第一步：必须清楚「要干啥」— 不清晰就反馈、对齐后再写代码
- 产出：口头/文档无歧义；对应 OpenSpec 里
proposal.md（做什么、不做什么、Capabilities 与后续specs/<能力>/spec.md一一对应）。 - 权威交叉：
docs/中科兴皖需求V0.3.md；Web / 小程序 UI 分别以docs/web-admin-ui-spec-fresh-mint.md、docs/miniprogram-ui-spec-sanqiang.md为准。 - Superpowers：需求或方案未定型时，先 @
.agents/skills/brainstorming/SKILL.md，再进入写 proposal / 拆 spec。 - 禁止：在需求含混时直接大改
tasks.md或批量改业务代码。
第二步：掌握项目框架、规范与参考案例
- 工程与 monorepo：以
AGENTS.md为准（后端backend/、管理端web-admin/、小程序miniprogram/等）。 - SHALL 级规范：
.cursor/rules/openspec-zkxw-standards.mdc；活跃变更下openspec/changes/*/specs/*/spec.md；若已归档则openspec/specs/为基线，与changes/并存时 以openspec/specs/为准。 - 进入实现前：执行
openspec instructions apply --change "<变更名>" --json，阅读返回的 全部contextFiles，不得跳过。 - Web 管理端界面模板（新页面对照，勿另起一套）：
web-admin/src/views/system/unit|order|product|category|user/index.vue等（路由与菜单见AGENTS.md/.cursorrules）。 - 树路径等业务约定：
web-admin/src/utils/tree-path.ts；弹窗与列表细节：.cursor/rules/web-admin-crud-dialog.mdc。
第三步：整理实现思路 — 坚持分步实施
- 产出：
design.md（如何做）+tasks.md（可执行、可勾选、粒度适合单 PR 或单会话块）。 - 顺序：用
openspec status --change "<变更名>" --json看制品依赖与applyRequires，缺什么先补什么，再进入大量编码。 - Superpowers：多步骤任务在写
tasks.md前可 @.agents/skills/writing-plans/SKILL.md，保证「一步一事」、依赖清晰。 - 原则：实现只推进
tasks.md当前项；避免无关重构与范围蔓延。
第四步：测试驱动开发（TDD）
- Superpowers：实现或修 Bug 写生产代码前 @
.agents/skills/test-driven-development/SKILL.md，遵循 Red → Green → Refactor；先看到有意义的失败再写最少通过代码。 - 与 OpenSpec 对齐：
spec.md中#### Scenario描述可验收行为；自动化测试（或本项目约定的可重复检查）应能指向这些场景。若某层（如纯 UI）难以单测，在tasks.md或对话中显式约定可替代的验证方式（例如 E2E、手工 checklist），并与用户确认——不得默认定「不写测」。
第五步：开发与验证循环，直到目标完成
- 开发：严格按
tasks.md逐项完成；需要并行子任务时可参考 @.agents/skills/dispatching-parallel-agents/SKILL.md或 @.agents/skills/subagent-driven-development/SKILL.md（与当前环境是否支持子代理一致）。 - 验证：每步完成后跑项目约定命令（见
AGENTS.md，如web-admin的pnpm lint、pnpm build:typecheck，后端pytest等）。声称完成前 @.agents/skills/verification-before-completion/SKILL.md，有命令输出再下结论。 - 收尾：变更完成后走 OpenSpec 归档（@
.cursor/skills/openspec-archive-change/SKILL.md或仓库文档中的 archive 流程），使基线与openspec/specs/同步。
对话里可复制的「开任务」示例
精简（你已习惯流程时）：
@代码助手.md @AGENTS.md
OpenSpec 变更：<kebab-change-name>。请按五步：先对齐 proposal/spec 中未决点；再读 apply 的 contextFiles；按 tasks 分步执行；每步 TDD；每步验证；最后对照 spec 与需求文档自检。
严格（更接近自动流程，只 @ 代码助手时推荐附带）：
@代码助手.md @AGENTS.md
帮我实现：XXX（验收：……；端：web-admin / 后端 / 小程序；是否新建 OpenSpec 变更：是/否；若否请说明原因）。
你必须遵守根目录代码助手.md中的会话契约：首轮只对齐阶段与缺口，不得直接大改代码；有变更名则openspec instructions apply --change "<名>" --json并读完所有 contextFiles 后再实现；每 task 先 TDD 或等价验收约定；每步跑AGENTS.md中的验证命令后再断言完成。
说明：Cursor 不会在后台替你执行命令；「自动」指模型必须按上文契约与五步组织行为。你仍可用 /opsx-propose、/opsx-apply 等命令（见 .cursor/commands/opsx-*.md）减少口述步骤。
维护说明
- 变更 OpenSpec 目录结构或 CLI 子命令时，同步更新本文「OpenSpec」小节与
openspec/config.yaml中的 context 摘要。 - Superpowers 技能路径以仓库
.agents/skills/为准；若本机安装位置不同，在对话中用实际可@的路径替换即可。 - 边界：本文提高模型遵守流程的概率，不是 IDE 插件或 CI 强制门禁；若要更强约束，可把「会话契约」摘要写入
.cursor/rules/*.mdc（alwaysApply） 或使用.cursor/commands/固定组合@与口令。