diff --git a/skills/plan/scope-lock/SKILL.md b/skills/plan/scope-lock/SKILL.md index e618bb2..4fc6418 100644 --- a/skills/plan/scope-lock/SKILL.md +++ b/skills/plan/scope-lock/SKILL.md @@ -1,8 +1,8 @@ --- name: scope-lock -description: A1 计划范围锁定——引导用户填写项目概述 + 技术栈 + 需求索引，并按模块子目录生成 REQ 卡片骨架（CC 推断 req_id/title/goal/rules/constraints/acceptance；输入/输出 字段表为结构化 6 列表单由人工逐行填真实数据）；末尾执行 A1 终结校验：每张 REQ 卡片字段含真实数据、配置字段名锁进 config-vars.yaml（非敏感填值 + secrets_ref 键名引用 .env.local）、build/lint/unit/e2e 命令锁进 docs/04 §零，缺则当场 AskUserQuestion 问清。 +description: A1 计划范围锁定——引导用户填写项目概述 + 技术栈 + 需求索引，并按模块子目录生成 REQ 卡片（CC 据 index.md 填 req_id/title/goal/rules/constraints/acceptance 这 6 个 `{{}}` 占位，模板其余内容含输入/输出示例字段表原样复制）；末尾执行 A1 终结校验：每张 REQ 卡片 6 个占位均填真实数据、全部配置锁进 config-vars.yaml（非敏感填值、敏感凭据留占位待人工填）、build/lint/unit/e2e 命令锁进 docs/04 §零，缺则当场 AskUserQuestion 问清。 user-invocable: false -allowed-tools: Read Write Edit Grep Glob Skill AskUserQuestion Bash(mkdir *) Bash(node *) +allowed-tools: Read Write Edit Grep Glob Skill AskUserQuestion Bash(mkdir *) --- **所有输出必须使用中文。** @@ -25,63 +25,47 @@ allowed-tools: Read Write Edit Grep Glob Skill AskUserQuestion Bash(mkdir *) Bas ### D. 生成 REQ 卡片骨架并停下等人工审阅 -1. 用 `Grep` 校验 `docs/01-需求清单/index.md` 无 `【人工填写：` 残留；有则回步骤 C。 -2. 用 `Read` 读 `index.md` 解析模块索引。 -3. **每模块/每 REQ 渲染**：`mkdir -p` → `Write` vars.json → `node render.mjs`。`` / `<模块名>` / `` 按 `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" - ``` -4. 用 `Edit` 在 `docs/08-模块任务管理.md` 勾选（A1 子项）： +1. 读 `index.md` 解析模块索引；读两个模板 `${CLAUDE_SKILL_DIR}/templates/_module-template.md`、`${CLAUDE_SKILL_DIR}/templates/req-card-template.md` 作为卡片结构参照。 +2. **每模块/每 REQ 直接 `Write`**：对每个模块先 `mkdir -p "docs/01-需求清单/<MOD>-<模块名>"`，再照模板结构 `Write`，`<MOD>` / `<模块名>` / `<REQ-MOD-NNN>` 按 `index.md` 实际值替换： + - **模块头** `_module.md`：据 `index.md` 填 `module_code` / `module_name` / `module_brief`；`依赖模块: TBD(A5 自动补)` / `涉及表: TBD(A3 自动补)` 两行原样保留。 + - **每个 REQ** `<REQ-MOD-NNN>.md`：**照模板原样 `Write`**，只把 `{{req_id}}` / `{{title}}` / `{{goal}}` / `{{rules}}` / `{{constraints}}` / `{{acceptance}}` 这 6 个占位替换为据 `index.md` 推断的真实值；模板其余内容（`输入` / `输出` 示例字段表、`依赖表: TBD(A3 自动补)` / `依赖接口: TBD(A5 自动补)` 两行）**原样复制不动**；模板顶部 HTML 引导注释**不写进产物**。 +3. 用 `Edit` 在 `docs/08-模块任务管理.md` 勾选（A1 子项）： - ` - [ ] REQ 卡片骨架已生成（docs/01-需求清单/<module>/REQ-*.md，业务内容留待人工填写）` -5. 打印「请人工填写 REQ 卡片」横幅并提示用户填完后回来继续（不停止，下一步是 A1 终结校验）： +4. 打印「请人工填写 REQ 卡片」横幅并提示用户填完后回来继续： ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ [scope-lock] REQ 卡片骨架已生成 - 产出: docs/01-需求清单/<module>/{_module.md, REQ-*.md} - - 请逐张填真实字段表, 完成后选「继续」进 A1 终结校验. + - 6 个占位已填真实值；输入/输出字段表为模板示例内容(如需可自行调整)。 + - 审阅后选「继续」进 A1 校验. ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ``` -用 `AskUserQuestion` 确认「所有 REQ 卡片的结构化字段都填成真实数据了吗？」，给「继续」和「有疑问想先沟通」两个选项。 +用 `AskUserQuestion` 确认「REQ 卡片已生成（6 个占位已填真实值），确认进入 A1 校验吗？」，给「继续」和「有疑问想先沟通」两个选项。 -- 选「继续」→ 进入步骤 E（A1 终结校验）。 +- 选「继续」→ 进入步骤 E。 - 选「有疑问想先沟通」→ 回答用户问题后，再确认一次。 -### E. A1 终结校验（硬闸：全部通过才勾选 A1 顶层） +### E. A1 校验 -E.1/E.2/E.3 全过后才勾 A1 顶层。 +#### E.1 占位校验（每张 REQ 卡片） -#### E.1 真实数据校验（每张 REQ 卡片） +卡片正文是模板原样复制，只有 6 个 `{{}}` 标量由 CC 填——本步只校验这 6 个占位填全填真。 1. 用 `Glob` 列出所有 `docs/01-需求清单/<module>/REQ-*.md`。 2. 对每张卡片用 `Read` + `Grep` 校验： - - **无模板默认占位**：卡片内**不得**出现 `【示例行，替换为真实字段】` 或 `<示例值>`（用 `Grep` 搜这两个字面量，命中即视为未完成）。 - - **结构化字段非空**：`输入字段` / `输出字段` 两张表每行 6 列均非空，且不是模板示例行内容；至少各有 1 行真实字段（除非该 REQ 确实无输入/输出，需在卡片显式标注）。 - - **`示例值` 列已填真实取值**：每行示例值列为真实约束下的合法取值，非占位。 - - **`{{...}}` 残留**：不得残留任何 `{{` 占位（说明渲染未替换）。 -3. 任一卡片不通过：打印不通过的卡片路径 + 具体缺口行，用 `AskUserQuestion` 引导用户当场补齐（可针对具体字段含义/校验规则发问），修订后重跑 E.1，直到全部通过。 + - **无 `{{` 残留**：不得残留任何 `{{` 占位（命中即说明 6 个标量未全部替换）。 + - **6 个标量为真实值**：`req_id` / `title` / `goal` / `rules` / `constraints` / `acceptance` 均据 `index.md` 填为真实内容，非空、非回显占位名。 + - 输入/输出字段表为模板原样复制内容，**不在此校验**。 +3. 任一卡片不通过：打印不通过的卡片路径 + 具体缺口行，用 `AskUserQuestion` 引导用户当场补齐，修订后重跑 E.1，直到全部通过。 -#### E.2 配置字段名锁进 config-vars.yaml（敏感键名引用 .env.local） +#### E.2 全部配置锁进 config-vars.yaml（含敏感凭据，单一文件，随项目提交） 1. 据 `docs/04` § 零 + REQ 卡片盘点配置. -2. `Read` 模板 `${CLAUDE_SKILL_DIR}/templates/config-vars-template.yaml` → `Write` `config-vars.yaml`: 非敏感字段填默认值, 无技术栈整节删, 不可推断留 `【人工填写】`; 敏感字段只把键名+含义登 `secrets_ref`, 不写真实值. -3. `AskUserQuestion` 让用户确认齐全. +2. `Read` 模板 `${CLAUDE_SKILL_DIR}/templates/config-vars-template.yaml` → `Write` `config-vars.yaml`: 非敏感字段（包名 / 端口 / 前端包名 / 初始账号等）CC 据上下文填默认值, 无技术栈整节删, 不可推断留 `【人工填写】`; 敏感字段（`database.password` / `admin_init.password` / `secrets.*` 等真实凭据）CC **不臆造**, 一律留 `【人工填写：<说明>】` 占位待人工填. +3. `AskUserQuestion` 让用户确认非敏感项齐全, 并提示敏感凭据需用户**自己在 config-vars.yaml 填真实值**. #### E.3 build / lint / unit / e2e 命令锁进 docs/04 § 零 @@ -93,12 +77,12 @@ E.1/E.2/E.3 全过后才勾 A1 顶层。 - **e2e**（端到端测试命令，如 `npm run test:e2e`；无则显式记 `无`） 3. 把确认后的命令写入 `docs/04-技术规范.md` § 零（若 § 零无「命令」小节则用 `Edit` 新增一个「命令清单」小节，按 stack 分组列出 build/lint/unit/e2e 四行）。这些命令是 Coding 阶段 `coding.mjs` 的 tdd / test-gate 读取来源，必须在此锁全。 -#### E.4 全部通过后勾选 A1 顶层并停止 +#### E.4 全部通过后勾选 A1 顶层并自动进入 A2 三项检查（E.1 / E.2 / E.3）全部通过后： 1. 用 `Edit` 在 `docs/08-模块任务管理.md` 勾选 `- [ ] A1 范围锁定 — scope-lock` 顶层项。 -2. 打印 A1 完成横幅并**停止**： +2. 打印 A1 完成横幅： ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ @@ -109,15 +93,15 @@ E.1/E.2/E.3 全过后才勾 A1 顶层。 ✓ docs/04 § 零 技术栈 + build/lint/unit/e2e 命令 ✓ docs/01-需求清单/index.md 模块索引 ✓ docs/01-需求清单/<module>/_module.md 模块头 - ✓ docs/01-需求清单/<module>/REQ-*.md 字段表已填真实数据 - ✓ config-vars.yaml 配置字段 + secrets_ref 键名已锁（敏感真实值留待 A2 .env.local） - - 运行以下命令继续进入 A2： - /erp-workflow:plan-start + ✓ docs/01-需求清单/<module>/REQ-*.md 6 个占位已填真实值（字段表为模板示例） + ✓ config-vars.yaml 配置已锁（非敏感已填；DB 凭据 / 密钥占位待人工填，plan-start 把关） + 自动进入 A2：skeleton-gen ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ``` +3. 立即调用 `Skill(skeleton-gen)` 进入 A2。 + ## 参考 - `CLAUDE.md` @@ -129,4 +113,3 @@ E.1/E.2/E.3 全过后才勾 A1 顶层。 - `${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` diff --git a/skills/plan/scope-lock/templates/req-card-template.md b/skills/plan/scope-lock/templates/req-card-template.md index 667f364..aa156d5 100644 --- a/skills/plan/scope-lock/templates/req-card-template.md +++ b/skills/plan/scope-lock/templates/req-card-template.md @@ -5,17 +5,44 @@ req-card-template：单张 REQ 卡片骨架。两处 `TBD(A3 自动补)` / `TBD( **目标**: {{goal}} -**输入字段**: +- **输入**: 用户提交用户名（3-20 位字母数字下划线，系统内唯一）、姓名（2-50字符）、手机号（11 位数字，系统内唯一）、邮箱（标准邮箱格式，可选）、初始密码（8-20位含大小写字母和数字） -| 字段名 | 类型 | 必填 | 校验规则 | 业务规则 | 示例值 | -| --- | --- | --- | --- | --- | --- | -| {{input_field_name}} | {{input_field_type}} | {{input_field_required}} | {{input_field_validation}} | {{input_field_business}} | {{input_field_example}} | + - **表1**： + + | 字段 | 类型 | 必填 | 输入方式 | 显示来源 | 预加载 | 默认值 | 业务规则 | + | ---- | ---- | --- | ---- | ----- | --- | --- | ------------------- | + | 用户名 | 文本 | 是 | 手工输入 | `职员表` | 否 | — | 3-20 位字母数字下划线；系统内唯一 | + | 姓名 | 文本 | 是 | 下拉单选 | `职员表` | 用户操作时 | — | 2-50 个字符 | + | 手机号 | 文本 | 是 | 手工输入 | `职员表` | 否 | — | 11 位数字；系统内唯一 | + | 邮箱 | 文本 | 否 | 手工输入 | `职员表` | 否 | — | 标准邮箱格式 | + | 角色 | 文本 | 是 | 下拉单选 | 普通用户/超级管理员 | 页面加载时 | 普通用户 | 至少选择 1 个 | + | 初始密码 | 文本 | 是 | 手工输入 | — | — | — | 8-20 位；含大小写字母和数字；显示星号 | -**输出字段**: + - **表2**： -| 字段名 | 类型 | 必填 | 校验规则 | 业务规则 | 示例值 | -| --- | --- | --- | --- | --- | --- | -| {{output_field_name}} | {{output_field_type}} | {{output_field_required}} | {{output_field_validation}} | {{output_field_business}} | {{output_field_example}} | + | 字段 | 类型 | 必填 | 输入方式 | 显示来源 | 预加载 | 默认值 | 业务规则 | + | --- | --- | --- | --- | --- | --- | --- | --- | + | 用户名 | 文本 | 是 | 手工输入 | `职员表` | 否 | — | 3-20 位字母数字下划线；系统内唯一 | + | 姓名 | 文本 | 是 | 下拉单选 | `职员表` | 用户操作时 | — | 2-50 个字符 | + | 手机号 | 文本 | 是 | 手工输入 | `职员表` | 否 | — | 11 位数字；系统内唯一 | + +- **输出**: 返回用户 id + + - **表1**： + + | 字段 | 类型 | 显示来源 | + | --- | --- | --- | + | 用户名 | 文本 | `职员表` | + | 姓名 | 文本 | `职员表` | + | 角色 | 文本 | `职员表` | + + - **表2**： + + | 字段 | 类型 | 显示来源 | + | --- | --- | --- | + | 用户名 | 文本 | `职员表` | + | 姓名 | 文本 | `职员表` | + | 角色 | 文本 | `职员表` | - **跨字段规则**: {{rules}} - **边界**: {{constraints}}