朱子纯 / erp-workflow-plugin

Commit 326c976992ed6417df0f65c7abacd99253f65901

Authored by zichun
1 parent 105a2e5c

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

Inline Side-by-side
Showing 2 changed files with 44 additions and 144 deletions
skills/plan/plan-start/SKILL.md
  View file @326c976
... ... @@ -50,8 +50,7 @@ A 阶段所有 checkbox å‡ `[x]` æ—¶**ä¸ä»£è¡¨å¯ä»¥è¿› B 阶段**。Coding é˜
50 50  
51 51 1. **REQ å¡ç‰‡çœŸå®žæ•°æ®**（æ¥è‡ª A1 scope-lock）
52 52 - `Glob` 找出全部 REQ å¡ç‰‡ï¼ˆå¦‚ `docs/01-需求清å•/**/*.md`）。
53   - - 对æ¯å¼ å¡ç‰‡ `Grep` 残留å ä½ï¼šå‘½ä¸­ä»»ä¸€å³ç¼ºå£ —
54   - `ã€äººå·¥å¡«å†™`ã€`TBD`ã€`å¾…è¡¥`ã€`<示例`ã€`ã€ç¤ºä¾‹è¡Œ`（与 scope-lock E.1 åŒå¼ºåº¦â€”—`<示例` 兜底 `<示例值>`，`ã€ç¤ºä¾‹è¡Œ` 兜底未删的模æ¿ç¤ºä¾‹è¡Œ `ã€ç¤ºä¾‹è¡Œï¼Œæ›¿æ¢ä¸ºçœŸå®žå­—段】`ï¼›é¿å…åŠå¡«å¡ç‰‡ç»•è¿‡æœ¬é—¸ï¼‰ã€‚
  53 + - 对æ¯å¼ å¡ç‰‡ `Grep` 命中以下任一å³ç¼ºå£: `ã€äººå·¥å¡«å†™` / `TBD` / `å¾…è¡¥` / `<示例` / `ã€ç¤ºä¾‹è¡Œ` (与 scope-lock E.1 åŒé›†åˆ).
55 54 - 缺å£è¡¨è¿°ç¤ºä¾‹ï¼š`REQ-USER-001 ä»å« TBD / 示例值未替æ¢ä¸ºçœŸå®žçº¦æŸ / 示例行未删除`。
56 55  
57 56 2. **secrets / 项目é…置全é”**（æ¥è‡ª A1 收集的 secret/account/package-name/namespace 清å•ï¼‰
... ...
skills/plan/scope-lock/SKILL.md
  View file @326c976
... ... @@ -7,148 +7,54 @@ allowed-tools: Read Write Edit Grep Glob Skill AskUserQuestion Bash(mkdir *) Bas
7 7  
8 8 **所有输出必须使用中文。**
9 9  
10   -# scope-lock
11   -
12   -> **关于 AskUserQuestion**：下文只描述「问什么、给哪些选项、各选项导向什么后续」。`header` / 各选项的 `description` / `multiSelect` 等具体参数由你按工具 schema 自行填全合法值——不要把下文的选项文字当成完整调用照抄。
13   -
14 10 ## 执行步骤
15 11  
16   -### A. 提示用户填写项目概述并等待
17   -
18   -向用户输出：
19   -
20   -```
21   -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
22   - [scope-lock] 请填写项目概述
23   -
24   - 📄 文件位置: ./CLAUDE.md
25   - 📌 编辑位置: § 🎯 项目概述
26   -
27   - 请将以下占位符替换为实际值：
28   - - 项目名称
29   - - 项目简述
30   - - 目标用户
31   - - 部署方式
32   - 改完后回来选择「继续」。
33   -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
34   -```
35   -
36   -用 `AskUserQuestion` 确认「项目概述填写完毕了吗？」，给「继续」和「有疑问想先沟通」两个选项。
  12 +### A / B / C. 填写项目概述 / 技术栈 / 需求清单
