diff --git a/skills/plan/lite-init/SKILL.md b/skills/plan/lite-init/SKILL.md new file mode 100644 index 0000000..9787e15 --- /dev/null +++ b/skills/plan/lite-init/SKILL.md @@ -0,0 +1,233 @@ +--- +name: lite-init +description: 计划第 1 段——项目初始化 + 范围锁定。复制 CLAUDE.md/docs(01/04/08) 模板、依赖检查、git init,引导项目概述+技术栈+需求索引,生成 REQ 卡片骨架,停下等人工审阅 REQ。 +user-invocable: false +allowed-tools: Glob Read Edit Grep Skill AskUserQuestion Bash(mkdir *) Bash(cp *) Bash(sed *) Bash(bash *) Bash(cat *) Bash(git init) Bash(command -v *) Bash(uname *) Bash(brew *) Bash(apt *) Bash(apt-get *) Bash(yum *) Bash(apk *) Bash(export PATH=*) Bash(echo *) +--- + +**所有输出必须使用中文。** + +你负责完成计划第 ① 段:项目初始化 + 范围锁定。合并了原 project-init + scope-lock 的全部逻辑。 + +## 执行步骤 + +### 步骤 0:打印计划流程图 + +用 `Bash` 向用户展示 lite 流程图(▶ 位于"计划 ①"): + +```bash +cat "${CLAUDE_PLUGIN_ROOT}/skills/crosscut/plan-start/banners/flow-lite.txt" 2>/dev/null || true +``` + +> 注:`flow-lite.txt` 由 Task 7 创建,当前若文件不存在,命令静默忽略,不影响后续执行。 + +打印分发横幅: + +``` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + [lite-init] 计划 ① 初始化 + 范围锁定 + ▶ 当前位置:计划 ① / 共 ③ +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +### A. 幂等复制模板文件 + +用 `Bash` 一次性完成。`cp -n` 表示"不覆盖已存在的文件": + +```bash +mkdir -p docs/01-需求清单 +cp -n "${CLAUDE_SKILL_DIR}/templates/CLAUDE-template.md" CLAUDE.md +cp -n "${CLAUDE_SKILL_DIR}/templates/docs-01-index-template.md" docs/01-需求清单/index.md +cp -n "${CLAUDE_SKILL_DIR}/templates/docs-04-stack-template.md" docs/04-技术规范.md +cp -n "${CLAUDE_SKILL_DIR}/templates/docs-08-initial-template.md" docs/08-模块任务管理.md +``` + +完成后,用 `Edit` 在 `docs/08-模块任务管理.md` 中勾选: +- ` - [ ] 项目文件骨架已创建(CLAUDE.md + docs/01 index + docs/04 + docs/08)` + +### B. 依赖检查 + 自动安装(命令行工具) + +对 **git、mysql** 两个工具依次执行以下流程: + 1. 如果缺失,尝试自动安装。 + 2. 如果检测到不在 PATH,尝试添加进 PATH,并加载。 + +全部通过后打印单行汇总再进入步骤 C: + +``` +[lite-init] 依赖检查: git ✓ mysql ✓ +``` + +完成后,用 `Edit` 在 `docs/08-模块任务管理.md` 中勾选: +- ` - [ ] 依赖检查通过(git / mysql)` + +### C. 初始化 Git(如尚未初始化) + +用 `Glob` 检查 `.git/` 目录是否存在。 +- 不存在 → 用 `Bash` 执行 `git init`。 +- 已存在 → 跳过。 + +完成后,用 `Edit` 在 `docs/08-模块任务管理.md` 中勾选: +- ` - [ ] Git 已初始化` + +打印完成横幅: + +``` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + [lite-init] 项目初始化完成 + + 已创建: + ✓ CLAUDE.md(从插件模板复制) + ✓ docs/01-需求清单/index.md(待人工填写模块索引) + ✓ docs/04-技术规范.md(默认技术栈,步骤 E 让用户确认) + ✓ docs/08-模块任务管理.md(全流程进度跟踪) + 已勾选:初始化子项 3 项 + + 下一步:引导项目概述 + 技术栈 + 需求索引 + 生成 REQ 卡片 +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +### D. 提示用户填写项目概述并等待 + +向用户输出: + +``` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + [lite-init] 请填写项目概述 + + 📄 文件位置: ./CLAUDE.md + 📌 编辑位置: § 🎯 项目概述 + + 请将以下占位符替换为实际值: + - 项目名称 + - 项目简述 + - 目标用户 + - 部署方式 + 改完后回来选择「继续」。 +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +用 `AskUserQuestion` 询问: +- **question**: `项目概述填写完毕了吗?` + - 用户选择「继续」→ 用 `Grep` 在 `CLAUDE.md` 搜索 `【人工填写:`(限定 § 🎯 项目概述 节)。命中 → 打印残留行 + 路径,重新弹出同样的 AskUserQuestion;0 命中 → 勾选并进入步骤 E。 + - 用户选择「有疑问想先沟通」→ 回答用户问题后,再次弹出同样的 QA。 + +0 命中后,用 `Edit` 在 `docs/08-模块任务管理.md` 中勾选: +- ` - [ ] 项目概述已填写(CLAUDE.md § 🎯 项目概述)` + +### E. 提示用户检查默认技术栈并等待 + +`docs/04-技术规范.md` 已由步骤 A 用模板复制(默认技术栈)。本步骤让用户检查 / 调整 § 零。 + +向用户输出: + +``` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + [lite-init] 技术栈已保存 + + 📄 文件位置: ./docs/04-技术规范.md(由模板生成) + 📌 编辑位置: § 零、技术栈总览 + + 请检查技术栈表: + - 不需要的行直接删除(如纯后端项目删前端行) + - 需要替换的技术直接改 + - 需要新增的条目直接加行 + 改完后回来选择「继续」。 +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +用 `AskUserQuestion` 询问: +- **question**: `技术栈检查完毕了吗?` + - 用户选择「继续」→ 进入步骤 F。 + - 用户选择「有疑问想先沟通」→ 回答用户问题后,再次弹出同样的 QA。 + +完成后,用 `Edit` 在 `docs/08-模块任务管理.md` 中勾选: +- ` - [ ] 技术栈已确认(docs/04 § 零)` + +### F. 提示用户填写需求清单并等待 + +`docs/01-需求清单/index.md` 已由步骤 A 写入占位符模板,这里让用户补齐模块清单。 + +向用户输出: + +``` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + [lite-init] 请填写需求清单模块索引 + + 📄 文件位置: ./docs/01-需求清单/index.md + 📌 编辑位置: § 模块索引(表格) + + 请按业务列出所有模块: + - 每行一个模块(如 SYS 系统管理 / PUR 采购 / SAL 销售) + - 「核心功能点」只需关键词,CC 会拆分为 REQ 卡片 + 改完后回来选择「继续」。 +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +用 `AskUserQuestion` 询问: +- **question**: `需求清单模块索引填写完毕了吗?` + - 用户选择「继续」→ 进入步骤 G。 + - 用户选择「有疑问想先沟通」→ 回答用户问题后,再次弹出同样的 QA。 + +完成后,用 `Edit` 在 `docs/08-模块任务管理.md` 中勾选: +- ` - [ ] 需求清单索引已填写(docs/01-需求清单/index.md)` + +### G. 生成 REQ 卡片骨架并停下等人工审阅 + +1. 用 `Grep` 校验 `docs/01-需求清单/index.md` 无 `【人工填写:` 残留;有则回步骤 F。 +2. 用 `Read` 读 `index.md` 解析模块索引。 +3. **单次 Bash 写入所有文件**(替代 N×9 次 Edit): + + - **每模块推断**:三元组 `{module_code, module_name, module_brief}` + N 个 REQ 的六元组 `{req_id, title, goal, rules, constraints, acceptance}`。`req_id`/`title` 从核心功能点拆分;`goal` 展开 `title`;`rules`/`constraints`/`acceptance` 起草业务语义。**不推断**输入 / 输出(模板原样保留示例)。 + - **单次 Bash**:调 `${CLAUDE_SKILL_DIR}/scripts/render.sh` 落盘所有文件(脚本内部完成模板读取 + 占位符替换 + HTML 注释剥离)。下面是**调用形态**示例,`` / `<模块名>` / `` 等尖括号位置 CC 按 `index.md` 实际值替换: + + ```bash + R="${CLAUDE_SKILL_DIR}/scripts/render.sh" + # 每个模块:mkdir + 1 个 render module + N 个 render req(每 REQ 一行) + mkdir -p "docs/01-需求清单/-<模块名>" + bash "$R" module "docs/01-需求清单/-<模块名>/_module.md" "" "<模块名>" "" + bash "$R" req "docs/01-需求清单/-<模块名>/.md" "" "" "<goal>" "<rules>" "<constraints>" "<acceptance>" + ``` + + - **兜底**:值含字面 `$xxx` 或 `}}` 的 REQ 单独走 cp + Edit。 + +4. 用 `Edit` 在 `docs/08-模块任务管理.md` 勾选(计划 ① 子项 + ① 顶层): + - ` - [ ] REQ 卡片骨架已生成(docs/01-需求清单/<module>/REQ-*.md)` + - `- [ ] 计划 ① 初始化 + 范围锁定 — lite-init` + +5. 打印停下横幅并**停止**,不自动派发 lite-design: + +``` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + [lite-init] ✅ 计划 ① 完成 + + 产出: + ✓ CLAUDE.md § 🎯 项目概述 + ✓ docs/04 § 零 技术栈 + ✓ docs/01-需求清单/index.md 模块索引 + ✓ docs/01-需求清单/<module>/_module.md 模块头 + ✓ docs/01-需求清单/<module>/REQ-*.md REQ 卡片骨架 + + ⏸ 现在请你逐张打开 REQ 卡片: + - **必改**:输入 / 输出 两段 + · `表1` / `表2` 是模板示例,按本 REQ 业务**改字段 / 增删行 / 增删整张表** + - **审阅**:目标 / 跨字段规则 / 边界 / 验收(已起草,对照业务校正) + - **保留**:`TBD` 不要改,由之后流程自动回填 + + 审阅完成后,运行以下命令进入计划 ②: + /erp-workflow:plan-start + +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +> **STOP**:此处是人工审阅 REQ 的闸门。停止执行,等待用户运行 `/erp-workflow:plan-start` 后由 plan-start 派发 lite-design。 + +## 参考 + +- `${CLAUDE_SKILL_DIR}/templates/CLAUDE-template.md`(项目级 CLAUDE.md 模板) +- `${CLAUDE_SKILL_DIR}/templates/docs-01-index-template.md`(需求索引初稿) +- `${CLAUDE_SKILL_DIR}/templates/docs-04-stack-template.md`(默认技术栈) +- `${CLAUDE_SKILL_DIR}/templates/docs-08-initial-template.md`(计划阶段进度初始化) +- `${CLAUDE_SKILL_DIR}/templates/req-card-template.md`(REQ 卡片模板) +- `${CLAUDE_SKILL_DIR}/templates/_module-template.md`(模块头模板) +- `${CLAUDE_SKILL_DIR}/scripts/render.sh`(步骤 G 渲染助手,dispatch `module` / `req` 两种模式) +- 下游:人工审阅 REQ 后运行 `/erp-workflow:plan-start`,由 plan-start 派发 `lite-design`(计划 ②) diff --git a/skills/plan/scope-lock/scripts/render.sh b/skills/plan/lite-init/scripts/render.sh index 8a83488..8a83488 100644 --- a/skills/plan/scope-lock/scripts/render.sh +++ b/skills/plan/lite-init/scripts/render.sh diff --git a/skills/plan/lite-init/templates/CLAUDE-template.md b/skills/plan/lite-init/templates/CLAUDE-template.md new file mode 100644 index 0000000..02930e0 --- /dev/null +++ b/skills/plan/lite-init/templates/CLAUDE-template.md @@ -0,0 +1,273 @@ +# CLAUDE.md — ERP项目 Claude Code 主指令文件 + +> 本文件是 Claude Code 的"操作手册"。Claude Code 启动时会自动读取此文件。 + +--- + +## 🎯 项目概述 + +- **项目名称**: 【人工填写:公司 + 项目名,例如"XX 公司 ERP 管理系统"】 +- **项目简述**: 【人工填写:一句话描述项目目标,例如"面向中小制造企业的全流程 ERP,涵盖采购/库存/生产/销售/财务"】 +- **目标用户**: 【人工填写:谁会用,例如"企业内部管理人员(采购员、仓管员、生产主管、销售员、财务人员、管理层)"】 +- **部署方式**: 【人工填写:私有化部署 / 云部署 / Docker 容器化 等】 + +--- + +## 🔄 编码开发流程(统一循环) + +编码阶段入口:`/erp-workflow:coding-start`。所有模块统一走同一个 phase-driver 循环,无前后端分段。 + +### 阶段路由(coding-start 内,只做分发) + +`coding-start` 每次入口扫描 `docs/08 § 二` 的 `里程碑:` 字段 + 本地 `git tag -l 'milestone/<id>'`,找第一个未打里程碑的模块分发到 `phase-driver`;所有模块里程碑均已打 → 输出"全部完成"。 + +### 统一功能循环 + +**模块循环(外)**:`phase-driver` → feature 循环 → `milestone`(本地 merge 进默认分支 + 打 `milestone/<id>` tag)→ 自动回调 `coding-start` 路由下一模块(无人工介入)。 + +**功能循环(内,每个 REQ-XXX-NNN 一遍)**:`feature-spec` → `feature-tdd` → `feature-review`。 +- `feature-review` verdict=approve → 勾选 docs/08 § 二 对应功能子项,继续下一 feature; +- 模块所有 feature 完成 → 调用 `milestone` 打里程碑 tag + 回调 `coding-start`。 + +### 里程碑前守门 + +- `milestone` 在打 tag 前内置测试闸门(后端:`scripts/test.sh`);红色不得跳过。 +- 测试 / 验证统一派发到 Agent 子会话执行,主会话只接收结构化结论。 + +--- + +## ✅ 阶段完成判定规则 + +`docs/08-模块任务管理.md` 分两段: +- `§ 一`:计划阶段三段(①②③)进度勾选 +- `§ 二`:编码模块元数据表(每个模块一行 bullet,记录依赖 / 路径 / 里程碑 tag / 功能子项) + +**阶段完成判定**统一以 `里程碑:` 字段 + 本地 `git tag -l 'milestone/<id>'` 判定;子项勾选只作可视化进度,不参与完成判定。 + +### 后端模块格式 + +每个后端模块在 docs/08 § 二 中长这样: + +```markdown +- module_0 系统管理 + - 依赖: — + - 路径: backend/module/sys/ + - 里程碑: — + - 功能: + - [ ] REQ-SYS-001 用户登录 + - [ ] REQ-SYS-002 用户注册 +``` + +- `里程碑:` 字段由 `milestone` 在打里程碑 tag 时从 `—` 改为 `milestone/<module_id>`。 +- 每个 `REQ-*` 子项由 `feature-review` 在 verdict=approve 时自动勾选为 `[x]`。 + +### 状态语义 + +| `里程碑:` 字段 | `git tag -l` | 含义 | 你(Claude Code)的行为 | +|---|---|---|---| +| `—` | tag 不存在 | 该阶段未开始 / 进行中(未打里程碑) | ✅ 开始 / 继续该阶段开发 | +| `milestone/<id>` | tag 存在 | 阶段**已完成** | 🟢 进入下一未完成模块;全部完成 → 输出完成信息 | + +### 模块完成报告 + +由 `milestone` skill 产出,模板由 milestone skill 持有。CC 不手写模块报告,仅填模板。 + +--- + +## 🏷️ 占位符统一约定 + +项目文档里有 **2 种填写占位** + **1 种提示占位**: + +| 格式 | 谁填 | 使用阶段 | 说明 | +|------|-----|---------|------| +| `【人工填写:<简短说明>】` | 人 | 仅计划阶段文档 | 密钥 / 账密 / 包名 / 命名约定 / 小版本号等人工才能决定的值;编码阶段 plan/spec 禁止出现,查不到真值时用 `AskUserQuestion` 问用户 | +| `TBD(<责任人>)` | CC 自动 | 计划或编码 | 后缀附带责任方(如 `TBD(lite-design 自动补)` / `TBD(lite-build-db 自动补)`);由对应 skill 就地补填 | + +**HTML 注释 `<!-- ... -->`**:提示占位,是**插件内部大纲模板**里给 LLM 的**填空提示 / 章节引导**,指引 LLM 按结构填实际内容。skill 生成时会**剥除**这些注释,最终产物里注释不会保留。 + +--- + +## 📐 编码行为约束 + +### 你必须做的 ✅ + +1. **严格遵循** `docs/04-技术规范.md`——命名 / 编码 / 统一响应 / 异常处理 / 数据访问 / 配置与安全 / 环境配置(含 .env.local 字段说明)等项目专属技术规约全部在此 +2. **每个后端接口** 必须先在 `docs/05-API接口契约.md` 定义,再编码实现 +3. **每个功能可追溯到 `REQ-XXX-NNN`**——commit tag + 代码注释(如 `// REQ-SYS-001: 用户登录`)+ plan/spec 文件名均用此 tag +4. **遇到跨模块改动**(动到非当前模块的代码)——按 § 🟡 软规则 **S2** 执行(允许改,但必须留痕) +5. **遇到技术栈外组件引入**(`docs/04 § 零` 技术栈表外的框架 / 中间件 / 关键库),按 § 🟡 软规则 **S1** 执行(允许引入,但必须先 AskUserQuestion) + +### 你禁止做的 🚫 + +1. **主会话直接 `mysql -e` 跑业务 DDL**(只读查询 / 临时本地调试除外)——业务 schema 必须走 `sql/migrations/V_n__*.sql`,详见下方 Schema 演化规约 +2. **手动 Edit `docs/08 § 二` 的 `里程碑:` 字段**,必须由 `milestone` 自动回写 + +### Schema 演化规约(Flyway migration) + +1. **文件命名**:`sql/migrations/V<n>__<snake_case_desc>.sql`,例:`V5__add_user_email_unique_index.sql` +2. **版本号分配**:建文件前 `ls sql/migrations/V*.sql` 查当前最大 n,新文件 `n_max + 1` +3. **Apply 方式**:Spring Boot 启动 / 测试启动时 Flyway 自动 apply(项目必须在 `pom.xml` 声明 `flyway-core` + `flyway-mysql` 依赖)。`scripts/setup-test-db.sh` 只负责清空库,不做 apply +4. **已合并的 migration 永不修改**:发现错了写一个补救 migration(如 `V7__fix_V5_index_name.sql`),旧 `V_n.sql` 不动 +5. **临时调试 DDL**:临时在本地试字段/索引可手动 `mysql -e`,但不写 migration;下次 `setup-test-db.sh` 会 drop+create 清掉 +6. **计划 ③ 生成的 V1**:`V1__initial_schema.sql` 是计划阶段由 `lite-build-db` 从 `docs/03-数据库设计文档.md`(lite-design 正向设计的 schema SSoT)翻译生成的初始版本;后续 V2/V3/... 由编码阶段每个 REQ 按需写入,**同时**反向同步更新 docs/03 对应表小节以保持 SSoT 一致 + +--- + +## 🗂️ Git 提交规范 + +每次提交必须遵循以下格式: + +``` +<type>(<scope>): <subject> +``` + +- `scope`: 模块名,如 `user` / `inventory` / `order` +- `subject`: 简短描述;业务类(feat / fix / test)必须带 `REQ-XXX-NNN` 后缀 + +`type` 含义: + +| type | 看到它意味着 | +|-----|-------------| +| `feat` | **新能力上线**——用户多了一个功能、接口、页面或业务规则 | +| `fix` | **修 bug**——原来行为错了,这次改对 | +| `refactor` | **重构**——外部行为不变,只改代码结构 / 命名 / 抽象 | +| `docs` | **文档改动**——只动 Markdown / 代码注释,不动实现 | +| `style` | **格式调整**——空白 / 缩进 / import 顺序,逻辑 0 变化 | +| `test` | **只动测试代码**——补用例 / 修 fixture,不碰实现 | +| `chore` | **流程维护**——构建 / 依赖 / 工具 / 证据档案 / 里程碑元数据等非业务动作 | + +--- + +## 🚩 中断机制 + +功能循环(每个功能 REQ-XXX 的 feature-spec → feature-tdd → feature-review)默认 **静默编程**,但触发以下任何一条必须**立刻停下、记录原因、等人决策**,不得自行绕过: + +| # | 中断 | 例子 | +| - | --- | --- | +| 1 | **测试反复失败** | 同一测试同一功能内连续 **10 次**修复失败 | +| 2 | **要改密钥 / 账密 / 包名** | 涉及 .env.local / docs/04 §零环境 中的密钥/账密字段 | +| 3 | **外部接口不可达** | 第三方 API 无法连接、证书失效等环境问题,并无法自行解决 | + +> 其余需要人类判断的场景一律走普通 `AskUserQuestion` Q&A,不中断、不写 Blocker 文件。 + +**触发中断时的固定动作:** + +1. 在当前功能的 spec 文件里追加一节 `## 🚩 Blocker`(报告格式由 `interrupt-check` 的 `interrupt-block-template.md` 持有) +2. 停止后续所有功能的静默执行 +3. 在主会话输出一句话摘要 + 指向 blocker 文件的路径,等人回复 + +--- + +## 🟡 软规则(允许继续,但有强制后续动作) + +以下情况 **不触发中断**,CC 可自行继续推进,但必须在约定位置留痕,模块完成时统一审计。 + +| # | 软规则 | 允许动作 | 强制后续 | +| - | ----- | ------- | ------- | +| S1 | **技术栈外组件引入** | 用 `AskUserQuestion` 给用户三选一:接受引入 / 换方案 / 拒绝 | ① **接受** → 同会话直接在 `docs/04 § 零` 追加一行 → 继续流程 ② **换方案 / 拒绝** → 视为常规歧义澄清,继续 Q&A 收敛 ③ 不写 Blocker、不中断流程 | +| S2 | **跨模块改动** | **默认不改**,仅为当前模块实现所必需时允许修改 | ① hook `log-cross-module.sh` 自动落存根 ② `milestone` 在打里程碑前调用 `interrupt-check` skill 批量补齐「原因 / 影响评估」节 | + +--- + +## 🧭 通用工作准则(General Principles) + +### 1. Think Before Coding + +**Don't assume. Don't hide confusion. Surface tradeoffs.** + +Before implementing: +- State your assumptions explicitly. If uncertain, ask. +- If multiple interpretations exist, present them - don't pick silently. +- If a simpler approach exists, say so. Push back when warranted. +- If something is unclear, stop. Name what's confusing. Ask. + +### 2. Simplicity First + +**Minimum code that solves the problem. Nothing speculative.** + +- No features beyond what was asked. +- No abstractions for single-use code. +- No "flexibility" or "configurability" that wasn't requested. +- No error handling for impossible scenarios. +- If you write 200 lines and it could be 50, rewrite it. + +Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify. + +### 3. Surgical Changes + +**Touch only what you must. Clean up only your own mess.** + +When editing existing code: +- Don't "improve" adjacent code, comments, or formatting. +- Don't refactor things that aren't broken. +- Match existing style, even if you'd do it differently. +- If you notice unrelated dead code, mention it - don't delete it. + +When your changes create orphans: +- Remove imports/variables/functions that YOUR changes made unused. +- Don't remove pre-existing dead code unless asked. + +The test: Every changed line should trace directly to the user's request. + +### 4. Goal-Driven Execution + +**Define success criteria. Loop until verified.** + +Transform tasks into verifiable goals: +- "Add validation" → "Write tests for invalid inputs, then make them pass" +- "Fix the bug" → "Write a test that reproduces it, then make it pass" +- "Refactor X" → "Ensure tests pass before and after" + +For multi-step tasks, state a brief plan: +``` +1. [Step] → verify: [check] +2. [Step] → verify: [check] +3. [Step] → verify: [check] +``` + +Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification. + +--- + +## 🗺️ Skill 索引(erp-workflow-lite,共 11 个) + +### 入口 + +| Skill | 描述 | +|-------|------| +| `plan-start` | 计划阶段入口——扫 docs/08 § 一找第一个未完成计划段(①②③)并派发 | +| `coding-start` | 编码阶段入口——扫 docs/08 § 二找第一个未打里程碑模块并派发 phase-driver | + +### 计划阶段 + +| Skill | 描述 | +|-------|------| +| `lite-init` | 计划 ①——项目初始化 + 范围锁定(模板复制、依赖检查、git init、项目概述+技术栈+需求索引、REQ 卡片生成,停下等人工审阅) | +| `lite-design` | 计划 ②——脚手架 + 数据库设计(docs/04 § 一+、scripts、.env.local、docs/03 DB 设计,停下等人工审阅) | +| `lite-build-db` | 计划 ③——DB 初始化 + 下游文档(V1 migration apply、docs/05 API 契约、docs/08 § 二模块清单,计划阶段结束) | + +### 编码阶段 + +| Skill | 描述 | +|-------|------| +| `phase-driver` | 模块驱动——加载当前模块 REQ 清单,逐个派发 feature 循环 | +| `feature-spec` | 功能规格——为 REQ 生成 spec 文档(API 签名、数据变更、边界) | +| `feature-tdd` | TDD 实现——按 spec 写测试先行,再实现,Agent 子会话跑测试 | +| `feature-review` | AI 代码审查——审查当前 REQ 实现,verdict approve/reject,approve 时勾选进度 | +| `milestone` | 里程碑——内置测试闸门(Agent 子会话),green 则本地 merge + 打 tag,生成模块完成报告 | + +### 守门 + +| Skill | 描述 | +|-------|------| +| `interrupt-check` | 中断检查——触发中断条件时由功能循环 skill 调用,追加 Blocker 节并停止执行 | + +### 文档套件(5 文档) + +| 文档 | 职责 | +|------|------| +| `docs/01-需求清单/` | REQ 卡片目录(模块子目录 + index.md) | +| `docs/03-数据库设计文档.md` | 表/字段/索引/外键 SSoT(lite-design 生成,编码阶段同步更新) | +| `docs/04-技术规范.md` | 技术栈总览(§ 零)+ 架构规范 + 环境变量说明(含 .env.local 密钥字段) | +| `docs/05-API接口契约.md` | 所有后端接口契约(lite-build-db 生成,feature-spec 按需追加) | +| `docs/08-模块任务管理.md` | 全流程进度跟踪(§ 一计划 / § 二编码) | diff --git a/skills/plan/scope-lock/templates/_module-template.md b/skills/plan/lite-init/templates/_module-template.md index 5425b83..5425b83 100644 --- a/skills/plan/scope-lock/templates/_module-template.md +++ b/skills/plan/lite-init/templates/_module-template.md diff --git a/skills/plan/project-init/templates/docs-01-index-template.md b/skills/plan/lite-init/templates/docs-01-index-template.md index 08e326a..08e326a 100644 --- a/skills/plan/project-init/templates/docs-01-index-template.md +++ b/skills/plan/lite-init/templates/docs-01-index-template.md diff --git a/skills/plan/project-init/templates/docs-04-stack-template.md b/skills/plan/lite-init/templates/docs-04-stack-template.md index 234b200..234b200 100644 --- a/skills/plan/project-init/templates/docs-04-stack-template.md +++ b/skills/plan/lite-init/templates/docs-04-stack-template.md diff --git a/skills/plan/lite-init/templates/docs-08-initial-template.md b/skills/plan/lite-init/templates/docs-08-initial-template.md new file mode 100644 index 0000000..4294e88 --- /dev/null +++ b/skills/plan/lite-init/templates/docs-08-initial-template.md @@ -0,0 +1,37 @@ +# 08-工作流进度 + +> 全流程进度跟踪。CC 每完成一项产出就勾选一项。 +> - **§ 一 计划阶段**:`plan-start` 找第一个未勾的计划段(①②③)分发到对应 skill +> - **§ 二 Coding(模块)**:`coding-start` 扫描 docs/08 § 二 的 `里程碑:` 字段 + 本地 `git tag -l 'milestone/<id>'`,找第一个未打里程碑模块分发。本 § 二 行序无语义,仅作模块元数据表 + +## 一、计划阶段进度 + +- [ ] 计划 ① 初始化 + 范围锁定 — lite-init + - [ ] 项目文件骨架已创建(CLAUDE.md + docs/01 index + docs/04 + docs/08) + - [ ] 依赖检查通过(git / mysql) + - [ ] Git 已初始化 + - [ ] 项目概述已填写(CLAUDE.md § 🎯 项目概述) + - [ ] 技术栈已确认(docs/04 § 零) + - [ ] 需求清单索引已填写(docs/01-需求清单/index.md) + - [ ] REQ 卡片骨架已生成(docs/01-需求清单/<module>/REQ-*.md) +- [ ] 计划 ② 脚手架 + 数据库设计 — lite-design + - [ ] 架构文档已生成(docs/04 § 一+ | scripts/*.sh | .env.local | sql/migrations/) + - [ ] docs/03 数据库设计已生成(REQ → 表/字段/索引/外键,回填 REQ 依赖表) +- [ ] 计划 ③ DB 初始化 + 下游文档 — lite-build-db + - [ ] V1 migration 已生成并校验 + apply 到本地 MySQL + - [ ] docs/05 API 契约已生成 + 回填 REQ 依赖接口 + - [ ] docs/08 § 二 模块清单(含 REQ 顺序)已生成 + +## 二、Coding 阶段(模块循环) + +(lite-build-db 填入后,每行一个后端模块。每个模块的 `里程碑:` 字段在 `—` 和 `milestone/<id>` 之间变化,完成由本地 `git tag -l` 判定。`coding-start` 每次扫每模块的里程碑 tag 决定派发。所有模块打里程碑后整体完成。) + +<!-- 模块格式示例(由 lite-build-db 追加;功能子项由 feature-review 在 approve 时勾选): +- module_0 系统管理 + - 依赖: — + - 路径: backend/module/sys/ + - 里程碑: — + - 功能: + - [ ] REQ-SYS-001 用户登录 + - [ ] REQ-SYS-002 用户注册 +--> diff --git a/skills/plan/scope-lock/templates/req-card-template.md b/skills/plan/lite-init/templates/req-card-template.md index bb5a169..bb5a169 100644 --- a/skills/plan/scope-lock/templates/req-card-template.md +++ b/skills/plan/lite-init/templates/req-card-template.md diff --git a/skills/plan/project-init/SKILL.md b/skills/plan/project-init/SKILL.md deleted file mode 100644 index 431dd21..0000000 --- a/skills/plan/project-init/SKILL.md +++ /dev/null @@ -1,89 +0,0 @@ ---- -name: project-init -description: A0 项目初始化——从插件模板幂等地复制 CLAUDE.md / docs/01-需求清单/index.md / docs/04-技术规范.md / docs/08-模块任务管理.md(已存在则跳过),并初始化 Git(如未初始化)。session-start 在 docs/08 缺失时派发本 skill。 -user-invocable: false -allowed-tools: Glob Edit Skill Bash(mkdir *) Bash(cp -n *) Bash(git init) Bash(command -v *) Bash(uname *) Bash(brew *) Bash(apt *) Bash(apt-get *) Bash(yum *) Bash(apk *) Bash(export PATH=*) Bash(echo *) Bash(cat *) ---- - -**所有输出必须使用中文。** - -你负责在项目目录中创建初始文件结构,已存在的文件不覆盖。 - -## 执行步骤 - -### 步骤 0:打印当前位置流程图 - -用 `Bash` 执行 `cat` 命令向用户展示当前位置流程图(stdout 即 ASCII 框图): - -```bash -cat "${CLAUDE_PLUGIN_ROOT}/skills/plan/project-init/banners/flow.txt" -``` - -### A. 幂等复制模板文件 - -用 `Bash` 一次性完成。`cp -n` 表示"不覆盖已存在的文件": - -```bash -mkdir -p docs/01-需求清单 -cp -n "${CLAUDE_SKILL_DIR}/templates/CLAUDE-template.md" CLAUDE.md -cp -n "${CLAUDE_SKILL_DIR}/templates/docs-01-index-template.md" docs/01-需求清单/index.md -cp -n "${CLAUDE_SKILL_DIR}/templates/docs-04-stack-template.md" docs/04-技术规范.md -cp -n "${CLAUDE_SKILL_DIR}/templates/docs-08-initial-template.md" docs/08-模块任务管理.md -``` - -完成后,用 `Edit` 在 `docs/08-模块任务管理.md` 中勾选: -- ` - [ ] 项目文件骨架已创建(CLAUDE.md + docs/01-需求清单/index.md + docs/04-技术规范.md)` - -### B. 依赖检查 + 自动安装(命令行工具) - -对 **git、mysql** 两个工具依次执行以下流程。 - 1. 如果缺失,尝试自动安装。 - 2. 如果检测到不在 PATH,尝试添加进 PATH,并加载。 - -全部通过后打印单行汇总再进入步骤 C: - -``` -[project-init] 依赖检查: git ✓ mysql ✓ -``` - -完成后,用 `Edit` 在 `docs/08-模块任务管理.md` 中勾选: -- ` - [ ] 依赖检查通过` - -### C. 初始化 Git(如尚未初始化) - -用 `Glob` 检查 `.git/` 目录是否存在。 -- 不存在 → 用 `Bash` 执行 `git init`。 -- 已存在 → 跳过。 - -完成后,用 `Edit` 在 `docs/08-模块任务管理.md` 中勾选(A0 子项 + A0 顶层): -- ` - [ ] Git 已初始化` -- `- [ ] A0 项目初始化 — project-init` - -### D. 打印完成横幅并进入 A1 - -向用户输出: - -``` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ - [project-init] 项目初始化完成 - - 已创建: - ✓ CLAUDE.md(从插件模板复制) - ✓ docs/01-需求清单/index.md(待人工填写模块索引) - ✓ docs/04-技术规范.md(默认技术栈,A1 让用户确认) - ✓ docs/08-模块任务管理.md(全流程进度跟踪) - 已勾选:A0 项目初始化 - - 下一步:A1 scope-lock(填写项目概述 + 技术栈 + 需求索引 + REQ 卡片) -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -``` - -立即调用 `Skill(scope-lock)` 进入 A1,不等用户手动输入。 - -## 参考 - -- `${CLAUDE_SKILL_DIR}/templates/CLAUDE-template.md`(项目级 CLAUDE.md 模板) -- `${CLAUDE_SKILL_DIR}/templates/docs-01-index-template.md`(需求索引初稿) -- `${CLAUDE_SKILL_DIR}/templates/docs-04-stack-template.md`(默认技术栈) -- `${CLAUDE_SKILL_DIR}/templates/docs-08-initial-template.md`(A 阶段进度初始化) -- 下游:`scope-lock`(A1,自动派发) diff --git a/skills/plan/project-init/banners/flow.txt b/skills/plan/project-init/banners/flow.txt deleted file mode 100644 index fd2e547..0000000 --- a/skills/plan/project-init/banners/flow.txt +++ /dev/null @@ -1,17 +0,0 @@ -┌────────────────────────────────────────────────────────┐ -│ 📋 阶段 A:规划(一次性) │ -│ │ -│ ▶ A0 初始化项目 │ -│ ↓ │ -│ A1 锁范围(生成 REQ 卡片) → 人工审核 │ -│ ↓ │ -│ A2 生成骨架 │ -│ ↓ │ -│ A3 生成 DB 设计 → 人工审核 │ -│ ↓ │ -│ A4 初始化 DB │ -│ ↓ │ -│ A5 生成下游文档 │ -│ │ -│ 规划阶段到此结束 │ -└────────────────────────────────────────────────────────┘ diff --git a/skills/plan/project-init/templates/CLAUDE-template.md b/skills/plan/project-init/templates/CLAUDE-template.md deleted file mode 100644 index a048f68..0000000 --- a/skills/plan/project-init/templates/CLAUDE-template.md +++ /dev/null @@ -1,260 +0,0 @@ -# CLAUDE.md — ERP项目 Claude Code 主指令文件 - -> 本文件是 Claude Code 的"操作手册"。Claude Code 启动时会自动读取此文件。 - ---- - -## 🎯 项目概述 - -- **项目名称**: 【人工填写:公司 + 项目名,例如"XX 公司 ERP 管理系统"】 -- **项目简述**: 【人工填写:一句话描述项目目标,例如"面向中小制造企业的全流程 ERP,涵盖采购/库存/生产/销售/财务"】 -- **目标用户**: 【人工填写:谁会用,例如"企业内部管理人员(采购员、仓管员、生产主管、销售员、财务人员、管理层)"】 -- **部署方式**: 【人工填写:私有化部署 / 云部署 / Docker 容器化 等】 - ---- - -## 🔄 B 阶段开发流程(后端模块循环 → 前端整体阶段) - -B 阶段分两段,**全部固化到 skills**。入口:`/erp-workflow:coding-start`。 - -### 阶段路由(coding-start 内,只做分发) - -`coding-start` 每次入口做两段完成性检查后真值表派发: - -- 后端完成性检查 → `backend_done`(扫 docs/08 § 二 里程碑字段 + `git tag -l`) -- 前端完成性检查 → `frontend_done`(扫 docs/08 § 三 整体里程碑 + `git tag -l`) - -| `backend_done` | `frontend_done` | 派发 | -|---|---|---| -| `false` | 任意 | `module-start`(写后端) | -| `true` | `false` | `frontend-start`(写前端) | -| `true` | `true` | "所有阶段已完成" | - -前端阶段前置(prototype/ 门禁)由 `frontend-start` 自带,不在 coding-start。`module-start` 与 `frontend-start` **互不感知对方**。 - -### 后端阶段(每模块一个里程碑 tag) - -- **模块循环(外)**:`module-start` → `test-gate(phase=backend)` → `module-report` → `milestone-tag`(本地 merge 进默认分支 + 打 `milestone/<id>` tag)→ 自动回调 coding-start 路由下一阶段(无人工介入) -- **功能循环(内,每 REQ-XXX-NNN 一遍)**:`feature-brainstorm` → `feature-plan` → `feature-tdd` → `feature-verify` → `feature-review` -- 后端阶段任务严格落在 `backend/` 路径下;docs/01 REQ 卡片的 UI 描述在此阶段忽略,UI 推迟到前端阶段。 - -### 前端阶段(整体一个里程碑 tag,所有后端模块打里程碑后启动) - -- **FE 清单(AI 自主推导,无审阅断点)**:`frontend-start` 进入时扫 prototype + docs/01 + docs/05 → AI 自主推导 FE 业务功能清单写入 `docs/08 § 三`(已有则加载)。**FE 是业务功能粒度,与 prototype HTML 文件数无关**——一个 HTML 可拆多个 FE,多个 HTML 也可合成一个 FE。FE 清单的合理性由 fe-feature-review / milestone-tag 在整体里程碑标记时一并校核(全程无人工介入)。 -- **FE 循环(外)**:`frontend-start` → fe-feature 循环 → `test-gate(phase=frontend)` → `module-report(phase=frontend)` → `milestone-tag`(分支 `frontend-phase`,docs/08 § 三 整体里程碑)。 -- **FE 功能循环(内,每个 FE-NN 一遍)**:`fe-feature-brainstorm` → `fe-feature-plan` → `fe-feature-tdd` → `fe-feature-verify` → `fe-feature-review`(专用 `fe-code-reviewer` agent,硬编码 7 维 review checklist) -- 前端阶段任务严格落在 `frontend/` 路径下;布局以 `prototype/` 为权威。 - -### 里程碑前测试闸门 - -- `test-gate`:后端阶段子会话跑 `scripts/test.sh`(含本模块新增 + 已合并模块回归);前端阶段子会话跑 vitest + playwright。 -- `test-gate` 是打里程碑 tag 前唯一的硬测试门;红色不得跳过进入 `module-report` / `milestone-tag`。 - ---- - -## ✅ 阶段完成判定规则 - -`docs/08-模块任务管理.md` 分两段: -- `§ 二`:后端模块元数据表(每个模块一行 bullet,记录依赖 / 路径 / 里程碑 tag / 功能子项) -- `§ 三`:前端阶段元数据(整体里程碑 + FE 子项清单,由 `frontend-start` 在所有后端模块打里程碑后填入) - -**阶段完成判定**统一以 `里程碑:` 字段(§ 二 各模块) / `整体里程碑:` 字段(§ 三)+ 本地 `git tag -l 'milestone/<id>'` 判定;子项勾选只作可视化进度,不参与完成判定。 - -### 后端模块格式 - -每个后端模块在 docs/08 § 二 中长这样: - -```markdown -- module_0 系统管理 - - 依赖: — - - 路径: backend/module/sys/ - - 里程碑: — - - 功能: - - [ ] REQ-SYS-001 用户登录 - - [ ] REQ-SYS-002 用户注册 -``` - -- `里程碑:` 字段由 `milestone-tag` 在打里程碑 tag 时从 `—` 改为 `milestone/<module_id>`。 -- 每个 `REQ-*` 子项由 `feature-review` 在 `verdict=approve` 时自动勾选为 `[x]`。 -- 路径限定为后端目录(如 `backend/module/sys/`);前端代码不在此阶段产生。 - -### 前端阶段格式(§ 三) - -```markdown -- 整体里程碑: — -- 功能: - - [ ] FE-01 用户登录与注册 | 关联 REQ:REQ-SYS-001, REQ-SYS-002 | 关联原型:prototype/auth.html - - [ ] FE-02 仪表盘总览 | 关联 REQ:REQ-DASH-001 | 关联原型:prototype/dashboard.html -``` - -- `整体里程碑:` 字段由 `milestone-tag` 在打前端里程碑 tag 时从 `—` 改为 `milestone/frontend-phase`。 -- "功能:" 列表由 `frontend-start` 进入时由 AI 自主推导写入(无人工审阅断点)。FE 是业务功能粒度,与 prototype HTML 文件数无关;合理性由 fe-feature-review / 整体里程碑标记时统一校核。 -- 每个 `FE-NN` 子项由 `fe-feature-review` 在 `verdict=approve` 时自动勾选为 `[x]`。 -- 进入前端阶段前 `frontend-start` 步骤 1 自带 prototype/ 门禁,强制检查项目根 `prototype/` 至少含 1 个 `*.html` mockup。 - -### 状态语义(后端模块 + 前端阶段共用) - -| `里程碑:` 字段 | `git tag -l` | 含义 | 你(Claude Code)的行为 | -|---|---|---|---| -| `—` | tag 不存在 | 该阶段未开始 / 进行中(未打里程碑) | ✅ 开始 / 继续该阶段开发 | -| `milestone/<id>` | tag 存在 | 阶段**已完成** | 🟢 后端:进入下一未完成模块;后端全完 → 前端阶段;前端已打里程碑 → 全部完成 | - -### 模块完成报告 - -由 `module-report` skill 产出,模板位于 由 module-report skill 持有(12 节标准化,含跨模块改动等 CLAUDE.md 软规则映射节)。CC 不手写模块报告,仅填模板。 - ---- - -## 🏷️ 占位符统一约定 - -项目文档里有 **2 种填写占位** + **1 种提示占位**: - -| 格式 | 谁填 | 使用阶段 | 说明 | -|------|-----|---------|------| -| `【人工填写:<简短说明>】` | 人 | 仅 A 阶段文档 | 密钥 / 账密 / 包名 / 命名约定 / 小版本号等人工才能决定的值;B 阶段 plan/spec 禁止出现,查不到真值时用 `AskUserQuestion` 问用户 | -| `TBD(<责任人>)` | CC 自动 | A 或 B | 后缀附带责任方(如 `TBD(A3 自动补)` / `TBD(A5 自动补)`);由对应 skill 就地补填,`module-report` § ⑦ 检查 `TBD(CC 补)` 残留 | - -**HTML 注释 `<!-- ... -->`**:提示占位,是**插件内部大纲模板**里给 LLM 的**填空提示 / 章节引导**,指引 LLM 按结构填实际内容。skill 生成时会**剥除**这些注释,最终产物里注释不会保留。 - ---- - -## 📐 编码行为约束 - -### 你必须做的 ✅ - -1. **严格遵循** `docs/04-技术规范.md`——命名 / 编码 / 统一响应 / 异常处理 / 数据访问 / 配置与安全 等项目专属技术规约全部在此 -2. **严格遵循** `docs/09-项目目录结构.md`——文件放对位置 -3. **每个后端接口** 必须先在 `docs/05-API接口契约.md` 定义,再编码实现 -4. **每个功能可追溯到 `REQ-XXX-NNN`**——commit tag + 代码注释(如 `// REQ-SYS-001: 用户登录`)+ plan/spec 文件名均用此 tag -5. **遇到跨模块改动**(动到非当前模块的代码)——按 § 🟡 软规则 **S2** 执行(允许改,但必须留痕) -6. **遇到技术栈外组件引入**(`docs/04 § 零` 技术栈表外的框架 / 中间件 / 关键库),按 § 🟡 软规则 **S1** 执行(允许引入,但必须先 AskUserQuestion) - -### 你禁止做的 🚫 - -1. **主会话直接 `mysql -e` 跑业务 DDL**(只读查询 / 临时本地调试除外)——业务 schema 必须走 `sql/migrations/V_n__*.sql`,详见下方 Schema 演化规约 -2. **手动 Edit `docs/08 § 二/§ 三` 的 `里程碑:` / `整体里程碑:` 字段**,必须要由 `milestone-tag` 自动回写 - -### Schema 演化规约(Flyway migration) - -1. **文件命名**:`sql/migrations/V<n>__<snake_case_desc>.sql`,例:`V5__add_user_email_unique_index.sql` -2. **版本号分配**:建文件前 `ls sql/migrations/V*.sql` 查当前最大 n,新文件 `n_max + 1` -3. **Apply 方式**:Spring Boot 启动 / 测试启动时 Flyway 自动 apply(项目必须在 `pom.xml` 声明 `flyway-core` + `flyway-mysql` 依赖)。`scripts/setup-test-db.sh` 只负责清空库,不做 apply -4. **已合并的 migration 永不修改**:发现错了写一个补救 migration(如 `V7__fix_V5_index_name.sql`),旧 `V_n.sql` -5. **临时调试 DDL**:临时在本地试字段/索引可手动 `mysql -e`,但不写 migration;下次 `setup-test-db.sh` 会 drop+create 清掉 -6. **A4 生成的 V1**:`V1__initial_schema.sql` 是 A 阶段由 `db-init` 从 `docs/03-数据库设计文档.md`(A3 正向设计的 schema SSoT)翻译生成的初始版本;后续 V2/V3/... 由 B 阶段每个 REQ 按需写入,**同时**反向同步更新 docs/03 对应表小节以保持 SSoT 一致 - ---- - -## 🗂️ Git 提交规范 - -每次提交必须遵循以下格式: - -``` -<type>(<scope>): <subject> -``` - -- `scope`: 模块名,如 `user` / `inventory` / `order` -- `subject`: 简短描述;业务类(feat / fix / test)必须带 `REQ-XXX-NNN` 后缀 - -`type` 含义: - -| type | 看到它意味着 | -|-----|-------------| -| `feat` | **新能力上线**——用户多了一个功能、接口、页面或业务规则 | -| `fix` | **修 bug**——原来行为错了,这次改对 | -| `refactor` | **重构**——外部行为不变,只改代码结构 / 命名 / 抽象 | -| `docs` | **文档改动**——只动 Markdown / 代码注释,不动实现 | -| `style` | **格式调整**——空白 / 缩进 / import 顺序,逻辑 0 变化 | -| `test` | **只动测试代码**——补用例 / 修 fixture,不碰实现 | -| `chore` | **流程维护**——构建 / 依赖 / 工具 / 证据档案 / 里程碑元数据等非业务动作 | - ---- - -## 🚩 中断机制 - -功能循环(每个功能 REQ-XXX 的 Brainstorm → Plan → TDD → Verify → AI 自审)默认 **静默编程**,但触发以下任何一条必须**立刻停下、记录原因、等人决策**,不得自行绕过: - -| # | 中断 | 例子 | -| - | --- | --- | -| 1 | **测试反复失败** | 同一测试同一功能内连续 **10 次**修复失败 | -| 2 | **要改密钥 / 账密 / 包名** | `docs/07-环境配置.md` 里由人工标注必须填的字段 | -| 3 | **外部接口不可达** | 第三方 API 无法连接、证书失效等环境问题,并无法自行解决 | - -> 其余需要人类判断的场景一律走普通 `AskUserQuestion` Q&A,不中断、不写 Blocker 文件。 - -**触发中断时的固定动作:** - -1. 在当前功能的 plan 文件里追加一节 `## 🚩 Blocker`(报告格式由 `interrupt-check` 的 `interrupt-block-template.md` 持有) -2. 停止后续所有功能的静默执行 -3. 在主会话输出一句话摘要 + 指向 blocker 文件的路径,等人回复 - ---- - -## 🟡 软规则(允许继续,但有强制后续动作) - -以下情况 **不触发中断**,CC 可自行继续推进,但必须在约定位置留痕,模块完成时统一审计。 - -| # | 软规则 | 允许动作 | 强制后续 | -| - | ----- | ------- | ------- | -| S1 | **技术栈外组件引入** | 用 `AskUserQuestion` 给用户三选一:接受引入 / 换方案 / 拒绝 | ① **接受** → 同会话直接在 `docs/04 § 零` 追加一行 → 继续流程 ② **换方案 / 拒绝** → 视为常规歧义澄清,继续 Q&A 收敛 ③ 不写 Blocker、不中断流程 | -| S2 | **跨模块改动** | **默认不改**,仅为当前模块实现所必需时允许修改 | ① hook `log-cross-module.sh` 自动落存根 ② `module-report` 一次性调用 `cross-module-log` skill 批量补齐「原因 / 影响评估」+ 「跨模块改动」节完整贴入《模块完成报告》 | - ---- - -## 🧭 通用工作准则(General Principles) - -### 1. Think Before Coding - -**Don't assume. Don't hide confusion. Surface tradeoffs.** - -Before implementing: -- State your assumptions explicitly. If uncertain, ask. -- If multiple interpretations exist, present them - don't pick silently. -- If a simpler approach exists, say so. Push back when warranted. -- If something is unclear, stop. Name what's confusing. Ask. - -### 2. Simplicity First - -**Minimum code that solves the problem. Nothing speculative.** - -- No features beyond what was asked. -- No abstractions for single-use code. -- No "flexibility" or "configurability" that wasn't requested. -- No error handling for impossible scenarios. -- If you write 200 lines and it could be 50, rewrite it. - -Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify. - -### 3. Surgical Changes - -**Touch only what you must. Clean up only your own mess.** - -When editing existing code: -- Don't "improve" adjacent code, comments, or formatting. -- Don't refactor things that aren't broken. -- Match existing style, even if you'd do it differently. -- If you notice unrelated dead code, mention it - don't delete it. - -When your changes create orphans: -- Remove imports/variables/functions that YOUR changes made unused. -- Don't remove pre-existing dead code unless asked. - -The test: Every changed line should trace directly to the user's request. - -### 4. Goal-Driven Execution - -**Define success criteria. Loop until verified.** - -Transform tasks into verifiable goals: -- "Add validation" → "Write tests for invalid inputs, then make them pass" -- "Fix the bug" → "Write a test that reproduces it, then make it pass" -- "Refactor X" → "Ensure tests pass before and after" - -For multi-step tasks, state a brief plan: -``` -1. [Step] → verify: [check] -2. [Step] → verify: [check] -3. [Step] → verify: [check] -``` - -Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification. diff --git a/skills/plan/project-init/templates/docs-08-initial-template.md b/skills/plan/project-init/templates/docs-08-initial-template.md deleted file mode 100644 index 092902c..0000000 --- a/skills/plan/project-init/templates/docs-08-initial-template.md +++ /dev/null @@ -1,70 +0,0 @@ -# 08-工作流进度 - -> 全流程进度跟踪。CC 每完成一项产出就勾选一项。 -> - **§ 一 Plan(A0~A5)**:`plan-start` 找第一个未勾 A 子项分发到对应 skill -> - **§ 二 Coding(模块)**:分发以 `docs/02-开发计划.md § 二 开发顺序清单` 为准;`coding-start` 按 docs/02 顺序扫描,对每个 REQ 所属模块查询本 § 二的 `里程碑:` 字段 + 本地 `git tag -l 'milestone/<id>'`,找第一个未打里程碑模块分发。本 § 二 行序无语义,仅作模块元数据表 - -## 一、Plan 阶段(一次性) - -- [ ] A0 项目初始化 — project-init - - [ ] 依赖检查通过 - - [ ] 项目文件骨架已创建(CLAUDE.md + docs/01-需求清单/index.md + docs/04-技术规范.md) - - [ ] Git 已初始化 - -- [ ] A1 范围锁定 — scope-lock - - [ ] 项目概述已填写(CLAUDE.md § 🎯 项目概述) - - [ ] 技术栈已确认(docs/04 § 零) - - [ ] 需求清单索引已填写(docs/01-需求清单/index.md) - - [ ] REQ 卡片骨架已生成(docs/01-需求清单/<module>/REQ-*.md,业务内容留待人工填写) - -- [ ] A2 骨架生成 — skeleton-gen - - [ ] 架构文档已生成(docs/04 § 一+、docs/06、docs/07、docs/09) - - [ ] 工具脚本已生成(scripts/*.sh、.env.local) - - [ ] .gitignore 已配置 - -- [ ] A3 DB 设计 + REQ 回填 — db-design-gen - - [ ] docs/03-数据库设计文档.md 已生成 - - [ ] docs/01 各 REQ 卡片"依赖表" + 模块头"涉及表" 已回填 - -- [ ] A4 DB 初始化 — db-init - - [ ] sql/migrations/V1__initial_schema.sql 已生成 - - [ ] DDL 与 docs/03 全量一致 - - [ ] .env.local 凭据已验证(mysql -e "SELECT 1" OK) - - [ ] setup-test-db.sh 防护通过 + DROP+CREATE + apply V1 已执行 - - [ ] SHOW TABLES 行数 == docs/03 表数量 - -- [ ] A5 下游文档生成 — downstream-gen - - [ ] docs/02 开发计划已生成 - - [ ] docs/05 API 契约已生成 - - [ ] docs/06 § 三 页面清单已填入 - - [ ] docs/10 验收清单已生成 - - [ ] 下方模块列表已填入 - - [ ] REQ 卡片依赖接口已回填 - -## 二、Coding 阶段(后端模块循环) - -(A5 填入后,每行一个后端模块。每个模块的 `里程碑:` 字段在 `—` 和 `milestone/<id>` 之间变化,完成由本地 `git tag -l` 判定。`coding-start` 每次按 docs/02 REQ 序扫每模块的里程碑 tag 决定派发。后端模块全部打里程碑后自动进入 § 三 前端阶段。) - -<!-- 模块格式示例(由 A5 downstream-gen 追加;功能子项由 feature-review 在 approve 时勾选): -- module_0 系统管理 - - 依赖: — - - 路径: backend/module/sys/ - - 里程碑: — - - 功能: - - [ ] REQ-SYS-001 用户登录 - - [ ] REQ-SYS-002 用户注册 ---> - -## 三、Coding 阶段(前端整体) - -(`frontend-start` 进入时扫 prototype/ + docs/01 + docs/05 → AI 自主推导 FE 业务功能清单写到下方"功能:"项(无人工审阅断点;合理性由整体里程碑标记时统一校核)。已有清单则直接加载。整个前端阶段 1 个里程碑 tag,分支 `frontend-phase`。) - -- 整体里程碑: — -- 功能: - <!-- AI 进入时按以下行格式写入(每行 1 个 FE,可关联多个 REQ / 多份原型): - - [ ] FE-NN 功能名 | 关联 REQ:REQ-A, REQ-B | 关联原型:prototype/<file>.html, prototype/<other>.html - - 示例: - - [ ] FE-01 用户登录与注册 | 关联 REQ:REQ-SYS-001, REQ-SYS-002 | 关联原型:prototype/auth.html - - [ ] FE-02 仪表盘总览 | 关联 REQ:REQ-DASH-001 | 关联原型:prototype/dashboard.html - --> diff --git a/skills/plan/scope-lock/SKILL.md b/skills/plan/scope-lock/SKILL.md deleted file mode 100644 index 2e39871..0000000 --- a/skills/plan/scope-lock/SKILL.md +++ /dev/null @@ -1,162 +0,0 @@ ---- -name: scope-lock -description: A1 计划范围锁定——引导用户填写项目概述 + 技术栈 + 需求索引,并按模块子目录生成 REQ 卡片骨架(CC 推断 req_id/title/goal/rules/constraints/acceptance;输入/输出 各含一句简述 + N 张示例字段表全部原样复制由人工编辑;依赖表/依赖接口模板写死 `TBD(A3/A5 自动补)` 由后续 skill 回填)。 -user-invocable: false -allowed-tools: Read Edit Grep Skill AskUserQuestion Bash(mkdir *) Bash(cp *) Bash(sed *) Bash(bash *) Bash(cat *) ---- - -**所有输出必须使用中文。** - -# scope-lock - -## 执行步骤 - -### 步骤 0:打印当前位置流程图 - -用 `Bash` 执行 `cat` 命令向用户展示当前位置流程图(stdout 即 ASCII 框图): - -```bash -cat "${CLAUDE_PLUGIN_ROOT}/skills/plan/scope-lock/banners/flow.txt" -``` - -### A. 提示用户填写项目概述并等待 - -向用户输出: - -``` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ - [scope-lock] 请填写项目概述 - - 📄 文件位置: ./CLAUDE.md - 📌 编辑位置: § 🎯 项目概述 - - 请将以下占位符替换为实际值: - - 项目名称 - - 项目简述 - - 目标用户 - - 部署方式 - 改完后回来选择「继续」。 -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -``` - -用 `AskUserQuestion` 询问: -- **question**: `项目概述填写完毕了吗?` - - 用户选择「继续」→ 用 `Grep` 在 `CLAUDE.md` 搜索 `【人工填写:`(限定 § 🎯 项目概述 节)。命中 → 打印残留行 + 路径,重新弹出同样的 AskUserQuestion;0 命中 → 勾选并进入步骤 B。 - - 用户选择「有疑问想先沟通」→ 回答用户问题后,再次弹出同样的 QA。 - -0 命中后,用 `Edit` 在 `docs/08-模块任务管理.md` 中勾选: -- ` - [ ] 项目概述已填写(CLAUDE.md § 🎯 项目概述)` - -### B. 提示用户检查默认技术栈并等待 - -`docs/04-技术规范.md` 已由 A0 `project-init` 用模板复制(默认技术栈,见 `project-init/templates/docs-04-stack-template.md`)。本步骤让用户检查 / 调整 § 零。 - -向用户输出: - -``` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ - [scope-lock] 技术栈已保存 - - 📄 文件位置: ./docs/04-技术规范.md(由 A0 模板生成) - 📌 编辑位置: § 零、技术栈总览 - - 请检查技术栈表: - - 不需要的行直接删除(如纯后端项目删前端行) - - 需要替换的技术直接改 - - 需要新增的条目直接加行 - 改完后回来选择「继续」。 -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -``` - -用 `AskUserQuestion` 询问: -- **question**: `技术栈检查完毕了吗?` - - 用户选择「继续」→ 进入步骤 C。 - - 用户选择「有疑问想先沟通」→ 回答用户问题后,再次弹出同样的 QA。 - -完成后,用 `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` 询问: -- **question**: `需求清单模块索引填写完毕了吗?` - - 用户选择「继续」→ 进入步骤 D。 - - 用户选择「有疑问想先沟通」→ 回答用户问题后,再次弹出同样的 QA。 - -完成后,用 `Edit` 在 `docs/08-模块任务管理.md` 中勾选: -- ` - [ ] 需求清单索引已填写(docs/01-需求清单/index.md)` - -### D. 生成 REQ 卡片骨架并停下等人工审阅 - -1. 用 `Grep` 校验 `docs/01-需求清单/index.md` 无 `【人工填写:` 残留;有则回步骤 C。 -2. 用 `Read` 读 `index.md` 解析模块索引。 -3. **单次 Bash 写入所有文件**(替代 N×9 次 Edit): - - - **每模块推断**:三元组 `{module_code, module_name, module_brief}` + N 个 REQ 的六元组 `{req_id, title, goal, rules, constraints, acceptance}`。`req_id`/`title` 从核心功能点拆分;`goal` 展开 `title`;`rules`/`constraints`/`acceptance` 起草业务语义。**不推断**输入 / 输出(模板原样保留示例)。 - - **单次 Bash**:调 `${CLAUDE_SKILL_DIR}/scripts/render.sh` 落盘所有文件(脚本内部完成模板读取 + 占位符替换 + HTML 注释剥离)。下面是**调用形态**示例,`<MOD>` / `<模块名>` / `<REQ-MOD-NNN>` 等尖括号位置 CC 按 `index.md` 实际值替换: - - ```bash - R="${CLAUDE_SKILL_DIR}/scripts/render.sh" - # 每个模块:mkdir + 1 个 render module + N 个 render req(每 REQ 一行) - mkdir -p "docs/01-需求清单/<MOD>-<模块名>" - bash "$R" module "docs/01-需求清单/<MOD>-<模块名>/_module.md" "<MOD>" "<模块名>" "<module_brief>" - bash "$R" req "docs/01-需求清单/<MOD>-<模块名>/<REQ-MOD-NNN>.md" "<REQ-MOD-NNN>" "<title>" "<goal>" "<rules>" "<constraints>" "<acceptance>" - ``` - - - **兜底**:值含字面 `$xxx` 或 `}}` 的 REQ 单独走 cp + Edit。 -4. 用 `Edit` 在 `docs/08-模块任务管理.md` 勾选(A1 子项 + A1 顶层): - - ` - [ ] REQ 卡片骨架已生成(docs/01-需求清单/<module>/REQ-*.md,业务内容留待人工填写)` - - `- [ ] A1 范围锁定 — scope-lock` -5. 打印停下横幅并**停止**: - -``` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ - [scope-lock] ✅ A1 范围锁定完成 - - 产出: - ✓ CLAUDE.md § 🎯 项目概述 - ✓ docs/04 § 零 技术栈 - ✓ docs/01-需求清单/index.md 模块索引 - ✓ docs/01-需求清单/<module>/_module.md 模块头 - ✓ docs/01-需求清单/<module>/REQ-*.md REQ 卡片骨架 - - ⏸ 现在请你逐张打开 REQ 卡片: - - **必改**:输入 / 输出 两段 - · `表1` / `表2` 是模板示例,按本 REQ 业务**改字段 / 增删行 / 增删整张表** - - **审阅**:目标 / 跨字段规则 / 边界 / 验收(已起草,对照业务校正) - - **保留**:`TBD` 不要改,由之后流程自动回填 - - 审阅完成后,运行以下命令继续进入 A2: - /erp-workflow:plan-start - -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -``` - -## 参考 - -- `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 字段) -- `${CLAUDE_SKILL_DIR}/templates/req-card-template.md` -- `${CLAUDE_SKILL_DIR}/templates/_module-template.md` -- `${CLAUDE_SKILL_DIR}/scripts/render.sh`(步骤 D 渲染助手,dispatch `module` / `req` 两种模式) diff --git a/skills/plan/scope-lock/banners/flow.txt b/skills/plan/scope-lock/banners/flow.txt deleted file mode 100644 index e012667..0000000 --- a/skills/plan/scope-lock/banners/flow.txt +++ /dev/null @@ -1,17 +0,0 @@ -┌────────────────────────────────────────────────────────┐ -│ 📋 阶段 A:规划(一次性) │ -│ │ -│ A0 初始化项目 │ -│ ↓ │ -│ ▶ A1 锁范围(生成 REQ 卡片) → 人工审核 │ -│ ↓ │ -│ A2 生成骨架 │ -│ ↓ │ -│ A3 生成 DB 设计 → 人工审核 │ -│ ↓ │ -│ A4 初始化 DB │ -│ ↓ │ -│ A5 生成下游文档 │ -│ │ -│ 规划阶段到此结束 │ -└────────────────────────────────────────────────────────┘