SKILL.md 8.62 KB

Edit Raw Blame History



name: design
description: 计划第 2 段——生成架构文档（docs/04 § 一+，含前端 Design Tokens + 环境配置）+ 工具脚本 + .env.local + sql/migrations/，然后从 REQ 正向设计 docs/03 并回填 REQ 依赖表，停下等人工审阅 docs/03。
user-invocable: false


allowed-tools: Read Write Edit Glob Grep Skill AskUserQuestion Bash(mkdir *) Bash(cp *) Bash(cat *) Bash(bash *)

所有输出必须使用中文。


design


执行步骤


步骤 0：打印当前位置流程图

用 Bash 执行以下命令（文件不存在时静默忽略，不报错）：
cat "${CLAUDE_PLUGIN_ROOT}/skills/crosscut/plan-start/banners/flow.txt" 2>/dev/null || true


打印横幅：▶ 计划阶段 ② — design。


A. 读取锁定的输入

用 Read 读取：


docs/04-技术规范.md § 零 技术栈表

docs/01-需求清单/index.md 需求索引

docs/01-需求清单/ 下所有 REQ 卡片（docs/01-需求清单/*/REQ-*.md）


后续所有内容都基于它们推导。


B. 生成 docs/04 § 一+（保留 § 零 不覆盖）

docs/04 已由 init 写入 § 零。本步骤追加 § 一 ~ 五。

docs/04 承担三类内容（不再生成独立的前端规范文件或环境配置文件）：


§ 一~三：后端/前端/共同编码规范
§ 四：前端 Design Tokens + 交互约定
§ 五：环境配置


操作：


读取 docs/04-技术规范.md（现有 § 零 完整内容）。
读取 ${CLAUDE_SKILL_DIR}/templates/docs-04-skeleton-template.md。
基于技术栈，按大纲生成 § 一 ~ 五 的项目专属内容，剥掉 HTML 注释（注释是给 LLM 的提示，不应出现在最终文档里）。
拼接原有内容和新生成内容，写回 docs/04-技术规范.md。


完成后，用 Edit 在 docs/08-模块任务管理.md 中勾选：


- [ ] 架构文档已生成（docs/04 § 一+ ｜ scripts/*.sh ｜ .env.local ｜ sql/migrations/）（步骤 C 完成后一并勾选）


C. 生成工具脚本 + 目录结构


C.1 复制固定文件
mkdir -p scripts sql/migrations src/styles
cp "${CLAUDE_SKILL_DIR}/templates/env-local-template" .env.local
cp "${CLAUDE_SKILL_DIR}/templates/scripts-setup-test-db-template.sh" scripts/setup-test-db.sh


注意：本阶段不生成 src/styles/tokens.css（前端 token 骨架由前端阶段处理）。


C.2 渲染 scripts/test.sh

读取 ${CLAUDE_SKILL_DIR}/templates/scripts-test-template.sh，基于步骤 A 的技术栈（docs/04 § 零）为以下 7 个命令槽推断命令后写到 scripts/test.sh（纯后端项目可把前端 / E2E 槽填 echo 占位）：


{{backend_build}} / {{backend_lint}} / {{backend_test}} — 后端各 stage 命令

{{frontend_build}} / {{frontend_lint}} / {{frontend_test}} — 前端各 stage 命令

{{e2e_cmd}} — E2E（无 E2E 工具则填 echo "[test.sh] e2e 略"）


推断规则：根据 docs/04 § 零。


「后端*」存在 → 据后端技术栈推 backend 三槽（build / lint / test 命令）
「前端*」存在 → 据前端技术栈推 frontend 三槽
缺席 stack → 三槽全填 :（语法合法即可）

{{e2e_cmd}} 通常仅前端，按上述前端规则或填 echo "[test.sh] e2e 略"


表结构异常（列名变更 / 无中文前缀）时停下，用 AskUserQuestion 让用户显式确认每 stack 命令。


C.3 赋权
bash -c "chmod +x scripts/*.sh"


完成后，用 Edit 在 docs/08-模块任务管理.md 中勾选：


- [ ] 架构文档已生成（docs/04 § 一+ ｜ scripts/*.sh ｜ .env.local ｜ sql/migrations/）


D. 追加 .gitignore 忽略项

调用脚本完成合并：
bash "${CLAUDE_SKILL_DIR}/scripts/merge-gitignore.sh" "${CLAUDE_SKILL_DIR}/templates/gitignore-append-template"


E. 推导 schema + 渲染 docs/03

基于步骤 A 读到的 REQ + docs/04 § 一命名规范，正向推导业务实体 → 表 + 字段 + 索引 + 外键。要求：


严格套用 docs/04 § 一 的命名规范（匈牙利前缀 i int / s varchar / t datetime 等）

主键：模板内置 iIncrement 为主键。REQ 明确要求复合主键 / UUID / 业务主键时按 REQ；其他主键变更需同步改 docs-03-header / docs-03-table 两份模板

外键：依据 REQ 中的引用关系（如「订单引用客户」），明确列出 ON DELETE / ON UPDATE 策略；不能确定时默认 RESTRICT


索引：根据 REQ 的查询模式推导业务索引；外键列默认建索引；标准列里 sBrandsId / sSubsidiaryId 这类多租户隔离列，按业务查询模式建组合索引

业务注记：对每张表用一两句话说明业务用途、关键约束、与其他表的关系


如果某 REQ 表述模糊以致无法推断关键 schema 细节（如：枚举值范围 / 字段长度上限 / 必填性），先按合理默认推导并在该字段「业务含义」列加 【人工填写：需用户审阅】 标注，不打断本次推导。

渲染 docs/03：


读取 ${CLAUDE_SKILL_DIR}/templates/docs-03-header-template.md，填充 schema_name（从 .env.local 读 DB_SCHEMA，无则填 【人工填写：DB_SCHEMA】）、er_overview（纯文本 ER 概览）。
渲染「表清单」：对每张表，读取并填充 ${CLAUDE_SKILL_DIR}/templates/docs-03-table-template.md。
写入 docs/03-数据库设计文档.md。


完成后，用 Edit 在 docs/08-模块任务管理.md 中勾选：


- [ ] docs/03 数据库设计已生成（REQ → 表/字段/索引/外键，回填 REQ 依赖表）


F. 回填模块头 + REQ 卡片的 TBD 字段


列出 docs/01-需求清单/*/_module.md（模块头）和 docs/01-需求清单/*/REQ-*.md（REQ 卡片）。
在这些文件中搜索 TBD(design 自动补) 并回填为实际表名。不动 TBD(build-db 自动补)。


_module.md 的 涉及表 字段：填入该模块涉及的所有表名（逗号分隔）

REQ-*.md 的 依赖表 字段：填入该 REQ 操作的表名（逗号分隔）


打印回填统计：design 回填 <M> 处模块"涉及表" + <N> 处 REQ"依赖表"。


G. 勾选 § 一 ② 顶层 + 停下等人工审阅


完成后，用 Edit 在 docs/08-模块任务管理.md 中勾选 ② 顶层：


- [ ] 计划 ② 脚手架 + 数据库设计 — design


打印停下横幅并停下：

   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
    [design] ✅ 计划 ② 完成

    产出：
      ✓ docs/04-技术规范.md（§ 一+ ｜ § 四 Design Tokens ｜ § 五 环境配置）
      ✓ scripts/setup-test-db.sh + scripts/test.sh（已赋权）
      ✓ .env.local（含占位符，凭据请自填）
      ✓ sql/migrations/（目录已建）
      ✓ .gitignore（已追加忽略项）
      ✓ docs/03-数据库设计文档.md
      ✓ docs/01 各 REQ 卡片"依赖表" + 模块头"涉及表" 已回填

    ⏸ 现在请你审阅 docs/03。
       重点关注：
         - 业务实体覆盖是否完整
         - 字段类型 / 长度 / 是否可空 / 默认值是否合理
         - 索引是否覆盖主要查询模式
         - 外键 ON DELETE / ON UPDATE 策略是否符合业务
         - 字段「业务含义」列含 `【人工填写：需用户审阅】` 标注的位置需逐一确认
         - .env.local 中的凭据占位符请直接编辑文件填写（凭据不进会话）

    审阅完成后，再运行：
      /erp-workflow:plan-start

   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━


停止，不调用任何下游 skill。


参考


docs/04-技术规范.md § 零（技术栈输入）

docs/01-需求清单/index.md（模块索引输入）

docs/01-需求清单/<module>/_module.md（模块头：回填 涉及表）

docs/01-需求清单/<module>/REQ-*.md（REQ 输入 + 回填 依赖表）

${CLAUDE_SKILL_DIR}/templates/docs-04-skeleton-template.md（大纲：§ 一~三 编码规范 + § 四 Design Tokens + § 五 环境配置）
${CLAUDE_SKILL_DIR}/templates/docs-03-header-template.md
${CLAUDE_SKILL_DIR}/templates/docs-03-table-template.md

${CLAUDE_SKILL_DIR}/templates/scripts-test-template.sh（推断命令填充槽位；缺席 stack 填 :）

${CLAUDE_SKILL_DIR}/templates/scripts-setup-test-db-template.sh（0 槽位）

${CLAUDE_SKILL_DIR}/templates/env-local-template（0 槽位）

${CLAUDE_SKILL_DIR}/templates/gitignore-append-template（0 槽位）

${CLAUDE_SKILL_DIR}/scripts/merge-gitignore.sh（.gitignore 逐行判重合并脚本）