37 13  
38   -- 选「继续」→ 用 `Grep` 在 `CLAUDE.md` 搜索 `【人工填写：`（限定 § 🎯 项目概述 节）。命中 → 打印残留行 + 路径，重新确认一次；0 命中 → 勾选并进入步骤 B。
39   -- 选「有疑问想先沟通」→ 回答用户问题后，再确认一次。
40   -
41   -0 命中后，用 `Edit` 在 `docs/08-模块任务管理.md` 中勾选：
42   -- ` - [ ] 项目概述已填写（CLAUDE.md § 🎯 项目概述）`
43   -
44   -### B. 提示用户检查默认技术栈并等待
  14 +| 步骤 | 文件 | 编辑位置 | docs/08 子项 |
  15 +|---|---|---|---|
  16 +| A | `CLAUDE.md` | § 🎯 项目概述 | `项目概述已填写（CLAUDE.md § 🎯 项目概述）` |
  17 +| B | `docs/04-技术规范.md`（A0 模板生成） | § 零、技术栈总览 | `技术栈已确认（docs/04 § 零）` |
  18 +| C | `docs/01-需求清单/index.md` | § 模块索引（表格） | `需求清单索引已填写（docs/01-需求清单/index.md）` |
45 19  
46   -`docs/04-技术规范.md` 已由 A0 `project-init` 用模板复制（默认技术栈，见 `project-init/templates/docs-04-stack-template.md`）。本步骤让用户检查 / 调整 § 零。
47   -
48   -向用户输出：
49   -
50   -```
51   -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
52   - [scope-lock] 技术栈已保存
53   -
54   - 📄 文件位置: ./docs/04-技术规范.md（由 A0 模板生成）
55   - 📌 编辑位置: § 零、技术栈总览
56   -
57   - 请检查技术栈表：
58   - - 不需要的行直接删除（如纯后端项目删前端行）
59   - - 需要替换的技术直接改
60   - - 需要新增的条目直接加行
61   - 改完后回来选择「继续」。
62   -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
63   -```
  20 +**每个填写步骤的通用流程**：输出 `[scope-lock]` 横幅指明文件 + 编辑位置 → `AskUserQuestion` 二选一（「继续」/「有疑问想先沟通」）→ 用 `Grep` 在对应位置搜 `【人工填写：` 占位（命中则打印残留行重新确认；0 命中则继续）→ 用 `Edit` 在 `docs/08-模块任务管理.md` 勾选对应子项。
64 21  
65   -用 `AskUserQuestion` 确认「技术栈检查完毕了吗？」，给「继续」和「有疑问想先沟通」两个选项。
66   -
67   -- 选「继续」→ 进入步骤 C。
68   -- 选「有疑问想先沟通」→ 回答用户问题后，再确认一次。
69   -
70   -完成后，用 `Edit` 在 `docs/08-模块任务管理.md` 中勾选：
71   -- ` - [ ] 技术栈已确认（docs/04 § 零）`
72   -
73   -### C. 提示用户填写需求清单并等待
74   -
75   -`docs/01-需求清单/index.md` 已由 `project-init` 写入占位符模板，这里让用户补齐模块清单。
76   -
77   -向用户输出：
78   -
79   -```
80   -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
81   - [scope-lock] 请填写需求清单模块索引
82   -
83   - 📄 文件位置: ./docs/01-需求清单/index.md
84   - 📌 编辑位置: § 模块索引（表格）
85   -
86   - 请按业务列出所有模块：
87   - - 每行一个模块（如 SYS 系统管理 / PUR 采购 / SAL 销售）
88   - - 「核心功能点」只需关键词，CC 会拆分为 REQ 卡片
89   - 改完后回来选择「继续」。
90   -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
91   -```
92   -
93   -用 `AskUserQuestion` 确认「需求清单模块索引填写完毕了吗？」，给「继续」和「有疑问想先沟通」两个选项。
94   -
95   -- 选「继续」→ 进入步骤 D。
96   -- 选「有疑问想先沟通」→ 回答用户问题后，再确认一次。
97   -
98   -完成后，用 `Edit` 在 `docs/08-模块任务管理.md` 中勾选：
99   -- ` - [ ] 需求清单索引已填写（docs/01-需求清单/index.md）`
  22 +- **A**：`CLAUDE.md` § 🎯 项目概述。占位符含项目名称 / 简述 / 目标用户 / 部署方式。
  23 +- **B**：`docs/04-技术规范.md` § 零。让用户检查 / 调整默认技术栈表（删不需要的行 / 改技术 / 加条目）。
  24 +- **C**：`docs/01-需求清单/index.md`。让用户按业务列出所有模块（每行一个，如 SYS / PUR / SAL），「核心功能点」给关键词即可，CC 会拆 REQ 卡片。
