skill(scope-lock): collapse A/B/C ritual into shared procedure + trim duplicated guidance

zichun
1 parent 105a2e5c
Showing 2 changed files with 44 additions and 144 deletions
skills/plan/plan-start/SKILL.md
skills/plan/scope-lock/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 æ¸…å•ï¼‰
@@ -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 <render.mjs> <模板路径> <vars.json 路径> <输出路径>`：读模板 + 读 JSON 变量 + 占位符字面替换 + 自动剥离 HTML 注释，写到输出路径。值含 `$`、`{`、`}`、`}}` 均按字面插入，无需兜底。
-   - **每个文件三步**：(a) 用 `Write` 写一个临时 vars JSON（仅含该文件用到的占位符键值）；(b) `mkdir -p` 模块目录；(c) `node` 调 render.mjs 渲染。`<MOD>` / `<模块名>` / `<REQ-MOD-NNN>` 等尖括号位置 CC 按 `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"
-     ```
-
-   - 渲染完成后删除临时 `*.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`