126 lines
10 KiB
Markdown
126 lines
10 KiB
Markdown
# 代码助手（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 依次交代（建议用小标题列出，便于你扫读）
|
||
|
||
1. **当前阶段**：写明处于五步中第几步（通常从第一步或第二步开始）。
|
||
2. **目标复述**：一句话重述要做的 XXX。
|
||
3. **待确认问题**：逐条列出仍不清晰处；没有则写「无，可继续」。
|
||
4. **OpenSpec**：若已有变更，写出目录 **`openspec/changes/<kebab-name>/`**；若无，**建议 `kebab-case` 变更名** 并说明将执行 `openspec new change` 或按 `.cursor/skills/openspec-propose/SKILL.md` 补齐制品。
|
||
5. **下一步**：唯一、可执行的具体动作（例如先问清验收，或跑 `openspec status` / `openspec instructions apply`）。
|
||
|
||
### 硬性门禁（助手 MUST NOT）
|
||
|
||
| 在未满足条件前 | 禁止 |
|
||
|----------------|------|
|
||
| 需求边界、验收方式仍含混且用户未确认 | 大篇幅编写 `tasks.md`、直接改 API/库表/核心业务 |
|
||
| 本次走 OpenSpec，但尚未读完 **`openspec instructions apply --change "<名>" --json`** 返回的 **全部 `contextFiles`** | 开始本次变更的**主要实现编码**（除为跑通 CLI 的微小编排外） |
|
||
| 当前 `tasks.md` 条目未约定本条的可验证方式（见第四步：测试或等价检查） | 为该条编写「为通过验收服务」的生产代码 |
|
||
| 未运行 **`AGENTS.md`** 中与本次改动相关的验证命令 | 下「已完成」「没问题」「全部搞定」等**完成断言** |
|
||
|
||
### 每一批改动提交前：自检三问（心中执行，复杂时写入回复）
|
||
|
||
1. 上一小步的 **lint / test / build**（以 `AGENTS.md` 为准）是否已通过？
|
||
2. 是否只推进 **`tasks.md` 中一项或一小块**？
|
||
3. 行为是否与 **`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/`** 固定组合 `@` 与口令。
|