100 25  
101 26 ### D. 生成 REQ 卡片骨架并停下等人工审阅
102 27  
103 28 1. 用 `Grep` 校验 `docs/01-需求清单/index.md` 无 `【人工填写：` 残留；有则回步骤 C。
104 29 2. 用 `Read` 读 `index.md` 解析模块索引。
105   -3. **逐文件渲染落盘**（用 Node 渲染助手，跨平台、字面量安全）：
106   -
107   - - **每模块推断**：三元组 `{module_code, module_name, module_brief}` + N 个 REQ 的六元组 `{req_id, title, goal, rules, constraints, acceptance}`。`req_id`/`title` 从核心功能点拆分；`goal` 展开 `title`；`rules`/`constraints`/`acceptance` 起草业务语义。**不推断**输入 / 输出字段（模板的结构化字段表保留示例行，留待人工逐行填真实数据）。
108   - - **渲染助手** `lib/render.mjs` 的 CLI 形态为 `node <render.mjs> <模板路径> <vars.json 路径> <输出路径>`：读模板 + 读 JSON 变量 + 占位符字面替换 + 自动剥离 HTML 注释，写到输出路径。值含 `$`、`{`、`}`、`}}` 均按字面插入，无需兜底。
109   - - **每个文件三步**：(a) 用 `Write` 写一个临时 vars JSON（仅含该文件用到的占位符键值）；(b) `mkdir -p` 模块目录；(c) `node` 调 render.mjs 渲染。`<MOD>` / `<模块名>` / `<REQ-MOD-NNN>` 等尖括号位置 CC 按 `index.md` 实际值替换。调用形态：
110   -
111   - ```bash
112   - # 模块头：先 Write docs/01-需求清单/<MOD>-<模块名>/_module.vars.json，内容形如
113   - # {"module_code":"<MOD>","module_name":"<模块名>","module_brief":"<module_brief>"}
114   - mkdir -p "docs/01-需求清单/<MOD>-<模块名>"
115   - node "${CLAUDE_PLUGIN_ROOT}/lib/render.mjs" \
116   - "${CLAUDE_SKILL_DIR}/templates/_module-template.md" \
117   - "docs/01-需求清单/<MOD>-<模块名>/_module.vars.json" \
118   - "docs/01-需求清单/<MOD>-<模块名>/_module.md"
119   -
120   - # 每个 REQ：先 Write 该 REQ 的 vars JSON，内容形如
121   - # {"req_id":"<REQ-MOD-NNN>","title":"<title>","goal":"<goal>","rules":"<rules>","constraints":"<constraints>","acceptance":"<acceptance>"}
122   - node "${CLAUDE_PLUGIN_ROOT}/lib/render.mjs" \
123   - "${CLAUDE_SKILL_DIR}/templates/req-card-template.md" \
124   - "docs/01-需求清单/<MOD>-<模块名>/<REQ-MOD-NNN>.vars.json" \
125   - "docs/01-需求清单/<MOD>-<模块名>/<REQ-MOD-NNN>.md"
126   - ```
127   -
128   - - 渲染完成后删除临时 `*.vars.json`（`rm` 或不留亦可，不进入交付物）。
  30 +3. **每模块/每 REQ 渲染**：`Write` vars.json → `mkdir -p` → `node render.mjs`。`<MOD>` / `<模块名>` / `<REQ-MOD-NNN>` 按 `index.md` 实际值替换。
  31 +
  32 + ```bash
  33 + # 模块头：先 Write docs/01-需求清单/<MOD>-<模块名>/_module.vars.json，内容形如
  34 + # {"module_code":"<MOD>","module_name":"<模块名>","module_brief":"<module_brief>"}
  35 + mkdir -p "docs/01-需求清单/<MOD>-<模块名>"
  36 + node "${CLAUDE_PLUGIN_ROOT}/lib/render.mjs" \
  37 + "${CLAUDE_SKILL_DIR}/templates/_module-template.md" \
  38 + "docs/01-需求清单/<MOD>-<模块名>/_module.vars.json" \
  39 + "docs/01-需求清单/<MOD>-<模块名>/_module.md"
  40 +
  41 + # 每个 REQ：先 Write 该 REQ 的 vars JSON，内容形如
  42 + # {"req_id":"<REQ-MOD-NNN>","title":"<title>","goal":"<goal>","rules":"<rules>","constraints":"<constraints>","acceptance":"<acceptance>"}
  43 + node "${CLAUDE_PLUGIN_ROOT}/lib/render.mjs" \
  44 + "${CLAUDE_SKILL_DIR}/templates/req-card-template.md" \
  45 + "docs/01-需求清单/<MOD>-<模块名>/<REQ-MOD-NNN>.vars.json" \
  46 + "docs/01-需求清单/<MOD>-<模块名>/<REQ-MOD-NNN>.md"
  47 + ```
