From f0cff74ca4a0874233c9dfb0533f48d6dae78490 Mon Sep 17 00:00:00 2001 From: zichun Date: Mon, 25 May 2026 13:53:11 +0800 Subject: [PATCH] feat(lite): unify backend+frontend feature loops into one phase-parameterized 3-step chain --- skills/coding/fe-feature-brainstorm/SKILL.md | 74 -------------------------------------------------------------------------- skills/coding/fe-feature-brainstorm/templates/fe-feature-spec-template.md | 55 ------------------------------------------------------- skills/coding/fe-feature-plan/SKILL.md | 142 ---------------------------------------------------------------------------------------------------------------------------------------------- skills/coding/fe-feature-plan/templates/fe-feature-plan-template.md | 47 ----------------------------------------------- skills/coding/fe-feature-review/SKILL.md | 40 ---------------------------------------- skills/coding/fe-feature-review/templates/commit-message-template.md | 1 - skills/coding/fe-feature-review/templates/fe-feature-review-template.md | 37 ------------------------------------- skills/coding/fe-feature-tdd/SKILL.md | 65 ----------------------------------------------------------------- skills/coding/fe-feature-tdd/templates/commit-message-template.md | 1 - skills/coding/fe-feature-verify/SKILL.md | 61 ------------------------------------------------------------- skills/coding/fe-feature-verify/templates/fe-feature-verify-evidence-template.md | 33 --------------------------------- skills/coding/feature-brainstorm/SKILL.md | 65 ----------------------------------------------------------------- skills/coding/feature-brainstorm/templates/feature-spec-template.md | 31 ------------------------------- skills/coding/feature-plan/SKILL.md | 143 ----------------------------------------------------------------------------------------------------------------------------------------------- skills/coding/feature-plan/templates/feature-plan-template.md | 28 ---------------------------- skills/coding/feature-review/SKILL.md | 135 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++------------------ skills/coding/feature-review/templates/commit-message-template.md | 1 + skills/coding/feature-review/templates/feature-review-template.md | 35 +++++++++++++++++++++++++++++------ skills/coding/feature-spec/SKILL.md | 215 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ skills/coding/feature-spec/templates/feature-spec-plan-template.md | 153 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ skills/coding/feature-tdd/SKILL.md | 88 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++--------------- skills/coding/feature-verify/SKILL.md | 41 ----------------------------------------- skills/coding/feature-verify/templates/feature-verify-evidence-template.md | 16 ---------------- 23 files changed, 588 insertions(+), 919 deletions(-) delete mode 100644 skills/coding/fe-feature-brainstorm/SKILL.md delete mode 100644 skills/coding/fe-feature-brainstorm/templates/fe-feature-spec-template.md delete mode 100644 skills/coding/fe-feature-plan/SKILL.md delete mode 100644 skills/coding/fe-feature-plan/templates/fe-feature-plan-template.md delete mode 100644 skills/coding/fe-feature-review/SKILL.md delete mode 100644 skills/coding/fe-feature-review/templates/commit-message-template.md delete mode 100644 skills/coding/fe-feature-review/templates/fe-feature-review-template.md delete mode 100644 skills/coding/fe-feature-tdd/SKILL.md delete mode 100644 skills/coding/fe-feature-tdd/templates/commit-message-template.md delete mode 100644 skills/coding/fe-feature-verify/SKILL.md delete mode 100644 skills/coding/fe-feature-verify/templates/fe-feature-verify-evidence-template.md delete mode 100644 skills/coding/feature-brainstorm/SKILL.md delete mode 100644 skills/coding/feature-brainstorm/templates/feature-spec-template.md delete mode 100644 skills/coding/feature-plan/SKILL.md delete mode 100644 skills/coding/feature-plan/templates/feature-plan-template.md create mode 100644 skills/coding/feature-review/templates/commit-message-template.md create mode 100644 skills/coding/feature-spec/SKILL.md create mode 100644 skills/coding/feature-spec/templates/feature-spec-plan-template.md delete mode 100644 skills/coding/feature-verify/SKILL.md delete mode 100644 skills/coding/feature-verify/templates/feature-verify-evidence-template.md diff --git a/skills/coding/fe-feature-brainstorm/SKILL.md b/skills/coding/fe-feature-brainstorm/SKILL.md deleted file mode 100644 index cbc730e..0000000 --- a/skills/coding/fe-feature-brainstorm/SKILL.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -name: fe-feature-brainstorm -description: 前端功能循环第 1 步。针对单个 FE-NN 页面（prototype/*.html）做交互式 Q&A + 写前端规格，产出到 docs/superpowers/specs/，链入 fe-feature-plan。 -user-invocable: false -allowed-tools: Read Write Skill AskUserQuestion Glob Grep ---- - -**所有输出必须使用中文。** - -# fe-feature-brainstorm - -## 阶段范围（前端） - -本 skill 服务于**前端阶段**。产出范围限定为：组件树 / 页面状态机 / 交互流程 / API 调用 / Design Tokens 引用 / 业务校验前端复刻。**不涉及** SQL / migration / controller / service / DTO（这些已在后端阶段完成）。 - -一个 FE 是**业务功能**粒度，可能关联多个 prototype 文件区域和多个 REQ。 - -## 占位符规则 - -本 skill 写的 spec 是 CC 内部推理产物，不是用户审阅文档。**不允许** `【人工填写：...】` 占位符——A 阶段标记。需要具体值时： - -1. **先查** `.env.local` / `docs/07-环境配置.md` / `docs/04-技术规范.md` / `docs/06-UI交互规范.md` / `CLAUDE.md` / 现有代码 / 关联 prototype。值已落地某处 → 在 spec 中引用源 -2. **再问**：查不到 → `AskUserQuestion` 问用户，记录答案到 spec -3. **绝不**留 `【人工填写：】` 占位符 - -## 执行步骤 - -1. **收集上下文**：确定本次 FE（由 `frontend-start` 派发时传入 `{ fe_id, name, associated_reqs[], associated_prototypes[] }`），读取证据： - - **页面骨架**：Read 所有 `associated_prototypes[]`（如 `prototype/dashboard.html` + `prototype/dashboard.html#metrics-section`；含 anchor 时聚焦相应区域），作为本 FE 涉及页面的布局权威 - - **业务规则**：Read 所有 `associated_reqs[]` 对应的 `docs/01-需求清单//.md`，提取业务校验规则、acceptance、UI 描述 - - **API 契约**：Read `docs/05-API接口契约.md`，按 `associated_reqs[]` 过滤出本 FE 消费的端点 - - **Design Tokens**：Read `docs/06-UI交互规范.md § 二`，作为色值/状态色的引用源 - - **前端组件库**：Read `docs/04-技术规范.md § 零` 找 `frontend.ui_lib`（如 Ant Design / Element Plus），决定组件选型 - -2. **交互式 Q&A**（参考下方"Q&A 原则"，本次为**前端阶段**头脑风暴）： - - 关注：组件树、页面状态机、交互流程、API 调用一致性、Design Tokens 引用、业务校验前端复刻 - - **不要**讨论 SQL / migration / controller / service / DTO（后端阶段已定） - - **一次一问** `AskUserQuestion`，仅对真模糊点；多选题优先 - - trade-off 直接内嵌 spec，**不设确认 gate** - -3. **写 spec 到 `docs/superpowers/specs/-.md`**： - - 按 `${CLAUDE_SKILL_DIR}/templates/fe-feature-spec-template.md` 渲染 - - 规格至少含： - - 关联 REQ + 关联原型（来自 frontend-start 派发的入参） - - 组件树（多个 prototype 文件 / 区域则按页面分块；推导自 prototype DOM） - - 页面状态机（loading / empty / error / 正常 / 表单提交中 至少 5 态；多页则按页列出） - - 消费的后端端点（与 docs/05 对齐，按本 FE 的 `associated_reqs[]` 过滤） - - 业务规则前端复刻清单（逐条，每条标注：规则描述 / 触发时机 / 报错文案 / 来源 REQ） - - Design Tokens 引用清单（本 FE 用到的 `var(--color-*)` 名称） - - 文件已存在 → 征求用户确认后覆盖 - -4. **Spec 自审**（inline 修，无须用户等待）： - - 所有顶级节非空 - - **全文不得出现** `TBD` / `@todo` / `controller` / `SQL` / `service` / `migration` 字样——前者代表 spec 未完成，后五者属于后端范畴不应出现。命中 → 修正后重渲染 - - **内部一致性** / **范围检查** / **歧义检查**（按 Q&A 原则） - -5. **输出 + 链 fe-feature-plan**（**直接做这两件事，不要输出"回交父 skill / 交给 caller / 等下一步 / 准备好了请检查"之类的桥接叙述**——那些会被解读为 turn 结束信号）： - - 输出一行 `fe-feature-brainstorm: → ` - - **同一 turn 内立即** `Skill(fe-feature-plan)` - -## Q&A 原则 - -- **一次一问** — 不堆问题 -- **多选题优先** — 答更快 -- **仅对真模糊点问** — 不造确认问题 -- **YAGNI** — 删不必要的功能 -- **渐进理解** — 不明白就问 -- **无审批 gate** — 写 spec 即 commit - -## 参考 - -- `${CLAUDE_SKILL_DIR}/templates/fe-feature-spec-template.md` -- 上游：`frontend-start`（每个未完成 FE 派发到此） -- 下游：`fe-feature-plan` diff --git a/skills/coding/fe-feature-brainstorm/templates/fe-feature-spec-template.md b/skills/coding/fe-feature-brainstorm/templates/fe-feature-spec-template.md deleted file mode 100644 index a2b7d9f..0000000 --- a/skills/coding/fe-feature-brainstorm/templates/fe-feature-spec-template.md +++ /dev/null @@ -1,55 +0,0 @@ -# 前端功能规格 — {{fe_id}} {{name}} - -> 关联 REQ：{{associated_reqs}} -> 关联原型：{{associated_prototypes}} -> 日期：{{date}} - -## 一、功能概述 - -{{feature_overview}} - -## 二、组件树 - - - -``` -{{component_tree}} -``` - -## 三、页面状态机 - -| # | 状态 | 触发条件 | 视觉表现 | 用户可执行操作 | -|---|------|---------|---------|--------------| -{{state_machine_rows}} - -至少包含：loading / empty / error / 正常 / 提交中 五态。 - -## 四、消费的后端端点 - -| # | 方法 | 路径 | 触发时机 | 关联 REQ | -|---|------|------|---------|---------| -{{endpoint_rows}} - -## 五、业务规则前端复刻清单 - -| # | 规则描述 | 触发时机 | 报错文案 | 来源 REQ | -|---|---------|---------|---------|---------| -{{validation_rows}} - -> **要求**：每条规则必须在前端 form-level 校验中复刻，不仅依赖后端报错。文案与后端语义一致。 - -## 六、Design Tokens 引用清单 - - - -``` -{{token_list}} -``` - -## 七、交互流程关键路径 - -{{interaction_flow}} - -## 八、备注与开放问题 - -{{open_questions}} diff --git a/skills/coding/fe-feature-plan/SKILL.md b/skills/coding/fe-feature-plan/SKILL.md deleted file mode 100644 index fe190c6..0000000 --- a/skills/coding/fe-feature-plan/SKILL.md +++ /dev/null @@ -1,142 +0,0 @@ ---- -name: fe-feature-plan -description: 前端功能循环第 2 步。将 FE 规格转任务级实现计划（每任务 2-5 分钟，含组件路径、props 契约、测试意图），产出到 docs/superpowers/plans/，链入 fe-feature-tdd。 -user-invocable: false -allowed-tools: Read Write Grep Skill AskUserQuestion ---- - -**所有输出必须使用中文。** - -# fe-feature-plan - -## 阶段范围（前端） - -把当前 FE 的规格转成任务级实现计划。任务粒度限定为：**组件文件 / 路由配置 / store hook / API client 包装函数**。**不允许**生成涉及后端文件（controller / service / repository / SQL）的任务。 - -## 计划写作原则 - -- Plan 告诉 TDD 执行者**做什么**，不是**怎么写代码**——执行者是 `fe-feature-tdd`（同一模型，全上下文） -- Plan 锁定**文件边界 + 测试意图 + props 契约 + 完成判据**；代码由 TDD 红绿循环产出 -- **禁止 dump 整个文件内容**（vue/react 组件源码、config 文件）到 plan -- 每个任务标注"测试先行类型" = **jsdom 组件测试** OR **Playwright E2E** -- DRY、YAGNI、TDD、frequent commits - -## 占位符规则 - -每个 step 必须写实际内容。以下绝不出现： - -- `TBD` / `TODO` / `implement later` / `fill in details` -- **`【人工填写：】`** — A 阶段标记。需要具体值时：先查 `.env.local` / `docs/07` / `docs/04` / `docs/09` / 现有代码并引用源；否则 `AskUserQuestion` -- 涉及后端文件（`backend/` / `sql/` / `scripts/`）的任务——**硬护栏** -- 未在任何 task 定义的组件 / hook / API client 函数 - -## 执行步骤 - -1. **收集输入**： - - 当前 FE 的规格 `docs/superpowers/specs/-.md`（不存在则报错） - - `docs/04-技术规范.md § 一前端架构`（路由 / 状态库 / 组件目录约定 / 测试栈） - - `docs/09-项目目录结构.md § 前端目录结构`（文件落盘位置规范） - - 相关代码指针（通过 `Grep` 在 `frontend/` 下定位现有前端文件） - -2. **范围检查**：spec 跨多页/多业务 → 提示拆分 - -3. **文件结构推导**： - - 组件 / 路由 / hook / API client 各放哪里（依 docs/09 § 前端目录结构） - - 每个文件单一职责 - - 同 feature 的相关文件放一起 - -4. **任务粒度推导**（参考下方"任务原则"）： - - 每个任务 = 一个 red-green-commit 单元 - - 4 个 step：写失败测试 → 实现最小代码 → 子会话验证 PASS → commit - - 任务粒度 2-5 分钟 - - 每个任务必须含：`test_file::test_name` + `impl_file` + 完成判据 + "测试先行类型"标注 - -5. **写 plan 到 `docs/superpowers/plans/-.md`**： - - 按 `${CLAUDE_SKILL_DIR}/templates/fe-feature-plan-template.md` 渲染 - - 文件已存在 → 征求用户确认后覆盖 - -6. **Plan 自审**（inline 修，无须用户等待）： - - 每个任务必须含 `test_file::test_name`、`impl_file`、完成标准 - - **每个任务的 `impl_file` 路径必须以 `frontend/` 开头**（或 `docs/09` 声明的前端根目录）；命中 `backend/` / `sql/` / `scripts/` → 修正后重渲染 - - **占位符扫描**：`TBD` / `【人工填写：】` → 修 - - **Spec coverage**：spec 每节能指向至少一个 task 吗 - - **类型一致性**：组件 props 类型 / hook 签名跨 task 一致 - -7. **输出 + 链 fe-feature-tdd**（**直接做这两件事，不要输出"回交父 skill / 交给 caller / 等下一步 / 准备好了请检查"之类的桥接叙述**——那些会被解读为 turn 结束信号）： - - 输出一行 `fe-feature-plan: → ` - - **同一 turn 内立即** `Skill(fe-feature-tdd)` - -## 任务原则 - -### Plan 文件头 - -每个 plan 必须以以下头部开始： - -```markdown -# [FE Feature Name] Implementation Plan - -> **Execution:** Parent skill `fe-feature-tdd` executes this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. - -**Goal:** [一句话描述] - -**Architecture:** [2-3 句方法论] - -**Tech Stack:** [关键技术 / 库] - ---- -``` - -### Task 结构 - -每个 task 是 red-green-commit 单元： - -````markdown -### Task N: [组件名] - -**Files:** -- Create: `frontend/src/components/LoginForm.tsx` -- Test: `frontend/src/components/LoginForm.test.tsx` -- 测试先行类型: jsdom 组件测试 - -**Props/API shape**（只写需要约束实现的签名）: -- ` Promise} loading={boolean} />` - -- [ ] **Step 1: 写失败测试** - - 测试名: `LoginForm renders username and password fields` - - 意图: 验证组件渲染 username / password input，submit button disabled when empty - - 子会话确认 FAIL（组件不存在） - -- [ ] **Step 2: 实现最小代码** - - 目标: 让 Step 1 测试通过；不多做 - - 涉及文件: `frontend/src/components/LoginForm.tsx` - -- [ ] **Step 3: 子会话验证 PASS** - -- [ ] **Step 4: Commit** - - `git add <文件>` - - `git commit -m "feat(fe): LoginForm 组件 FE-01"` -```` - -### 允许的代码块场景 - -少数例外，需要写死而非让 TDD 自由发挥： - -- **路由配置**：`routes.ts` 中 path 注册（路径是契约级） -- **API client 契约**：fetch 包装函数签名 + headers + 错误码 mapping -- **Design Tokens 名称**：`var(--color-primary)` 列表（跨组件复用） -- **测试断言形状**（可选） - -除此之外一律散文 + 签名描述，**不贴完整组件源码**。 - -### 记住 - -- Exact file paths always（必须以 `frontend/` 开头） -- 测试先行类型必须明确（jsdom / Playwright） -- 组件 props / hook 签名 / API client 函数签名 — **必须写死** -- Internal implementation code — **不写**；留给 TDD 阶段 - -## 参考 - -- `${CLAUDE_SKILL_DIR}/templates/fe-feature-plan-template.md` -- 上游：`fe-feature-brainstorm` -- 下游：`fe-feature-tdd` diff --git a/skills/coding/fe-feature-plan/templates/fe-feature-plan-template.md b/skills/coding/fe-feature-plan/templates/fe-feature-plan-template.md deleted file mode 100644 index d3a2091..0000000 --- a/skills/coding/fe-feature-plan/templates/fe-feature-plan-template.md +++ /dev/null @@ -1,47 +0,0 @@ -# 前端功能计划 — {{fe_id}} {{name}} - -> 规格：docs/superpowers/specs/{{date}}-{{fe_id}}.md -> 关联原型：{{associated_prototypes}} -> 关联 REQ：{{associated_reqs}} -> 日期：{{date}} - -## 一、依赖与前置条件 - -- 前置 FE：{{prerequisite_fes}} -- 共享组件：{{shared_components}} -- 路由配置文件：{{router_file}} - -## 二、任务清单 - -每行一个任务，2-5 分钟可完成。`test_file::test_name` 先行写失败测试，`impl_file` 写最小实现使其通过。 - -| # | 任务 | 测试先行类型 | test_file::test_name | impl_file | 完成判据 | -|---|------|-------------|---------------------|-----------|---------| -{{task_rows}} - -> **路径约束**：所有 `impl_file` 必须以 `frontend/`（或 docs/09 声明的前端根目录）开头。 -> **测试先行类型**：`jsdom`（组件单测，vitest/jest）或 `e2e`（Playwright）。 - -## 三、组件 props 契约 - -| 组件 | props | 类型 | 必填 | 说明 | -|------|-------|------|------|------| -{{props_rows}} - -## 四、状态管理 - - - -{{state_management}} - -## 五、API client 包装 - -| 函数名 | HTTP 方法 | 路径 | 入参 | 返回 | -|--------|----------|------|------|------| -{{api_client_rows}} - -> 函数实现必须基于项目统一 API client（见 docs/04 § 一），不允许直接 `fetch` / `axios` 拼路径。 - -## 六、风险与回退 - -{{risks}} diff --git a/skills/coding/fe-feature-review/SKILL.md b/skills/coding/fe-feature-review/SKILL.md deleted file mode 100644 index 58e0465..0000000 --- a/skills/coding/fe-feature-review/SKILL.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -name: fe-feature-review -description: 前端功能循环第 5 步。AI 自审 FE 的 diff（专用前端 reviewer），approve 则回 frontend-start；request-changes 则自修复 + 重 verify，循环上限 5 轮。 -user-invocable: false -allowed-tools: Read Write Edit Skill Agent Bash(git add *) Bash(git commit *) ---- - -**所有输出必须使用中文。** - -# fe-feature-review - -委托 `fe-code-reviewer` agent（前端专用 reviewer，不复用 superpower-code-reviewer）对当前 FE 引入的代码改动做 AI 自审。`approve` 回 frontend-start 推进下一 FE；`request-changes` 自修复 must-fix 并重新 verify，最多 5 轮。 - -## 执行步骤 - -1. 派发 `Agent(subagent_type=fe-code-reviewer)`，把本 FE 引入的代码 diff、规格（`docs/superpowers/specs/-.md`）、本 FE 关联的所有 prototype 文件（spec 顶部的 `关联原型` 列表）作为输入。 - -2. 按 `${CLAUDE_SKILL_DIR}/templates/fe-feature-review-template.md` 渲染审阅报告，写入 `docs/superpowers/reviews/-.md`。`verdict` 取 `approve` 或 `request-changes`。 - -3. 按 `verdict` 分派： - - **approve** - - `Edit docs/08-模块任务管理.md § 三`，把本 FE 下 `- [ ] ...` 改为 `- [x] ...`（仅 FE 级可视化；前端阶段完成仍以 `整体里程碑:` 字段 + 本地 `git tag -l` 为准） - - 输出 `fe-feature-review: round 通过`，调用 `Skill(frontend-start)` 推进下一 FE 或进入 test-gate(phase=frontend) - - **request-changes（round < 5）** - - 逐项编辑 `must_fix[]` 指向的代码文件 - - 按 `${CLAUDE_SKILL_DIR}/templates/commit-message-template.md` 格式 commit：`fix(): 修复 review round must-fix REQ_ID: ` - - 调用 `Skill(fe-feature-verify)` 重新验证；verify 通过后会再次链回本 skill，round `` 重审 - - **request-changes（round == 5）** - - 停止并打印摘要，升级给用户手工介入；不再自动修复，不回调 frontend-start - -## 参考 - -- `${CLAUDE_SKILL_DIR}/templates/fe-feature-review-template.md` -- `${CLAUDE_SKILL_DIR}/templates/commit-message-template.md` -- 委托：`fe-code-reviewer` agent（本插件 `agents/fe-code-reviewer.md`，前端专用，硬编码 7 维 review checklist） -- 上游：`fe-feature-verify` -- 下游：`frontend-start`（approve）/ `fe-feature-verify`（request-changes 时重验） diff --git a/skills/coding/fe-feature-review/templates/commit-message-template.md b/skills/coding/fe-feature-review/templates/commit-message-template.md deleted file mode 100644 index ecf5222..0000000 --- a/skills/coding/fe-feature-review/templates/commit-message-template.md +++ /dev/null @@ -1 +0,0 @@ -{{type}}({{scope}}): {{subject}} {{req_id}} diff --git a/skills/coding/fe-feature-review/templates/fe-feature-review-template.md b/skills/coding/fe-feature-review/templates/fe-feature-review-template.md deleted file mode 100644 index 6c6c1cf..0000000 --- a/skills/coding/fe-feature-review/templates/fe-feature-review-template.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -fe_id: {{fe_id}} -date: {{date}} -round: {{round}} -reviewer: fe-code-reviewer ---- - -# Review: {{fe_id}} — round {{round}} - -## 结论 -{{verdict}} （approve / request-changes） - -## Must-fix -{{#each must_fix}} -- [{{severity}}] {{file}}:{{line}} — {{issue}}（建议：{{suggestion}}） -{{/each}} - -## Nice-to-have -{{#each nice_to_have}} -- {{file}}:{{line}} — {{suggestion}} -{{/each}} - -## 维度核查（fe-code-reviewer 7 维） - -| # | 维度 | 状态 | 备注 | -|---|------|------|------| -| 1 | prototype 一致性 | {{dim_prototype}} | {{dim_prototype_note}} | -| 2 | Design Tokens | {{dim_tokens}} | {{dim_tokens_note}} | -| 3 | 无障碍 | {{dim_a11y}} | {{dim_a11y_note}} | -| 4 | 响应式 | {{dim_responsive}} | {{dim_responsive_note}} | -| 5 | 业务校验前端复刻 | {{dim_validation}} | {{dim_validation_note}} | -| 6 | API 调用一致性 | {{dim_api}} | {{dim_api_note}} | -| 7 | 状态机覆盖 | {{dim_state}} | {{dim_state_note}} | - -## 反例 / 测试覆盖缺口 - -{{gaps}} diff --git a/skills/coding/fe-feature-tdd/SKILL.md b/skills/coding/fe-feature-tdd/SKILL.md deleted file mode 100644 index 4cbf6fe..0000000 --- a/skills/coding/fe-feature-tdd/SKILL.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -name: fe-feature-tdd -description: 前端功能循环第 3 步。按 plan 逐任务做 TDD（失败测试 → 实现 → 通过 → commit），组件测试用 jsdom，E2E 派子会话跑 Playwright。 -user-invocable: false -allowed-tools: Read Write Edit Agent Skill Bash(git add *) Bash(git commit *) ---- - -**所有输出必须使用中文。** - -# fe-feature-tdd - -按 plan 文件逐任务做 TDD：写失败测试 → 写最小实现 → 确认通过 → commit。**所有测试运行强制派发到 Agent 子会话**，主会话只接收 JSON 结果。 - -## 路径护栏（前端阶段） - -- 任务的 `impl_file` 路径若**不以** `frontend/`（或项目实际前端根目录，从 `docs/09-项目目录结构.md § 前端目录结构` 取）开头 → 硬停并打印：`fe-feature-tdd 不允许写非前端文件：。前端阶段任务的 impl_file 必须落在前端目录下。` -- 命中 `backend/` / `sql/` / `scripts/` → 同上硬停 -- 不允许在主会话直接 `pnpm playwright` / `pnpm test` / `pnpm e2e`，必须派发子会话 - -## 执行步骤 - -1. 加载计划文件 `docs/superpowers/plans/-.md`。 - -2. 从 `docs/04-技术规范.md § 零 frontend` 取测试栈： - - `frontend.unit_test_runner`：vitest / jest（默认 vitest） - - `frontend.e2e_runner`：playwright（默认 playwright） - - `frontend.test_command` / `frontend.e2e_command`：执行命令（缺失则用 `pnpm test:ci` / `pnpm e2e:ci`） - -3. 按顺序处理每个任务： - - a. 在 `test_file::test_name` 处写**失败**测试： - - `测试先行类型 = jsdom`：在 jsdom 环境下用 vitest/jest 写组件单测（render + 断言 DOM / 交互后状态变化） - - `测试先行类型 = e2e`：在 `frontend/e2e/` 写 Playwright 测试（headless） - - b. 派发 Agent 子会话（general-purpose）运行该测试，子会话只返回 `{command, exit_code, failing_assertion}` JSON，确认失败。 - - c. 在 `impl_file` 处写**最小**实现使测试通过。**严格遵守**： - - 路径必须以 `frontend/`（或 docs/09 声明的前端根）开头（违反 → 硬停，见护栏） - - 色值用 `var(--color-*)`（来自 spec § 六），不硬编码 hex - - 业务校验按 spec § 五 在 form-level 复刻 - - d. 再次派发子会话确认通过。 - - e. 同一测试 >10 次修复仍失败 → 调用 `Skill(interrupt-check)`（中断 #1：测试反复失败）。 - - f. 按 `${CLAUDE_SKILL_DIR}/templates/commit-message-template.md` 格式 commit： - - `scope` = 任务模块（如组件名 `dashboard` / `user-form`） - - `subject` ≤ 50 字符 - - 必含 trailer `REQ_ID: `（如 `REQ_ID: FE-01`） - -4. 全部任务完成 → 调用 `Skill(fe-feature-verify)`。 - -## 护栏 - -- **绝不**在主会话直接跑 `pnpm test` / `pnpm e2e` / `pnpm playwright`，必须通过子会话 -- **绝不**在 `impl_file` 中写非 `frontend/` 路径（路径护栏会硬停） -- 每次 commit 必须含 `REQ_ID: FE-NN` trailer；不混合无关改动到同一 commit -- 不硬编码颜色 hex；token 引用必须对齐 spec § 六 - -## 参考 - -- `${CLAUDE_SKILL_DIR}/templates/commit-message-template.md` -- 守门：`interrupt-check`（仅在步骤 3.e 触发，条件 1） -- 上游：`fe-feature-plan` -- 下游：`fe-feature-verify` diff --git a/skills/coding/fe-feature-tdd/templates/commit-message-template.md b/skills/coding/fe-feature-tdd/templates/commit-message-template.md deleted file mode 100644 index ecf5222..0000000 --- a/skills/coding/fe-feature-tdd/templates/commit-message-template.md +++ /dev/null @@ -1 +0,0 @@ -{{type}}({{scope}}): {{subject}} {{req_id}} diff --git a/skills/coding/fe-feature-verify/SKILL.md b/skills/coding/fe-feature-verify/SKILL.md deleted file mode 100644 index ad9f192..0000000 --- a/skills/coding/fe-feature-verify/SKILL.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -name: fe-feature-verify -description: 前端功能循环第 4 步。把 FE 的组件测试 + E2E 派发到子会话执行，按模板渲染证据。无证据不声称完成。 -user-invocable: false -allowed-tools: Skill Read Agent ---- - -**所有输出必须使用中文。** - -# fe-feature-verify - -把当前 FE 的测试派发到 Agent 子会话执行，按模板把结构化结果渲染成证据。**主会话从不直接跑测试**，也不自由编写证据。 - -## 执行步骤 - -1. 从 plan 文件确定本 FE 的测试目标： - - 单测目标：plan § 二中所有 `测试先行类型 = jsdom` 的 test_file 列表 → 拼成 vitest/jest 过滤模式 - - E2E 目标：所有 `测试先行类型 = e2e` 的 test_file 列表 → 拼成 Playwright spec 过滤模式 - -2. 派发 Agent 子会话（general-purpose）依次运行两个目标，子会话只返回结构化 JSON（不输出描述文字）： - - ```json - { - "unit": { - "command": "", - "exit_code": , - "passed": , - "failed": , - "failed_list": ["", ...], - "stdout_excerpt": "<最后 30 行或最相关的失败片段>" - }, - "e2e": { - "command": "", - "exit_code": , - "passed": , - "failed": , - "failed_list": ["", ...], - "stdout_excerpt": "<最后 30 行或最相关的失败片段>" - } - } - ``` - - 命令从 `docs/04-技术规范.md § 零 frontend.test_command` / `frontend.e2e_command` 取，缺失则用默认 `pnpm test:ci` / `pnpm e2e:ci`。 - -3. 按 `${CLAUDE_SKILL_DIR}/templates/fe-feature-verify-evidence-template.md` 渲染证据并打印到会话。 - -4. **任一目标 `exit_code != 0` 或 `failed > 0`** → 停止，不进入 review。 - -5. 全部通过 → 调用 `Skill(fe-feature-review)`。 - -## 护栏 - -- **绝不**在主会话直接跑测试，必须通过子会话 -- **绝不**自由编写证据正文，必须从模板渲染 -- 不要把原始 stdout 全文塞进主会话（`stdout_excerpt` ≤ 30 行） - -## 参考 - -- `${CLAUDE_SKILL_DIR}/templates/fe-feature-verify-evidence-template.md` -- 上游：`fe-feature-tdd` -- 下游：`fe-feature-review` diff --git a/skills/coding/fe-feature-verify/templates/fe-feature-verify-evidence-template.md b/skills/coding/fe-feature-verify/templates/fe-feature-verify-evidence-template.md deleted file mode 100644 index 1be7252..0000000 --- a/skills/coding/fe-feature-verify/templates/fe-feature-verify-evidence-template.md +++ /dev/null @@ -1,33 +0,0 @@ -## Verify evidence — {{fe_id}} - -### 单元测试（jsdom） - -- 命令: `{{unit.command}}` -- 子会话: {{unit.subagent_id}} -- 退出码: {{unit.exit_code}} -- 通过用例数: {{unit.passed}} -- 失败用例数: {{unit.failed}} -- 失败列表: {{unit.failed_list}} - -关键 stdout 片段 (≤30 行): - -``` -{{unit.stdout_excerpt}} -``` - -### E2E 测试（Playwright） - -- 命令: `{{e2e.command}}` -- 子会话: {{e2e.subagent_id}} -- 退出码: {{e2e.exit_code}} -- 通过用例数: {{e2e.passed}} -- 失败用例数: {{e2e.failed}} -- 失败列表: {{e2e.failed_list}} - -关键 stdout 片段 (≤30 行): - -``` -{{e2e.stdout_excerpt}} -``` - -结论: {{conclusion}} （pass = 两段都 pass / fail = 任一 fail） diff --git a/skills/coding/feature-brainstorm/SKILL.md b/skills/coding/feature-brainstorm/SKILL.md deleted file mode 100644 index 4e768e8..0000000 --- a/skills/coding/feature-brainstorm/SKILL.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -name: feature-brainstorm -description: 功能循环第 1 步。针对单个 REQ-XXX-NNN 做交互式 Q&A + 写规格，产出到 docs/superpowers/specs/，链入 feature-plan。 -user-invocable: false -allowed-tools: Read Write Skill AskUserQuestion Bash(mysql *) ---- - -**所有输出必须使用中文。** - -# feature-brainstorm - -## 阶段范围（后端） - -本 skill 服务于**后端阶段**。产出范围限定为 controller / service / repository / DTO / 校验 / SQL migration / REST 契约。读 docs/01 REQ 卡片时**忽略 UI 描述**（输入控件类型、按钮位置、列表布局等），但**校验规则、业务规则**仍要落到后端 DTO + service。UI 实现统一推迟到前端阶段（fe-feature-*）。 - -## 占位符规则 - -本 skill 写的 spec 是 CC 内部推理产物，不是用户审阅文档。**不允许** `【人工填写：...】` 占位符——A 阶段 `docs/01~10` / `CLAUDE.md` / `.env.local` 才用那个标记。需要具体值时： - -1. **先查** `.env.local` / `docs/07-环境配置.md` / `CLAUDE.md` / 现有代码。值已落地某处 → 在 spec 中引用源（例 "JWT_SECRET 从 `.env.local` 读取，`application.yml` 用 `${JWT_SECRET}` 注入"） -2. **再问**：查不到 → `AskUserQuestion` 问用户，记录答案到 spec -3. **绝不**留 `【人工填写：】` 占位符；若 1 + 2 都解决不了，spec 必须写出具体阻塞点（不是泛化的人工填写标记），Q&A 继续直到解决 - -## 执行步骤 - -1. **收集上下文**：确定本次 REQ-XXX-NNN（由 module-start 派发时指定），读取： - - REQ 卡片 `docs/01-需求清单//.md` - - 涉及的数据表定义（取自 docs/03 或实时 mysql 查询） - -2. **交互式 Q&A**（参考下方"Q&A 原则"）： - - **先评估 scope**：单 spec 容纳得下吗？跨多个独立子系统（如"含登录 + 文件存储 + 计费 + 分析"）→ 先提示分解，每个子项目独立 brainstorm - - **一次一问** `AskUserQuestion`，仅对真模糊点；多选题优先 - - 决策完成后挑一种 approach；trade-off 直接内嵌 spec，**不设确认 gate** - -3. **写 spec 到 `docs/superpowers/specs/-.md`**： - - 按 `${CLAUDE_SKILL_DIR}/templates/feature-spec-template.md` 渲染 - - 覆盖：goal / 输入输出 / 业务规则 / 约束 / schema / API 引用 / acceptance criteria - - 文件已存在 → 征求用户确认后覆盖 - -4. **Spec 自审**（inline 修，无须用户等待）： - - **占位符扫描**：`TBD` / `TODO` / `【人工填写：】` / 含糊段 → 修（按"占位符规则"流程解决） - - **内部一致性**：节与节是否矛盾？架构是否匹配功能描述？ - - **范围检查**：单 plan 能消化吗？还是需要分解 - - **歧义检查**：任何 requirement 两种解读？挑一个写明 - - fix inline，无须 re-review。 - -5. **输出 + 链 feature-plan**（**直接做这两件事，不要输出"回交父 skill / 交给 caller / 等下一步 / 准备好了请检查"之类的桥接叙述**——那些会被解读为 turn 结束信号）： - - 输出一行 `feature-brainstorm: → ` - - **同一 turn 内立即** `Skill(feature-plan)` - -## Q&A 原则 - -- **一次一问** — 不堆问题 -- **多选题优先** — 答更快 -- **仅对真模糊点问** — 不造确认问题 -- **YAGNI** — 删 spec 中不必要的功能 -- **渐进理解** — 不明白就问 -- **无审批 gate** — 写 spec 即 commit；分歧落地为具体 Q&A 项，不靠"等用户确认" - -## 参考 - -- `${CLAUDE_SKILL_DIR}/templates/feature-spec-template.md` -- 上游：`module-start` -- 下游：`feature-plan` diff --git a/skills/coding/feature-brainstorm/templates/feature-spec-template.md b/skills/coding/feature-brainstorm/templates/feature-spec-template.md deleted file mode 100644 index 09715ab..0000000 --- a/skills/coding/feature-brainstorm/templates/feature-spec-template.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -req_id: {{req_id}} -date: {{date}} -module: {{module}} ---- - -# Spec: {{req_id}} — {{title}} - -## 目标 -{{goal}} - -## 输入 / 触发 -{{input}} - -## 输出 / 结果 -{{output}} - -## 业务规则 -{{rules}} - -## 边界与约束 -{{constraints}} - -## 依赖的 schema 表 / 字段 -{{schema_refs}} - -## 依赖的接口 -{{api_refs}} - -## 验收标准 -{{acceptance}} diff --git a/skills/coding/feature-plan/SKILL.md b/skills/coding/feature-plan/SKILL.md deleted file mode 100644 index 9e6cd12..0000000 --- a/skills/coding/feature-plan/SKILL.md +++ /dev/null @@ -1,143 +0,0 @@ ---- -name: feature-plan -description: 功能循环第 2 步。将 spec 转任务级 TDD 计划（每任务 2-5 分钟），产出到 docs/superpowers/plans/，链入 feature-tdd。 -user-invocable: false -allowed-tools: Read Write Grep Skill AskUserQuestion ---- - -**所有输出必须使用中文。** - -# feature-plan - -## 阶段范围（后端） - -本 skill 服务于**后端阶段**。任务粒度限定为后端模块文件：controller / service / repository / DTO / 校验 / SQL migration。**禁止**生成 `frontend/` 路径下的实现任务——UI 实现统一推迟到前端阶段（fe-feature-*）。 - -## 计划写作原则 - -- Plan 告诉 TDD 执行者**做什么**，不是**怎么写代码**——执行者是 `feature-tdd`（同一模型，全上下文），不是机械复制粘贴员 -- Plan 锁定**文件边界 + 测试意图 + API 形状 + 完成判据**；代码由 TDD 红绿循环产出 -- **禁止 dump 整个文件内容**（pom.xml / entity 类 / config 文件）到 plan——plan 和代码会成为两个 source of truth 并漂移；2000+ 行 plan 浪费上下文 -- DRY、YAGNI、TDD、frequent commits - -## 占位符规则 - -每个 step 必须写实际内容。以下属于 **plan failures**，绝不出现： - -- `TBD` / `TODO` / `implement later` / `fill in details` -- **`【人工填写：】`** — 这是 A 阶段标记（`docs/01~10` / `CLAUDE.md` / `.env.local`），B 阶段 plan **绝不能出现**。需要具体值时： - 1. 先查 `.env.local` / `docs/07-环境配置.md` / `CLAUDE.md` / 现有代码并在 plan 中引用源 - 2. 否则 `AskUserQuestion` 问用户并记录答案 -- "Add appropriate error handling" / "add validation"（要具体到哪些错误码 / 哪些字段） -- "Similar to Task N"（相似任务各自写清楚测试意图 + 完成判据，不互相链接） -- 未在任何 task 定义的 types / functions / methods（类/方法首次出现的 task 必须给出 API 签名） - -> 散文级"做什么"是 OK 的——执行器（`feature-tdd`）会在 TDD 循环里决定"怎么写"。plan 的义务是**约束范围**，不是**替 TDD 写代码**。 - -## 执行步骤 - -1. **收集输入**： - - spec 文件 `docs/superpowers/specs/-.md`（不存在则报错） - - 相关代码指针（通过 `Grep` 在现有代码定位待修改文件） - - `docs/04-技术规范.md` 与 `docs/09-项目目录结构.md`（编码规范 + 目录规范） - -2. **范围检查**：spec 跨多个独立子系统 → 提示拆分，每个 plan 应能独立产出可工作、可测试的软件 - -3. **文件结构推导**： - - 哪些文件 create / modify - - 每个文件单一职责，well-defined interface - - 一起变化的文件放一起；不按技术层切分 - -4. **任务粒度推导**（参考下方"任务原则"）： - - 每个任务 = 一个 red-green-commit 单元 - - 4 个 step：写失败测试 → 实现最小代码 → 子会话验证 PASS → commit - - 任务粒度 2-5 分钟 - -5. **写 plan 到 `docs/superpowers/plans/-.md`**： - - 按 `${CLAUDE_SKILL_DIR}/templates/feature-plan-template.md` 渲染 - - 文件已存在 → 征求用户确认后覆盖 - -6. **Plan 自审**（inline 修，无须用户等待）： - - **占位符扫描**：按"占位符规则"清单逐项 grep；命中即修 - - **Spec coverage**：skim spec 每节，能指向至少一个 task 吗？list gaps 并补 task - - **类型一致性**：tasks 之间签名 / 方法名 / 属性名 / 错误码是否一致（Task 3 的 `clearLayers()` 和 Task 7 的 `clearFullLayers()` 是 bug） - -7. **输出 + 链 feature-tdd**（**直接做这两件事，不要输出"回交父 skill / 交给 caller / 等下一步 / 准备好了请检查"之类的桥接叙述**——那些会被解读为 turn 结束信号）： - - 输出一行 `feature-plan: → ` - - **同一 turn 内立即** `Skill(feature-tdd)` - -## 任务原则 - -### Plan 文件头 - -每个 plan 必须以以下头部开始： - -```markdown -# [Feature Name] Implementation Plan - -> **Execution:** Parent skill `feature-tdd` executes this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. - -**Goal:** [一句话描述] - -**Architecture:** [2-3 句方法论] - -**Tech Stack:** [关键技术 / 库] - ---- -``` - -### Task 结构 - -每个 task 是 red-green-commit 单元。捕获意图和边界，代码留给 TDD： - -````markdown -### Task N: [组件名] - -**Files:** -- Create: `exact/path/to/File.java` -- Modify: `exact/path/to/Existing.java:123-145` -- Test: `tests/exact/path/to/FileTest.java` - -**API shape**（只写需要约束实现的签名；内部实现留给 TDD）: -- `LoginService#login(LoginRequest req) : LoginResponse` -- `throws AccountLockedException when iLoginFailCount ≥ 5 within tLockUntil window` - -- [ ] **Step 1: 写失败测试** - - 测试名: `LoginServiceTest#loginWithBadPassword_incrementsFailCount_returns40101` - - 意图: 错误密码 → `iLoginFailCount += 1`；第 5 次 → 设置 `tLockUntil = now + 15min`；返回码 40101 - - 子会话确认 FAIL（函数/类不存在） - -- [ ] **Step 2: 实现最小代码** - - 目标: 让 Step 1 测试通过；不多做 - - 涉及文件: `LoginService.java`, `SftLoginInfoMapper.java` - -- [ ] **Step 3: 子会话验证 PASS** - -- [ ] **Step 4: Commit** - - `git add <文件>` - - `git commit -m "feat(sys): 登录失败计数 + 锁定 REQ-SYS-001"` -```` - -### 允许的代码块场景 - -少数例外，需要写死而非让 TDD 自由发挥： - -- **DDL / migration 文件**：`V_n__*.sql` 的 ALTER/CREATE 语句——schema 是事实源、不是 TDD 红绿产物 -- **合同级常量**：API 错误码表、JWT claim 名、Redis key 模式——跨模块消费，必须在 plan 锁定 -- **测试断言形状**（可选）：一句话说不清"测什么"时，给个 3-5 行断言 sketch 是 OK 的 - -除此之外一律散文 + 签名描述，**不贴完整文件**。 - -### 记住 - -- Exact file paths always -- Exact commands with expected output（测试运行 + git 操作） -- API signatures / class names / error codes / contract values — **必须写死** -- Internal implementation code — **不写**；留给 TDD 阶段 -- DRY、YAGNI、TDD、frequent commits - -## 参考 - -- `${CLAUDE_SKILL_DIR}/templates/feature-plan-template.md` -- 上游：`feature-brainstorm` -- 下游：`feature-tdd` diff --git a/skills/coding/feature-plan/templates/feature-plan-template.md b/skills/coding/feature-plan/templates/feature-plan-template.md deleted file mode 100644 index 00d36f6..0000000 --- a/skills/coding/feature-plan/templates/feature-plan-template.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -req_id: {{req_id}} -date: {{date}} -spec_ref: docs/superpowers/specs/{{date}}-{{req_id}}.md ---- - -# Plan: {{req_id}} - -## Schema 改动 -{{schema_change_decision}} - -## 文件变更清单 -{{#each files}} -- `{{path}}` — {{action}}（{{rationale}}） -{{/each}} - -## 任务步骤 -{{#each tasks}} -### Task {{index}}: {{title}} -- 失败测试: `{{test_file}}::{{test_name}}` — {{test_intent}} -- 实现路径: `{{impl_file}}` -- 完成判据: {{done_when}} -{{/each}} - -## 提交计划 -{{#each commits}} -- `{{message}}`（覆盖 Task {{task_index}}） -{{/each}} diff --git a/skills/coding/feature-review/SKILL.md b/skills/coding/feature-review/SKILL.md index bd603c1..26f53a9 100644 --- a/skills/coding/feature-review/SKILL.md +++ b/skills/coding/feature-review/SKILL.md @@ -1,6 +1,6 @@ --- name: feature-review -description: 功能循环第 5 步。AI 自审 REQ 的 diff，approve 则回调 module-start；request-changes 则自修复 + 重 verify，循环上限 5 轮。 +description: 统一功能循环第 3 步（后端 REQ / 前端 FE 共用，由 phase 参数区分）。先派子会话跑验证测试（verify 阶段），通过后再派相应 reviewer agent 做 AI 自审（review 阶段），approve 回 phase-driver；request-changes 自修复 + 重验，最多 5 轮。 user-invocable: false allowed-tools: Read Write Edit Skill Agent Bash(git add *) Bash(git commit *) --- @@ -9,29 +9,128 @@ allowed-tools: Read Write Edit Skill Agent Bash(git add *) Bash(git commit *) # feature-review -委托 `superpower-code-reviewer` agent 对当前 REQ 引入的代码改动做 AI 自审，渲染审阅报告。`approve` 回模块主循环；`request-changes` 则自修复 must-fix 并重新 verify，最多 5 轮。 +统一功能循环第 3 步（verify + review 合并）。先派子会话运行功能测试（verify 阶段），通过后再委托对应 reviewer agent 做 AI 自审（review 阶段），渲染合并报告。`approve` 回 `phase-driver` 推进；`request-changes` 自修复 must-fix 并从 verify 阶段重新开始，最多 5 轮。 + +**入参（由 feature-tdd 传入）：** +- `phase`：`backend` | `frontend` +- `id`：`REQ-XXX-NNN`（backend）或 `FE-NN`（frontend） + +内部维护 `round` 计数器（首次 = 1）。 + +--- + +## 阶段差异 + +| 项目 | phase=backend | phase=frontend | +|------|-------------|----------------| +| 测试目标 | `./scripts/test.sh`（plan 确认）| vitest/jest 单测 + Playwright E2E（从 `docs/04 §零 frontend.test_command` / `frontend.e2e_command` 取；缺失用 `pnpm test:ci` / `pnpm e2e:ci`）| +| 测试 JSON 结构 | 单层 JSON（见"验证阶段"）| 两层 JSON：`unit` + `e2e`（见"验证阶段"）| +| Reviewer agent | `superpower-code-reviewer` | `fe-code-reviewer` | +| approve 写 docs/08 | §二 该 REQ 行 `[ ]`→`[x]` | §三 该 FE 行 `[ ]`→`[x]` | +| approve 输出 | `feature-review: round 通过` | `feature-review: round 通过` | + +--- ## 执行步骤 -1. 派发 `Agent(subagent_type=superpower-code-reviewer)`，把本 REQ 引入的代码 diff 与规格作为输入。 -2. 按 `${CLAUDE_SKILL_DIR}/templates/feature-review-template.md` 渲染审阅报告，写入 `docs/superpowers/reviews/-.md`。`verdict` 取 `approve` 或 `request-changes`。 -3. 按 `verdict` 分派： +### 阶段一：验证（Verify） + +1. **确定测试目标**： + - `phase=backend`：从 plan 文件或项目标准命令确定（如 Maven profile / `scripts/test.sh` path） + - `phase=frontend`：从 `docs/04-技术规范.md § 零 frontend` 取测试栈和测试命令；按 plan 中 task 的"测试先行类型"拆分单测目标（jsdom）和 E2E 目标（playwright） + +2. **派发 Agent 子会话（general-purpose）** 运行测试目标，子会话只返回结构化 JSON（不输出描述文字）： + + `phase=backend`： + ```json + { + "command": "", + "exit_code": , + "passed": , + "failed": , + "failed_list": ["", ...], + "stdout_excerpt": "<最后 30 行或最相关的失败片段>" + } + ``` + + `phase=frontend`： + ```json + { + "unit": { + "command": "", + "exit_code": , + "passed": , + "failed": , + "failed_list": ["", ...], + "stdout_excerpt": "<最后 30 行>" + }, + "e2e": { + "command": "", + "exit_code": , + "passed": , + "failed": , + "failed_list": ["", ...], + "stdout_excerpt": "<最后 30 行>" + } + } + ``` + +3. 渲染 `## 验证证据` 节（填入 `${CLAUDE_SKILL_DIR}/templates/feature-review-template.md` 的 verify 部分）。 + +4. **`exit_code != 0` 或 `failed > 0`**（任一目标失败）→ **停止，不进入 review 阶段**。等待下轮或用户介入。 + +5. 全部通过 → 进入 review 阶段。 + +--- + +### 阶段二：审阅（Review） + +6. **派发 reviewer agent**（把本 id 引入的代码 diff 与规格作为输入）： + - `phase=backend` → `Agent(subagent_type=superpower-code-reviewer)` + - `phase=frontend` → `Agent(subagent_type=fe-code-reviewer)`（同时提供规格文件 + 关联 prototype 文件列表，见 spec 顶部 `关联原型`） + +7. 渲染 `## 自审结论` 节（填入 `${CLAUDE_SKILL_DIR}/templates/feature-review-template.md` 的 review 部分），写入合并报告 `docs/superpowers/reviews/-.md`。`verdict` 取 `approve` 或 `request-changes`。 + +--- + +### 阶段三：按 verdict 分派 + +**approve** - **approve** - - `Edit docs/08-模块任务管理.md § 二`，把本模块下 `- [ ] ...` 改为 `- [x] ...`（仅功能级可视化；模块完成仍以 `里程碑:` 字段 + 本地 `git tag -l` 为准，不依赖此勾选） - - 输出 `feature-review: round 通过`，调用 `Skill(module-start)` +- `Edit docs/08-模块任务管理.md`： + - `phase=backend`：在 §二 找 `- [ ] ...` 改为 `- [x] ...` + - `phase=frontend`：在 §三 找 `- [ ] ...` 改为 `- [x] ...` + - （仅功能级可视化；模块 / 阶段完成仍以 `里程碑:` 字段 + 本地 `git tag -l` 为准，不依赖此勾选） +- 输出状态行（见上方阶段差异表），调用 `Skill(phase-driver)` 传入 `{ phase }` - **request-changes（round < 5）** - - 逐项编辑 `must_fix[]` 指向的代码文件 - - 按 `feature-tdd/templates/commit-message-template.md` 格式 commit：`fix(): 修复 review round must-fix ` - - 调用 `Skill(feature-verify)` 重新验证；verify 通过后会再次链回本 skill，round `` 重审 +**request-changes（round < 5）** - **request-changes（round == 5）** - - 停止并打印摘要，升级给用户手工介入；不再自动修复，不回调 module-start +- 逐项编辑 `must_fix[]` 指向的代码文件 +- 按 `${CLAUDE_SKILL_DIR}/templates/commit-message-template.md` 格式 commit： + `fix(): 修复 review round must-fix ` +- **重新执行本 skill 的验证阶段**（阶段一）；通过后进入 round `` 的 review 阶段 + +**request-changes（round == 5）** + +- 停止并打印摘要（本 id、5 轮 must-fix 列表汇总），升级给用户手工介入 +- 不再自动修复，不回调 `phase-driver` + +--- + +## 护栏 + +- **绝不**在主会话直接跑测试，必须通过子会话 +- **绝不**自由编写证据正文，必须从模板渲染 +- 不要把原始 stdout 全文塞进主会话（`stdout_excerpt` ≤ 30 行） +- verify 失败（exit_code≠0 或 failed>0）→ 硬停，不进 review + +--- ## 参考 -- `${CLAUDE_SKILL_DIR}/templates/feature-review-template.md` -- 委托：`superpower-code-reviewer`（本插件 `agents/superpower-code-reviewer.md`） -- Fix commit 格式与 `feature-tdd/templates/commit-message-template.md` 一致 -- 上游：`feature-verify`；下游：`module-start`（approve）/ `feature-verify`（request-changes） +- `${CLAUDE_SKILL_DIR}/templates/feature-review-template.md`（verify 证据 + review 结论合并文档） +- `${CLAUDE_SKILL_DIR}/templates/commit-message-template.md`（fix commit 格式） +- 委托：`superpower-code-reviewer`（backend，本插件 `agents/superpower-code-reviewer.md`） +- 委托：`fe-code-reviewer`（frontend，本插件 `agents/fe-code-reviewer.md`，前端专用，硬编码 7 维 review checklist） +- 上游：`feature-tdd` +- 下游：`phase-driver`（approve）/ 本 skill 验证阶段（request-changes 重验） diff --git a/skills/coding/feature-review/templates/commit-message-template.md b/skills/coding/feature-review/templates/commit-message-template.md new file mode 100644 index 0000000..ecf5222 --- /dev/null +++ b/skills/coding/feature-review/templates/commit-message-template.md @@ -0,0 +1 @@ +{{type}}({{scope}}): {{subject}} {{req_id}} diff --git a/skills/coding/feature-review/templates/feature-review-template.md b/skills/coding/feature-review/templates/feature-review-template.md index 27fa018..a584fa4 100644 --- a/skills/coding/feature-review/templates/feature-review-template.md +++ b/skills/coding/feature-review/templates/feature-review-template.md @@ -1,24 +1,47 @@ --- req_id: {{req_id}} date: {{date}} +phase: {{phase}} round: {{round}} -reviewer: superpower-code-reviewer --- -# Review: {{req_id}} — round {{round}} +# 验证 + 审阅：{{req_id}} — round {{round}} -## 结论 +## 验证证据 + +- 命令: `{{command}}` +- 子会话: {{subagent_id}} +- 退出码: {{exit_code}} +- 通过用例数: {{passed}} +- 失败用例数: {{failed}} +- 失败列表: {{failed_list}} + +关键 stdout 片段 (≤30 行): + +``` +{{stdout_excerpt}} +``` + +结论: {{verify_conclusion}} （pass / fail） + +--- + +## 自审结论 + +审阅者: {{reviewer}} + +### 结论 {{verdict}} （approve / request-changes） -## Must-fix +### Must-fix {{#each must_fix}} - [{{severity}}] {{file}}:{{line}} — {{issue}}（建议：{{suggestion}}） {{/each}} -## Nice-to-have +### Nice-to-have {{#each nice_to_have}} - {{file}}:{{line}} — {{suggestion}} {{/each}} -## 反例 / 测试覆盖缺口 +### 反例 / 测试覆盖缺口 {{gaps}} diff --git a/skills/coding/feature-spec/SKILL.md b/skills/coding/feature-spec/SKILL.md new file mode 100644 index 0000000..36eb349 --- /dev/null +++ b/skills/coding/feature-spec/SKILL.md @@ -0,0 +1,215 @@ +--- +name: feature-spec +description: 统一功能循环第 1 步（后端 REQ / 前端 FE 共用，由 phase 参数区分）。交互式 Q&A → 产出"规格 + 任务级 TDD 计划"合并文档到 docs/superpowers/specs/，链入 feature-tdd。 +user-invocable: false +allowed-tools: Read Write Grep Glob Skill AskUserQuestion Bash(mysql *) +--- + +**所有输出必须使用中文。** + +# feature-spec + +统一功能循环第 1 步，后端（REQ-XXX-NNN）和前端（FE-NN）共用，由 `phase` 参数区分范围与上下文。交互式 Q&A → 产出"规格 + 任务级 TDD 计划"合并文档 → 链入 `feature-tdd`。 + +**入参（由上游 skill 传入）：** +- `phase`：`backend` | `frontend` +- `id`：`REQ-XXX-NNN`（backend）或 `FE-NN`（frontend） +- `name`：功能名称 +- `associated_reqs[]`：（仅 frontend）关联的 REQ 卡片 id 列表 +- `associated_prototypes[]`：（仅 frontend）关联的 prototype 文件路径列表 + +--- + +## 占位符规则 + +本 skill 写的 spec 是 CC 内部推理产物，不是用户审阅文档。**不允许** `【人工填写：...】` 占位符——A 阶段标记只在 `docs/01~10` / `CLAUDE.md` / `.env.local` 使用。需要具体值时： + +1. **先查** `.env.local` + `docs/04 §零环境` / `CLAUDE.md` / 现有代码 / 关联 prototype（frontend 时）。值已落地某处 → spec 中引用源（例 "JWT_SECRET 从 `.env.local` 读取，`application.yml` 用 `${JWT_SECRET}` 注入"） +2. **再问**：查不到 → `AskUserQuestion` 问用户，记录答案到 spec +3. **绝不**留 `【人工填写：】` 占位符；若 1 + 2 都解决不了，spec 必须写出具体阻塞点（不是泛化占位符），Q&A 继续直到解决 + +--- + +## 阶段范围 + +### phase=backend + +产出范围限定为：controller / service / repository / DTO / 校验 / SQL migration / REST 契约。 + +读 `docs/01-需求清单//.md` 时**忽略 UI 描述**（输入控件类型、按钮位置、列表布局等），但**校验规则、业务规则**仍要落到后端 DTO + service。UI 实现统一推迟到前端阶段（`phase=frontend`）。 + +上下文来源： +- REQ 卡片 `docs/01-需求清单//.md` +- 涉及的数据表定义（取自 `docs/03-数据库设计文档.md` 或实时 `mysql` 查询） + +### phase=frontend + +产出范围限定为：组件树 / 页面状态机 / 交互流程 / API 调用 / Design Tokens 引用 / 业务校验前端复刻。**不涉及** SQL / migration / controller / service / DTO（后端阶段已完成）。 + +一个 FE 是**业务功能**粒度，可能关联多个 prototype 文件区域和多个 REQ。 + +上下文来源： +- **页面骨架**：Read 所有 `associated_prototypes[]`（含 anchor 时聚焦相应区域），作为布局权威 +- **业务规则**：Read 所有 `associated_reqs[]` 对应的 `docs/01-需求清单//.md`，提取业务校验规则、acceptance、UI 描述 +- **API 契约**：Read `docs/05-API接口契约.md`，按 `associated_reqs[]` 过滤出本 FE 消费的端点 +- **Design Tokens**：Read `docs/06-UI交互规范.md § 二`，作为色值 / 状态色的引用源 +- **前端组件库**：Read `docs/04-技术规范.md § 零` 找 `frontend.ui_lib`（如 Ant Design / Element Plus），决定组件选型 + +--- + +## 执行步骤 + +### 步骤 1：收集上下文 + +按上方"阶段范围"对应的上下文来源读取所有相关文档。 + +### 步骤 2：评估 scope + +- 单 spec 容纳得下吗？ +- `phase=backend`：跨多个独立子系统（如"含登录 + 文件存储 + 计费 + 分析"）→ 先提示分解，每个子项目独立 brainstorm +- `phase=frontend`：跨多页 / 多业务 → 提示拆分，每个 FE 应独立可测试 + +### 步骤 3：交互式 Q&A + +参考下方"Q&A 原则"进行交互式问答： + +- `phase=backend`：聚焦 goal / 输入输出 / 业务规则 / 约束 / schema / API 引用 / acceptance criteria +- `phase=frontend`：聚焦组件树、页面状态机、交互流程、API 调用一致性、Design Tokens 引用、业务校验前端复刻。**不要**讨论 SQL / migration / controller / service / DTO + +**一次一问** `AskUserQuestion`，仅对真模糊点；多选题优先。决策完成后挑一种 approach；trade-off 直接内嵌 spec，**不设确认 gate**。 + +### 步骤 4：写合并文档 + +写到 `docs/superpowers/specs/-.md`（`id` = `REQ-XXX-NNN` 或 `FE-NN`）： + +- 按 `${CLAUDE_SKILL_DIR}/templates/feature-spec-plan-template.md` 渲染 +- **只填写当前 phase 对应的规格小节**（另一 phase 的小节留空或删除） +- 规格后紧接任务级计划（plan 部分） +- 计划粒度：每任务 2-5 分钟，= 一个 red-green-commit 单元 + +**计划写作原则（两 phase 通用）：** +- Plan 告诉 TDD 执行者**做什么**，不是**怎么写代码** +- Plan 锁定**文件边界 + 测试意图 + API / Props 形状 + 完成判据**；代码由 TDD 红绿循环产出 +- **禁止 dump 整个文件内容**到 plan（pom.xml / entity 类 / vue 组件源码 / config 文件） +- `phase=backend` 任务：`impl_file` 禁止以 `frontend/` 开头；`phase=frontend` 任务：`impl_file` 必须以 `frontend/` 开头 +- 每个任务含 4 步：写失败测试 → 实现最小代码 → 子会话验证 PASS → commit +- `phase=frontend` 每个任务必须标注"测试先行类型"：`jsdom 组件测试` 或 `Playwright E2E` + +文件已存在 → 征求用户确认后覆盖。 + +### 步骤 5：Spec + Plan 自审（inline 修，无须用户等待） + +**Spec 部分：** +- **占位符扫描**：`TBD` / `TODO` / `【人工填写：】` / 含糊段 → 修（按"占位符规则"流程解决） +- **内部一致性**：节与节是否矛盾？架构是否匹配功能描述？ +- **范围检查**：单 plan 能消化吗？还是需要分解 +- **歧义检查**：任何 requirement 两种解读？挑一个写明 +- `phase=frontend` 额外检查：全文不得出现 `TBD` / `@todo` / `controller` / `SQL` / `service` / `migration` → 命中则修正后重渲染 + +**Plan 部分：** +- **占位符扫描**：`TBD` / `TODO` / `implement later` / `fill in details` / `【人工填写：】` → 修 +- **Spec coverage**：skim spec 每节，能指向至少一个 task 吗？list gaps 并补 task +- **类型一致性**：tasks 之间签名 / 方法名 / 属性名 / 错误码一致（Task 3 的 `clearLayers()` 和 Task 7 的 `clearFullLayers()` 是 bug） +- `phase=frontend`：每个任务的 `impl_file` 路径必须以 `frontend/` 开头；命中 `backend/` / `sql/` / `scripts/` → 修正后重渲染 + +### 步骤 6：输出 + 链 feature-tdd + +（**直接做这两件事，不要输出"回交父 skill / 交给 caller / 等下一步 / 准备好了请检查"之类的桥接叙述**——那些会被解读为 turn 结束信号） + +- 输出一行 `feature-spec: → ` +- **同一 turn 内立即** `Skill(feature-tdd)` 传入 `{ phase, id }` + +--- + +## Q&A 原则 + +- **一次一问** — 不堆问题 +- **多选题优先** — 答更快 +- **仅对真模糊点问** — 不造确认问题 +- **YAGNI** — 删 spec 中不必要的功能 +- **渐进理解** — 不明白就问 +- **无审批 gate** — 写 spec 即 commit；分歧落地为具体 Q&A 项，不靠"等用户确认" + +--- + +## 任务原则 + +### Plan 文件头 + +每个合并文档的 plan 部分必须以以下头部开始： + +```markdown +# [Feature Name] Implementation Plan + +> **Execution:** Parent skill `feature-tdd` executes this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** [一句话描述] + +**Architecture:** [2-3 句方法论] + +**Tech Stack:** [关键技术 / 库] + +--- +``` + +### Task 结构 + +每个 task 是 red-green-commit 单元。捕获意图和边界，代码留给 TDD： + +````markdown +### Task N: [组件名 / 类名] + +**Files:** +- Create: `exact/path/to/File.java`（或 `frontend/src/...`） +- Modify: `exact/path/to/Existing.java:123-145` +- Test: `tests/exact/path/to/FileTest.java` +- 测试先行类型: jsdom 组件测试（仅 phase=frontend 需标注） + +**API shape / Props shape**（只写需要约束实现的签名；内部实现留给 TDD）: +- `LoginService#login(LoginRequest req) : LoginResponse` + +- [ ] **Step 1: 写失败测试** + - 测试名: `LoginServiceTest#loginWithBadPassword_incrementsFailCount_returns40101` + - 意图: 错误密码 → `iLoginFailCount += 1`；第 5 次 → 设置 `tLockUntil = now + 15min`；返回码 40101 + - 子会话确认 FAIL（函数/类不存在） + +- [ ] **Step 2: 实现最小代码** + - 目标: 让 Step 1 测试通过；不多做 + - 涉及文件: `LoginService.java`, `SftLoginInfoMapper.java` + +- [ ] **Step 3: 子会话验证 PASS** + +- [ ] **Step 4: Commit** + - `git add <文件>` + - `git commit -m "feat(sys): 登录失败计数 + 锁定 REQ-SYS-001"` +```` + +### 允许的代码块场景 + +少数例外，需要写死而非让 TDD 自由发挥： + +- **DDL / migration 文件**（phase=backend）：`V_n__*.sql` 的 ALTER/CREATE 语句——schema 是事实源 +- **合同级常量**：API 错误码表、JWT claim 名、Redis key 模式——跨模块消费，必须锁定 +- **路由配置**（phase=frontend）：`routes.ts` 中 path 注册（路径是契约级） +- **API client 契约**（phase=frontend）：fetch 包装函数签名 + headers + 错误码 mapping +- **Design Tokens 名称**（phase=frontend）：`var(--color-primary)` 列表 +- **测试断言形状**（可选）：一句话说不清"测什么"时，给个 3-5 行断言 sketch + +除此之外一律散文 + 签名描述，**不贴完整文件**。 + +### 记住 + +- Exact file paths always +- Exact commands with expected output（测试运行 + git 操作） +- API signatures / class names / error codes / contract values — **必须写死** +- Internal implementation code — **不写**；留给 TDD 阶段 +- DRY、YAGNI、TDD、frequent commits + +--- + +## 参考 + +- `${CLAUDE_SKILL_DIR}/templates/feature-spec-plan-template.md` +- 上游（backend）：`module-start` +- 上游（frontend）：`frontend-start` +- 下游：`feature-tdd` diff --git a/skills/coding/feature-spec/templates/feature-spec-plan-template.md b/skills/coding/feature-spec/templates/feature-spec-plan-template.md new file mode 100644 index 0000000..819e883 --- /dev/null +++ b/skills/coding/feature-spec/templates/feature-spec-plan-template.md @@ -0,0 +1,153 @@ + +阶段: {{phase}} + +--- + +# 规格 + 计划：{{id}} — {{title}} + +> 日期：{{date}} + +--- + +## 规格 + +### （phase=backend 填写）后端规格 + +--- +req_id: {{req_id}} +date: {{date}} +module: {{module}} +--- + +#### 目标 +{{goal}} + +#### 输入 / 触发 +{{input}} + +#### 输出 / 结果 +{{output}} + +#### 业务规则 +{{rules}} + +#### 边界与约束 +{{constraints}} + +#### 依赖的 schema 表 / 字段 +{{schema_refs}} + +#### 依赖的接口 +{{api_refs}} + +#### 验收标准 +{{acceptance}} + +--- + +### （phase=frontend 填写）前端规格 + + + +> 关联 REQ：{{associated_reqs}} +> 关联原型：{{associated_prototypes}} + +#### 功能概述 +{{feature_overview}} + +#### 组件树 + + + +``` +{{component_tree}} +``` + +#### 页面状态机 + +| # | 状态 | 触发条件 | 视觉表现 | 用户可执行操作 | +|---|------|---------|---------|--------------| +{{state_machine_rows}} + +至少包含：loading / empty / error / 正常 / 提交中 五态。 + +#### 消费的后端端点 + +| # | 方法 | 路径 | 触发时机 | 关联 REQ | +|---|------|------|---------|---------| +{{endpoint_rows}} + +#### 业务规则前端复刻清单 + +| # | 规则描述 | 触发时机 | 报错文案 | 来源 REQ | +|---|---------|---------|---------|---------| +{{validation_rows}} + +> **要求**：每条规则必须在前端 form-level 校验中复刻，不仅依赖后端报错。文案与后端语义一致。 + +#### Design Tokens 引用清单 + + + +``` +{{token_list}} +``` + +#### 交互流程关键路径 +{{interaction_flow}} + +#### 备注与开放问题 +{{open_questions}} + +--- + +## 任务级计划 + +> **Execution:** Parent skill `feature-tdd` executes this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** {{plan_goal}} + +**Architecture:** {{plan_architecture}} + +**Tech Stack:** {{plan_tech_stack}} + +--- + +### Schema 改动 +{{schema_change_decision}} + +### 文件变更清单 +{{#each files}} +- `{{path}}` — {{action}}（{{rationale}}） +{{/each}} + +### 任务步骤 +{{#each tasks}} +#### Task {{index}}: {{title}} + +**Files:** +{{task_files}} + +**API shape / Props shape**（只写需要约束实现的签名）: +{{api_shape}} + +- [ ] **Step 1: 写失败测试** + - 测试名: `{{test_file}}::{{test_name}}` + - 意图: {{test_intent}} + - 子会话确认 FAIL + +- [ ] **Step 2: 实现最小代码** + - 目标: 让 Step 1 测试通过；不多做 + - 涉及文件: `{{impl_file}}` + +- [ ] **Step 3: 子会话验证 PASS** + +- [ ] **Step 4: Commit** + - `git add <文件>` + - `git commit -m "{{commit_message}}"` +{{/each}} + +### 提交计划 +{{#each commits}} +- `{{message}}`（覆盖 Task {{task_index}}） +{{/each}} diff --git a/skills/coding/feature-tdd/SKILL.md b/skills/coding/feature-tdd/SKILL.md index 882f4ef..3810ea4 100644 --- a/skills/coding/feature-tdd/SKILL.md +++ b/skills/coding/feature-tdd/SKILL.md @@ -1,6 +1,6 @@ --- name: feature-tdd -description: 功能循环第 3 步。按 plan 逐任务做 TDD（失败测试 → 实现 → 通过 → commit），测试运行强制派发到子会话。 +description: 统一功能循环第 2 步（后端 REQ / 前端 FE 共用，由 phase 参数区分）。按 plan 逐任务做 TDD（失败测试 → 实现 → 通过 → commit），所有测试运行强制派发到 Agent 子会话，主会话只接收 JSON 结果。 user-invocable: false allowed-tools: Read Write Edit Agent Skill Bash(git add *) Bash(git commit *) --- @@ -9,34 +9,92 @@ allowed-tools: Read Write Edit Agent Skill Bash(git add *) Bash(git commit *) # feature-tdd -按 plan 文件逐任务做 TDD：写失败测试 → 写最小实现 → 确认通过 → commit。**所有测试运行强制派发到 Agent 子会话**，主会话只接收 JSON 结果。 +按合并文档（spec + plan）的任务级计划逐任务做 TDD：写失败测试 → 写最小实现 → 确认通过 → commit。**所有测试运行强制派发到 Agent 子会话**，主会话只接收 JSON 结果。 + +**入参（由 feature-spec 传入）：** +- `phase`：`backend` | `frontend` +- `id`：`REQ-XXX-NNN`（backend）或 `FE-NN`（frontend） + +--- + +## 阶段差异 + +### phase=backend + +- 工作分支：`module-` +- `impl_file` 不得以 `frontend/` 开头（见护栏） +- 测试命令：`./scripts/test.sh`（由子会话执行） +- Schema 改动前置：有 migration 需求时，第一个任务必须是写 migration + 同步 docs/03 +- 提交 trailer：`REQ-XXX-NNN` 标签（内嵌在 commit subject 中） + +### phase=frontend + +- 工作分支：`frontend-phase` +- `impl_file` 必须以 `frontend/` 开头（见护栏） +- 测试命令：从 `docs/04-技术规范.md § 零 frontend` 取： + - `frontend.unit_test_runner`：vitest / jest（默认 vitest） + - `frontend.e2e_runner`：playwright（默认 playwright） + - `frontend.test_command` / `frontend.e2e_command`（缺失则用 `pnpm test:ci` / `pnpm e2e:ci`） +- **无** SQL migration 步骤 +- 提交 trailer：`REQ_ID: FE-NN`（作为 commit trailer 行） + +--- ## 执行步骤 -1. 加载计划文件 `docs/superpowers/plans/-.md`。 -2. **Schema 改动前置**（仅当 plan 声明需要）：第一个任务必须是写 migration 文件 + 同步更新 docs/03，并一起 commit。 +1. **加载 spec + plan**：读取 `docs/superpowers/specs/-.md`，定位 `## 任务级计划` 节。 + +2. **Schema 改动前置**（仅 `phase=backend`，且 plan 声明需要时）：第一个任务必须是写 migration 文件 + 同步更新 docs/03，并一起 commit。 - 文件命名 `V__.sql`，`` = 现有 `sql/migrations/V*.sql` 最大版本号 + 1；文件只含 DDL - **同步**把新 CREATE / ALTER 反向更新到 `docs/03-数据库设计文档.md` 对应表小节，保持 docs/03 是 schema 的 SSoT；新增表按表小节模板追加 - migration + docs/03 改动**同一 commit**，避免 SSoT 与 migration 分裂 - - 测试运行时 Spring Boot 启动 Flyway 会自动 apply 这个新 migration；`scripts/setup-test-db.sh` 只负责清库 -3. 按顺序处理每个代码类任务： - a. 在 `test_file::test_name` 处写**失败**测试 - b. 派发 Agent 子会话（general-purpose）运行测试确认失败，子会话只返回 `{command, exit_code, failing_assertion}` JSON - c. 在 `impl_file` 处写**最小**实现使测试通过 + - 测试运行时 Spring Boot 启动 Flyway 会自动 apply 新 migration + +3. **按顺序处理每个代码类任务**： + + a. 在 `test_file::test_name` 处写**失败**测试： + - `phase=backend`：JUnit / 框架测试 + - `phase=frontend`，`测试先行类型=jsdom`：在 jsdom 环境下用 vitest/jest 写组件单测（render + 断言 DOM / 交互后状态变化） + - `phase=frontend`，`测试先行类型=e2e`：在 `frontend/e2e/` 写 Playwright 测试（headless） + + b. 派发 Agent 子会话（general-purpose）运行该测试，子会话只返回 `{command, exit_code, failing_assertion}` JSON，确认失败 + + c. 在 `impl_file` 处写**最小**实现使测试通过。**严格遵守**： + - `phase=backend`：`impl_file` 不得以 `frontend/` 开头（违反 → 护栏硬停） + - `phase=frontend`：`impl_file` 必须以 `frontend/` 开头（违反 → 护栏硬停）；色值用 `var(--color-*)`（来自 spec §六），不硬编码 hex；业务校验按 spec §五 在 form-level 复刻 + d. 再次派发子会话确认通过 - e. 同一测试 >10 次修复仍失败 → 调用 `interrupt-check`（中断 #1：测试反复失败） - f. 按 `${CLAUDE_SKILL_DIR}/templates/commit-message-template.md` 格式 commit（`scope` = 任务模块；`subject` ≤ 50 字符；`req_id` 必填） -4. 全部任务完成 → 调用 `Skill(feature-verify)`。 + + e. 同一测试 >10 次修复仍失败 → 调用 `Skill(interrupt-check)`（中断 #1：测试反复失败） + + f. 按 `${CLAUDE_SKILL_DIR}/templates/commit-message-template.md` 格式 commit： + - `phase=backend`：`scope` = 任务模块；`subject` ≤ 50 字符；内含 `REQ-XXX-NNN` 标签 + - `phase=frontend`：`scope` = 组件名（如 `dashboard` / `user-form`）；`subject` ≤ 50 字符；必含 trailer `REQ_ID: FE-NN` + +4. **全部任务完成** → 调用 `Skill(feature-review)` 传入 `{ phase, id }` + +--- ## 护栏 -- **绝不**在主会话直接跑 `mvn test` / `pnpm test` / `scripts/test.sh`，必须通过子会话 +- **绝不**在主会话直接跑任何测试命令（`mvn test` / `pnpm test` / `scripts/test.sh` / `pnpm playwright` / `vitest`），必须通过子会话 - **绝不**在主会话直接 `mysql -e "ALTER ..."`；业务 schema 改动一律走 `sql/migrations/V*.sql` 文件（只读查询 / 临时调试除外） -- 每次 commit 必须含 `REQ-XXX-NNN` 标签；不混合无关改动到同一 commit -- **后端阶段路径硬护栏**：任务表里的 `impl_file` 路径以 `frontend/` 开头 → 硬停并打印 `feature-tdd 后端阶段不允许写前端代码：。请检查 plan 任务定义；UI 推迟到前端阶段（fe-feature-*）`，不再继续 TDD 循环 +- **后端阶段路径硬护栏（phase=backend）**：任务表里的 `impl_file` 路径以 `frontend/` 开头 → 硬停并打印： + ``` + feature-tdd 后端阶段不允许写前端代码：。请检查 plan 任务定义；UI 推迟到前端阶段（phase=frontend）。 + ``` +- **前端阶段路径硬护栏（phase=frontend）**：`impl_file` 路径**不以** `frontend/` 开头，或命中 `backend/` / `sql/` / `scripts/` → 硬停并打印： + ``` + feature-tdd 前端阶段不允许写非前端文件：。前端阶段任务的 impl_file 必须落在 frontend/ 目录下。 + ``` +- 不硬编码颜色 hex（`phase=frontend`）；token 引用必须对齐 spec §六 + +--- ## 参考 - `${CLAUDE_SKILL_DIR}/templates/commit-message-template.md` - 守门：`interrupt-check`（仅在步骤 3.e 触发，条件 1） - 原则参考：`superpowers:test-driven-development`（外部 TDD 原则手册，本 skill 已固化"子会话跑测试 + REQ-tagged commit"流程，不做运行时 invoke） +- 上游：`feature-spec` +- 下游：`feature-review` diff --git a/skills/coding/feature-verify/SKILL.md b/skills/coding/feature-verify/SKILL.md deleted file mode 100644 index f583d75..0000000 --- a/skills/coding/feature-verify/SKILL.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -name: feature-verify -description: 功能循环第 4 步。把功能测试派发到子会话跑，按模板渲染证据。无证据不声称完成。 -user-invocable: false -allowed-tools: Skill Read Agent ---- - -**所有输出必须使用中文。** - -# feature-verify - -把当前 REQ 的功能测试派发到 Agent 子会话执行，按模板把结构化结果渲染成证据。**主会话从不直接跑测试**，也不自由编写证据。 - -## 执行步骤 - -1. 从 plan 文件或项目标准命令中确定功能的测试目标（如 Maven profile / pnpm script / pytest path）。 -2. 派发 Agent 子会话（general-purpose）运行该目标，子会话只返回结构化 JSON（不输出描述文字）： - ```json - { - "command": "", - "exit_code": , - "passed": , - "failed": , - "failed_list": ["", ...], - "stdout_excerpt": "<最后 30 行或最相关的失败片段>" - } - ``` -3. 按 `${CLAUDE_SKILL_DIR}/templates/feature-verify-evidence-template.md` 渲染证据并打印到会话。 -4. **`exit_code != 0` 或 `failed > 0`** → 停止，不进入 review。 -5. 通过 → 调用 `Skill(feature-review)`。 - -## 护栏 - -- **绝不**在主会话直接跑测试，必须通过子会话 -- **绝不**自由编写证据正文，必须从模板渲染 -- 不要把原始 stdout 全文塞进主会话（`stdout_excerpt` ≤ 30 行） - -## 参考 - -- `${CLAUDE_SKILL_DIR}/templates/feature-verify-evidence-template.md` -- 原则参考：`superpowers:verification-before-completion`（外部"证据先于断言"原则手册，本 skill 已固化子会话派发 + 模板渲染流程，不做运行时 invoke） diff --git a/skills/coding/feature-verify/templates/feature-verify-evidence-template.md b/skills/coding/feature-verify/templates/feature-verify-evidence-template.md deleted file mode 100644 index efaa70b..0000000 --- a/skills/coding/feature-verify/templates/feature-verify-evidence-template.md +++ /dev/null @@ -1,16 +0,0 @@ -## Verify evidence — {{req_id}} - -- 命令: `{{command}}` -- 子会话: {{subagent_id}} -- 退出码: {{exit_code}} -- 通过用例数: {{passed}} -- 失败用例数: {{failed}} -- 失败列表: {{failed_list}} - -关键 stdout 片段 (≤30 行): - -``` -{{stdout_excerpt}} -``` - -结论: {{conclusion}} （pass / fail） -- libgit2 0.22.2