From 326c976992ed6417df0f65c7abacd99253f65901 Mon Sep 17 00:00:00 2001 From: zichun Date: Thu, 28 May 2026 15:50:07 +0800 Subject: [PATCH] skill(scope-lock): collapse A/B/C ritual into shared procedure + trim duplicated guidance --- skills/plan/plan-start/SKILL.md | 3 +-- skills/plan/scope-lock/SKILL.md | 185 +++++++++++++++++++++++++++++++++++++++++++---------------------------------------------------------------------------------------------------------------------------------------------- 2 files changed, 44 insertions(+), 144 deletions(-) diff --git a/skills/plan/plan-start/SKILL.md b/skills/plan/plan-start/SKILL.md index 67bac3b..719bbff 100644 --- a/skills/plan/plan-start/SKILL.md +++ b/skills/plan/plan-start/SKILL.md @@ -50,8 +50,7 @@ A 阶段所有 checkbox 均 `[x]` 时**不代表可以进 B 阶段**。Coding 1. **REQ 卡片真实数据**（来自 A1 scope-lock） - `Glob` 找出全部 REQ 卡片（如 `docs/01-需求清单/**/*.md`）。 - - 对每张卡片 `Grep` 残留占位：命中任一即缺口 — - `【人工填写`、`TBD`、`待补`、`<示例`、`【示例行`（与 scope-lock E.1 同强度——`<示例` 兜底 `<示例值>`，`【示例行` 兜底未删的模板示例行 `【示例行，替换为真实字段】`；避免半填卡片绕过本闸）。 + - 对每张卡片 `Grep` 命中以下任一即缺口: `【人工填写` / `TBD` / `待补` / `<示例` / `【示例行` (与 scope-lock E.1 同集合). - 缺口表述示例：`REQ-USER-001 仍含 TBD / 示例值未替换为真实约束 / 示例行未删除`。 2. **secrets / 项目配置全锁**（来自 A1 收集的 secret/account/package-name/namespace 清单） diff --git a/skills/plan/scope-lock/SKILL.md b/skills/plan/scope-lock/SKILL.md index bbe71c2..8f64147 100644 --- a/skills/plan/scope-lock/SKILL.md +++ b/skills/plan/scope-lock/SKILL.md @@ -7,148 +7,54 @@ allowed-tools: Read Write Edit Grep Glob Skill AskUserQuestion Bash(mkdir *) Bas **所有输出必须使用中文。** -# scope-lock - -> **关于 AskUserQuestion**：下文只描述「问什么、给哪些选项、各选项导向什么后续」。`header` / 各选项的 `description` / `multiSelect` 等具体参数由你按工具 schema 自行填全合法值——不要把下文的选项文字当成完整调用照抄。 - ## 执行步骤 -### A. 提示用户填写项目概述并等待 - -向用户输出： - -``` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ - [scope-lock] 请填写项目概述 - - 📄 文件位置: ./CLAUDE.md - 📌 编辑位置: § 🎯 项目概述 - - 请将以下占位符替换为实际值： - - 项目名称 - - 项目简述 - - 目标用户 - - 部署方式 - 改完后回来选择「继续」。 -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -``` - -用 `AskUserQuestion` 确认「项目概述填写完毕了吗？」，给「继续」和「有疑问想先沟通」两个选项。 +### A / B / C. 填写项目概述 / 技术栈 / 需求清单 -- 选「继续」→ 用 `Grep` 在 `CLAUDE.md` 搜索 `【人工填写：`（限定 § 🎯 项目概述 节）。命中 → 打印残留行 + 路径，重新确认一次；0 命中 → 勾选并进入步骤 B。 -- 选「有疑问想先沟通」→ 回答用户问题后，再确认一次。 - -0 命中后，用 `Edit` 在 `docs/08-模块任务管理.md` 中勾选： -- ` - [ ] 项目概述已填写（CLAUDE.md § 🎯 项目概述）` - -### B. 提示用户检查默认技术栈并等待 +| 步骤 | 文件 | 编辑位置 | docs/08 子项 | +|---|---|---|---| +| A | `CLAUDE.md` | § 🎯 项目概述 | `项目概述已填写（CLAUDE.md § 🎯 项目概述）` | +| B | `docs/04-技术规范.md`（A0 模板生成） | § 零、技术栈总览 | `技术栈已确认（docs/04 § 零）` | +| C | `docs/01-需求清单/index.md` | § 模块索引（表格） | `需求清单索引已填写（docs/01-需求清单/index.md）` | -`docs/04-技术规范.md` 已由 A0 `project-init` 用模板复制（默认技术栈，见 `project-init/templates/docs-04-stack-template.md`）。本步骤让用户检查 / 调整 § 零。 - -向用户输出： - -``` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ - [scope-lock] 技术栈已保存 - - 📄 文件位置: ./docs/04-技术规范.md（由 A0 模板生成） - 📌 编辑位置: § 零、技术栈总览 - - 请检查技术栈表： - - 不需要的行直接删除（如纯后端项目删前端行） - - 需要替换的技术直接改 - - 需要新增的条目直接加行 - 改完后回来选择「继续」。 -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -``` +**每个填写步骤的通用流程**：输出 `[scope-lock]` 横幅指明文件 + 编辑位置 → `AskUserQuestion` 二选一（「继续」/「有疑问想先沟通」）→ 用 `Grep` 在对应位置搜 `【人工填写：` 占位（命中则打印残留行重新确认；0 命中则继续）→ 用 `Edit` 在 `docs/08-模块任务管理.md` 勾选对应子项。 -用 `AskUserQuestion` 确认「技术栈检查完毕了吗？」，给「继续」和「有疑问想先沟通」两个选项。 - -- 选「继续」→ 进入步骤 C。 -- 选「有疑问想先沟通」→ 回答用户问题后，再确认一次。 - -完成后，用 `Edit` 在 `docs/08-模块任务管理.md` 中勾选： -- ` - [ ] 技术栈已确认（docs/04 § 零）` - -### C. 提示用户填写需求清单并等待 - -`docs/01-需求清单/index.md` 已由 `project-init` 写入占位符模板，这里让用户补齐模块清单。 - -向用户输出： - -``` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ - [scope-lock] 请填写需求清单模块索引 - - 📄 文件位置: ./docs/01-需求清单/index.md - 📌 编辑位置: § 模块索引（表格） - - 请按业务列出所有模块： - - 每行一个模块（如 SYS 系统管理 / PUR 采购 / SAL 销售） - - 「核心功能点」只需关键词，CC 会拆分为 REQ 卡片 - 改完后回来选择「继续」。 -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -``` - -用 `AskUserQuestion` 确认「需求清单模块索引填写完毕了吗？」，给「继续」和「有疑问想先沟通」两个选项。 - -- 选「继续」→ 进入步骤 D。 -- 选「有疑问想先沟通」→ 回答用户问题后，再确认一次。 - -完成后，用 `Edit` 在 `docs/08-模块任务管理.md` 中勾选： -- ` - [ ] 需求清单索引已填写（docs/01-需求清单/index.md）` +- **A**：`CLAUDE.md` § 🎯 项目概述。占位符含项目名称 / 简述 / 目标用户 / 部署方式。 +- **B**：`docs/04-技术规范.md` § 零。让用户检查 / 调整默认技术栈表（删不需要的行 / 改技术 / 加条目）。 +- **C**：`docs/01-需求清单/index.md`。让用户按业务列出所有模块（每行一个，如 SYS / PUR / SAL），「核心功能点」给关键词即可，CC 会拆 REQ 卡片。 ### D. 生成 REQ 卡片骨架并停下等人工审阅 1. 用 `Grep` 校验 `docs/01-需求清单/index.md` 无 `【人工填写：` 残留；有则回步骤 C。 2. 用 `Read` 读 `index.md` 解析模块索引。 -3. **逐文件渲染落盘**（用 Node 渲染助手，跨平台、字面量安全）： - - - **每模块推断**：三元组 `{module_code, module_name, module_brief}` + N 个 REQ 的六元组 `{req_id, title, goal, rules, constraints, acceptance}`。`req_id`/`title` 从核心功能点拆分；`goal` 展开 `title`；`rules`/`constraints`/`acceptance` 起草业务语义。**不推断**输入 / 输出字段（模板的结构化字段表保留示例行，留待人工逐行填真实数据）。 - - **渲染助手** `lib/render.mjs` 的 CLI 形态为 `node <模板路径> <输出路径>`：读模板 + 读 JSON 变量 + 占位符字面替换 + 自动剥离 HTML 注释，写到输出路径。值含 `$`、`{`、`}`、`}}` 均按字面插入，无需兜底。 - - **每个文件三步**：(a) 用 `Write` 写一个临时 vars JSON（仅含该文件用到的占位符键值）；(b) `mkdir -p` 模块目录；(c) `node` 调 render.mjs 渲染。`` / `<模块名>` / `` 等尖括号位置 CC 按 `index.md` 实际值替换。调用形态： - - ```bash - # 模块头：先 Write docs/01-需求清单/-<模块名>/_module.vars.json，内容形如 - # {"module_code":"","module_name":"<模块名>","module_brief":""} - mkdir -p "docs/01-需求清单/-<模块名>" - node "${CLAUDE_PLUGIN_ROOT}/lib/render.mjs" \ - "${CLAUDE_SKILL_DIR}/templates/_module-template.md" \ - "docs/01-需求清单/-<模块名>/_module.vars.json" \ - "docs/01-需求清单/-<模块名>/_module.md" - - # 每个 REQ：先 Write 该 REQ 的 vars JSON，内容形如 - # {"req_id":"","title":"","goal":"<goal>","rules":"<rules>","constraints":"<constraints>","acceptance":"<acceptance>"} - node "${CLAUDE_PLUGIN_ROOT}/lib/render.mjs" \ - "${CLAUDE_SKILL_DIR}/templates/req-card-template.md" \ - "docs/01-需求清单/<MOD>-<模块名>/<REQ-MOD-NNN>.vars.json" \ - "docs/01-需求清单/<MOD>-<模块名>/<REQ-MOD-NNN>.md" - ``` - - - 渲染完成后删除临时 `*.vars.json`（`rm` 或不留亦可，不进入交付物）。 +3. **每模块/每 REQ 渲染**：`Write` vars.json → `mkdir -p` → `node render.mjs`。`<MOD>` / `<模块名>` / `<REQ-MOD-NNN>` 按 `index.md` 实际值替换。 + + ```bash + # 模块头：先 Write docs/01-需求清单/<MOD>-<模块名>/_module.vars.json，内容形如 + # {"module_code":"<MOD>","module_name":"<模块名>","module_brief":"<module_brief>"} + mkdir -p "docs/01-需求清单/<MOD>-<模块名>" + node "${CLAUDE_PLUGIN_ROOT}/lib/render.mjs" \ + "${CLAUDE_SKILL_DIR}/templates/_module-template.md" \ + "docs/01-需求清单/<MOD>-<模块名>/_module.vars.json" \ + "docs/01-需求清单/<MOD>-<模块名>/_module.md" + + # 每个 REQ：先 Write 该 REQ 的 vars JSON，内容形如 + # {"req_id":"<REQ-MOD-NNN>","title":"<title>","goal":"<goal>","rules":"<rules>","constraints":"<constraints>","acceptance":"<acceptance>"} + node "${CLAUDE_PLUGIN_ROOT}/lib/render.mjs" \ + "${CLAUDE_SKILL_DIR}/templates/req-card-template.md" \ + "docs/01-需求清单/<MOD>-<模块名>/<REQ-MOD-NNN>.vars.json" \ + "docs/01-需求清单/<MOD>-<模块名>/<REQ-MOD-NNN>.md" + ``` 4. 用 `Edit` 在 `docs/08-模块任务管理.md` 勾选（A1 子项）： - ` - [ ] REQ 卡片骨架已生成（docs/01-需求清单/<module>/REQ-*.md，业务内容留待人工填写）` - - **注意**：此处先**不**勾选 `- [ ] A1 范围锁定 — scope-lock` 顶层项；A1 顶层项必须在步骤 E（A1 终结校验）全部通过后才勾选。 5. 打印「请人工填写 REQ 卡片」横幅并提示用户填完后回来继续（不停止，下一步是 A1 终结校验）： ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ [scope-lock] REQ 卡片骨架已生成 - 产出： - ✓ docs/01-需求清单/<module>/_module.md 模块头 - ✓ docs/01-需求清单/<module>/REQ-*.md REQ 卡片骨架 - - ⏸ 现在请你逐张打开 REQ 卡片，把结构化字段表填成真实数据： - - **必改**：`输入字段` / `输出字段` 两张表 - · 删掉「【示例行，替换为真实字段】」示例行，按本 REQ 业务逐行填真实字段 - · 6 列全部填：字段名 / 类型 / 必填 / 校验规则 / 业务规则 / 示例值 - · **「示例值」列必须是真实约束下的合法取值**——留 `<示例值>` 或示例行会被 A1 终结校验阻断 - - **审阅**：目标 / 跨字段规则 / 边界 / 验收（已起草，对照业务校正） - - **保留**：`TBD` 不要改，由之后流程自动回填 - - 填完后回来选择「继续」，进入 A1 终结校验。 + - 产出: docs/01-需求清单/<module>/{_module.md, REQ-*.md} + - 请逐张填真实字段表, 完成后选「继续」进 A1 终结校验. ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ``` @@ -159,7 +65,7 @@ allowed-tools: Read Write Edit Grep Glob Skill AskUserQuestion Bash(mkdir *) Bas ### E. A1 终结校验（硬闸：全部通过才勾选 A1 顶层） -> 本步骤把原本会在编码期（coding.mjs 的 spec / plan stage）弹出的需求澄清 / config Q&A **全部前移到此处**。任一检查不满足，用 `AskUserQuestion` 在**此处（Plan 期）**问清并修订，**禁止**留待编码期。三项检查全过后才在 `docs/08` 勾选 `- [ ] A1 范围锁定 — scope-lock`。 +E.1/E.2/E.3 全过后才勾 A1 顶层。 #### E.1 真实数据校验（每张 REQ 卡片） @@ -173,14 +79,9 @@ allowed-tools: Read Write Edit Grep Glob Skill AskUserQuestion Bash(mkdir *) Bas #### E.2 配置字段名锁进 config-vars.yaml（敏感键名引用 .env.local） -1. 用 `Read` 读 `docs/04-技术规范.md` § 零技术栈，结合 REQ 卡片，盘点本项目需人工提供 / 确认的配置字段，分两类： - - **非敏感、项目级**：后端根包名 / 命名空间（Java package / C# namespace / Python 顶层包 / Go module path 等）、应用端口、前端包名 / scope、前端 dev 端口、管理员初始账号等。 - - **敏感凭据**：数据库密码、JWT / 签名密钥、Redis 密码、第三方 API key/secret、OSS / 对象存储凭证、短信 / 邮件服务凭证、管理员初始密码等。 -2. 用 `Read` 读模板 `${CLAUDE_SKILL_DIR}/templates/config-vars-template.yaml`，用 `Write` 落盘到仓库根 `config-vars.yaml`： - - **非敏感字段**：按技术栈推断默认值直接填入（如 `http_port: 8080`、`base_package: com.<org>.<app>`）；无对应技术栈的整节删除（如纯后端项目删 `frontend:`）；无法可靠推断的留 `【人工填写：…】`（A2 skeleton-gen 补填）。 - - **敏感字段**：只把「键名 + 含义」登记进 `secrets_ref` 列表，**绝不写真实值**（真实值由 A2 写进 `.env.local`，A2 据 `secrets_ref` 核对齐全）。 -3. **不**在此创建 / 填写 `docs/07-环境配置.md`——它由 A2 skeleton-gen 生成，只记规则不记具体值。 -4. 用 `AskUserQuestion` 向用户确认：「以下配置 / 凭据字段已登记进 config-vars.yaml，是否齐全？还有遗漏的吗？」展示非敏感字段 + `secrets_ref` 键名清单。用户补充则继续登记，直到确认齐全。 +1. 据 `docs/04` § 零 + REQ 卡片盘点配置. +2. `Read` 模板 `${CLAUDE_SKILL_DIR}/templates/config-vars-template.yaml` → `Write` `config-vars.yaml`: 非敏感字段填默认值, 无技术栈整节删, 不可推断留 `【人工填写】`; 敏感字段只把键名+含义登 `secrets_ref`, 不写真实值. +3. `AskUserQuestion` 让用户确认齐全. #### E.3 build / lint / unit / e2e 命令锁进 docs/04 § 零 @@ -219,13 +120,13 @@ allowed-tools: Read Write Edit Grep Glob Skill AskUserQuestion Bash(mkdir *) Bas ## 参考 -- `CLAUDE.md` § 🎯 项目概述（写入目标） -- `docs/04-技术规范.md`（技术栈输出，供 skeleton-gen 读取使用） -- `docs/01-需求清单/index.md`（模块索引输入） -- `docs/01-需求清单/<module>/_module.md`（模块头输出） -- `docs/01-需求清单/<module>/REQ-*.md`（REQ 卡片骨架输出，A3 db-design-gen / A5 downstream-gen 会回填 TBD 字段） -- `config-vars.yaml`（A1 终结校验 E.2 输出：非敏感配置字段填值 + secrets_ref 键名锁定；仓库根） -- `${CLAUDE_SKILL_DIR}/templates/config-vars-template.yaml`（E.2 渲染来源；跨栈中立，YAML 注释引导） -- `${CLAUDE_SKILL_DIR}/templates/req-card-template.md`（结构化 6 列字段表） +- `CLAUDE.md` +- `docs/04-技术规范.md` +- `docs/01-需求清单/index.md` +- `docs/01-需求清单/<module>/_module.md` +- `docs/01-需求清单/<module>/REQ-*.md` +- `config-vars.yaml` +- `${CLAUDE_SKILL_DIR}/templates/config-vars-template.yaml` +- `${CLAUDE_SKILL_DIR}/templates/req-card-template.md` - `${CLAUDE_SKILL_DIR}/templates/_module-template.md` -- `${CLAUDE_PLUGIN_ROOT}/lib/render.mjs`（步骤 D 渲染助手；CLI 形态 `node render.mjs <模板> <vars.json> <输出>`，字面量安全 + 自动剥 HTML 注释） +- `${CLAUDE_PLUGIN_ROOT}/lib/render.mjs` -- libgit2 0.22.2