129 48 4. 用 `Edit` 在 `docs/08-模块任务管理.md` 勾选（A1 子项）：
130 49 - ` - [ ] REQ 卡片骨架已生成（docs/01-需求清单/<module>/REQ-*.md，业务内容留待人工填写）`
131   -
132   - **注意**：此处先**不**勾选 `- [ ] A1 范围锁定 — scope-lock` 顶层项；A1 顶层项必须在步骤 E（A1 终结校验）全部通过后才勾选。
133 50 5. 打印「请人工填写 REQ 卡片」横幅并提示用户填完后回来继续（不停止，下一步是 A1 终结校验）：
134 51  
135 52 ```
136 53 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
137 54 [scope-lock] REQ 卡片骨架已生成
138 55  
139   - 产出：
140   - ✓ docs/01-需求清单/<module>/_module.md 模块头
141   - ✓ docs/01-需求清单/<module>/REQ-*.md REQ 卡片骨架
142   -
143   - ⏸ 现在请你逐张打开 REQ 卡片，把结构化字段表填成真实数据：
144   - - **必改**：`输入字段` / `输出字段` 两张表
145   - · 删掉「【示例行，替换为真实字段】」示例行，按本 REQ 业务逐行填真实字段
146   - · 6 列全部填：字段名 / 类型 / 必填 / 校验规则 / 业务规则 / 示例值
147   - · **「示例值」列必须是真实约束下的合法取值**——留 `<示例值>` 或示例行会被 A1 终结校验阻断
148   - - **审阅**：目标 / 跨字段规则 / 边界 / 验收（已起草，对照业务校正）
149   - - **保留**：`TBD` 不要改，由之后流程自动回填
150   -
151   - 填完后回来选择「继续」，进入 A1 终结校验。
  56 + - 产出: docs/01-需求清单/<module>/{_module.md, REQ-*.md}
  57 + - 请逐张填真实字段表, 完成后选「继续」进 A1 终结校验.
152 58 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
153 59 ```
154 60  
... ... @@ -159,7 +65,7 @@ allowed-tools: Read Write Edit Grep Glob Skill AskUserQuestion Bash(mkdir *) Bas
159 65  
160 66 ### E. A1 终结校验（硬闸：全部通过才勾选 A1 顶层）
161 67  
162   -> 本步骤把原本会在编码期（coding.mjs 的 spec / plan stage）弹出的需求澄清 / config Q&A **全部前移到此处**。任一检查不满足，用 `AskUserQuestion` 在**此处（Plan 期）**问清并修订，**禁止**留待编码期。三项检查全过后才在 `docs/08` 勾选 `- [ ] A1 范围锁定 — scope-lock`。
  68 +E.1/E.2/E.3 全过后才勾 A1 顶层。
163 69  
164 70 #### E.1 真实数据校验（每张 REQ 卡片）
165 71  
... ... @@ -173,14 +79,9 @@ allowed-tools: Read Write Edit Grep Glob Skill AskUserQuestion Bash(mkdir *) Bas
173 79  
174 80 #### E.2 配置字段名锁进 config-vars.yaml（敏感键名引用 .env.local）
175 81  
176   -1. 用 `Read` 读 `docs/04-技术规范.md` § 零技术栈，结合 REQ 卡片，盘点本项目需人工提供 / 确认的配置字段，分两类：
177   - - **非敏感、项目级**：后端根包名 / 命名空间（Java package / C# namespace / Python 顶层包 / Go module path 等）、应用端口、前端包名 / scope、前端 dev 端口、管理员初始账号等。
178   - - **敏感凭据**：数据库密码、JWT / 签名密钥、Redis 密码、第三方 API key/secret、OSS / 对象存储凭证、短信 / 邮件服务凭证、管理员初始密码等。
179   -2. 用 `Read` 读模板 `${CLAUDE_SKILL_DIR}/templates/config-vars-template.yaml`，用 `Write` 落盘到仓库根 `config-vars.yaml`：
180   - - **非敏感字段**：按技术栈推断默认值直接填入（如 `http_port: 8080`、`base_package: com.<org>.<app>`）；无对应技术栈的整节删除（如纯后端项目删 `frontend:`）；无法可靠推断的留 `【人工填写：…】`（A2 skeleton-gen 补填）。
181   - - **敏感字段**：只把「键名 + 含义」登记进 `secrets_ref` 列表，**绝不写真实值**（真实值由 A2 写进 `.env.local`，A2 据 `secrets_ref` 核对齐全）。
182   -3. **不**在此创建 / 填写 `docs/07-环境配置.md`——它由 A2 skeleton-gen 生成，只记规则不记具体值。
183   -4. 用 `AskUserQuestion` 向用户确认：「以下配置 / 凭据字段已登记进 config-vars.yaml，是否齐全？还有遗漏的吗？」展示非敏感字段 + `secrets_ref` 键名清单。用户补充则继续登记，直到确认齐全。
  82 +1. 据 `docs/04` § 零 + REQ 卡片盘点配置.
  83 +2. `Read` 模板 `${CLAUDE_SKILL_DIR}/templates/config-vars-template.yaml` → `Write` `config-vars.yaml`: 非敏感字段填默认值, 无技术栈整节删, 不可推断留 `【人工填写】`; 敏感字段只把键名+含义登 `secrets_ref`, 不写真实值.
  84 +3. `AskUserQuestion` 让用户确认齐全.
184 85  
185 86 #### E.3 build / lint / unit / e2e 命令锁进 docs/04 § 零
186 87  
... ... @@ -219,13 +120,13 @@ allowed-tools: Read Write Edit Grep Glob Skill AskUserQuestion Bash(mkdir *) Bas
219 120  
220 121 ## 参考
221 122  
222   -- `CLAUDE.md` § 🎯 项目概述（写入目标）
223   -- `docs/04-技术规范.md`（技术栈输出，供 skeleton-gen 读取使用）
224   -- `docs/01-需求清单/index.md`（模块索引输入）
225   -- `docs/01-需求清单/<module>/_module.md`（模块头输出）
226   -- `docs/01-需求清单/<module>/REQ-*.md`（REQ 卡片骨架输出，A3 db-design-gen / A5 downstream-gen 会回填 TBD 字段）
227   -- `config-vars.yaml`（A1 终结校验 E.2 输出：非敏感配置字段填值 + secrets_ref 键名锁定；仓库根）
228   -- `${CLAUDE_SKILL_DIR}/templates/config-vars-template.yaml`（E.2 渲染来源；跨栈中立，YAML 注释引导）
229   -- `${CLAUDE_SKILL_DIR}/templates/req-card-template.md`（结构化 6 列字段表）
  123 +- `CLAUDE.md`
  124 +- `docs/04-技术规范.md`
  125 +- `docs/01-需求清单/index.md`
  126 +- `docs/01-需求清单/<module>/_module.md`
  127 +- `docs/01-需求清单/<module>/REQ-*.md`
  128 +- `config-vars.yaml`
  129 +- `${CLAUDE_SKILL_DIR}/templates/config-vars-template.yaml`
  130 +- `${CLAUDE_SKILL_DIR}/templates/req-card-template.md`
230 131 - `${CLAUDE_SKILL_DIR}/templates/_module-template.md`
231   -- `${CLAUDE_PLUGIN_ROOT}/lib/render.mjs`（步骤 D 渲染助手；CLI 形态 `node render.mjs <模板> <vars.json> <输出>`，字面量安全 + 自动剥 HTML 注释）
  132 +- `${CLAUDE_PLUGIN_ROOT}/lib/render.mjs`
... ...