朱子纯 / erp-workflow-plugin

README.md 14.7 KB

erp-workflow

Claude Code 插件：ERP / 后端管理系统全流程开发框架。

把"从零到 N 个后端模块上线 + 前端整体阶段"的整个流程固化成 11 个 skill + 2 个 agent + 22 份模板 + 3 个脚本，让 CC 在 schema 演化用 Flyway migration、需求可追溯、纯本地 git 的前提下推进编码。后端按模块循环依次打里程碑 tag，所有后端模块打里程碑后进入前端整体阶段（以项目根 prototype/ 静态 HTML mockup 为页面权威）。两阶段共用同一套功能循环 skill，由 phase 参数区分。

这个插件做什么

┌────────────────────────────────────────────────────────┐
│  erp-workflow                                            │
│                                                          │
│  计划（/plan-start，一次性，2 个审阅断点）               │
│    ① init      初始化 + REQ 卡片      ⏸ 审阅 REQ         │
│    ② design    脚手架 + docs/03       ⏸ 审阅 schema      │
│    ③ build-db  V1+apply + docs/05/08                     │
│                                                          │
│  编码（/coding-start，统一功能循环）                     │
│    后端模块循环  ┐                                       │
│    前端整体阶段  ┘→ phase-driver                         │
│        feature-spec → feature-tdd → feature-review       │
│        全 approve → milestone（test→报告→merge+tag）     │
└────────────────────────────────────────────────────────┘

首次使用

  1. 进入空项目目录并启动 Claude Code：

    mkdir my-erp && cd my-erp
claude --plugin-dir /path/to/erp-workflow-plugin

  2. Plan 阶段入口（一次性规划）：

    /erp-workflow:plan-start

    Plan 阶段三段式执行，中间有两个人工审阅断点：

  • 第一段（首次运行）：执行 init（依赖检查 / git init / 初始化 docs + CLAUDE.md / 引导填技术栈 + 需求索引 / 生成 REQ 卡片骨架）后停下，等你审阅并补全 docs/01-需求清单/<module>/REQ-*.md（第一个人工关口：业务范围）
  • 第二段（REQ 审阅完重新运行）：执行 design（生成 docs/04 架构规范 / scripts / .env.local / 从 REQ 正向设计 docs/03-数据库设计文档.md）后再次停下，等你审阅 docs/03 的表 / 字段 / 索引 / 外键（第二个人工关口：database schema）
  • 第三段（docs/03 审阅完重新运行）：执行 build-db（解析 docs/03 → 生成 V1 migration → DROP+CREATE 本地 schema 并 apply → 生成 docs/05 API 契约 + 追加 docs/08 § 二 模块清单），Plan 完成后停下

每次运行都会自动接上次停下的地方继续。Plan 完成后不会自动进入编码，需要你手动运行 /erp-workflow:coding-start。

  1. Coding 阶段入口（后端模块循环 → 前端整体阶段）： /erp-workflow:coding-start Plan 全部完成后由你显式触发。coding-start 是阶段分发权威——每次入口都重新扫描 docs/08 § 二/§ 三 里程碑字段 + 本地 git tag，按当前进度决定派发：

路由规则（coding-start 真值表，只做分发）：

| backend_done | frontend_done | coding-start 派发 | |---|---|---| | false | 任意 | phase-driver(phase=backend)（写后端） | | true | false | phase-driver(phase=frontend)（写前端） | | true | true | 打印"所有阶段已完成"，停下 |

docs/08 里程碑字段与 git tag -l 不一致 → 停下报错（绝不静默假设完成状态）。

后端阶段（phase-driver phase=backend）：

  • 切到 module-<id> 分支，对每个未完成 REQ：feature-spec → feature-tdd → feature-review
  • 全 approve → milestone（内置测试闸门 + 完成报告 + 本地 merge + 打 milestone/<id> tag）→ 自动回 coding-start 再次路由

前端阶段（phase-driver phase=frontend，自带前置门禁）：

  • prototype/ 门禁（≥ 1 个 *.html，缺失则 AskUserQuestion 提示用户补齐 → 停下）
  • 准备 FE 清单（无审阅断点）：§ 三 占位则 AI 扫 prototype + docs/01 + docs/05 推导写入；§ 三 已有则加载
  • 切 frontend-phase 分支，对每个未完成 FE：feature-spec → feature-tdd → feature-review（fe-code-reviewer agent 做 7 维 review）
  • 全 approve → milestone（内置测试闸门 vitest + Playwright + 完成报告 + merge + tag）→ 自动回 coding-start → 全部完成
  1. 中途恢复：任何时候运行对应入口命令——根据 Plan § 一 checkbox、§ 二 各后端模块里程碑 tag、§ 三 前端整体里程碑 tag 跳到当前该做的事。

目录结构

erp-workflow-plugin/
├── .claude-plugin/
│   └── plugin.json                  # 插件清单，声明 skills 三个子目录
├── README.md                        # 本文档
├── agents/
│   ├── superpower-code-reviewer.md  # 后端 code-reviewer agent（feature-review 后端阶段调用）
│   └── fe-code-reviewer.md          # 前端专用 reviewer（feature-review 前端阶段调用，7 维 review）
└── skills/
    ├── plan/                        # 计划阶段：3 个一次性规划 skill
    │   ├── init/
    │   ├── design/
    │   └── build-db/
    ├── coding/                      # 编码阶段：5 个 skill（两阶段共用统一功能循环）
    │   ├── phase-driver/
    │   ├── feature-spec/
    │   ├── feature-tdd/
    │   ├── feature-review/
    │   └── milestone/
    └── crosscut/                    # 横切：3 个 skill（2 个入口 + 1 个中断守门）
        ├── plan-start/
        ├── coding-start/
        └── interrupt-check/

Hook 清单

本插件无 Hook——跨模块改动留痕已移除。跨模块改动须在 milestone 完成报告的「偏离与取舍」节人工记录。

Skill 清单（11 个）

入口（skills/crosscut/）

Skill 作用 流程中谁调用
plan-start A 阶段入口。读取 docs/08 § 一找第一个未勾计划段（①②③）→ 派发对应 plan skill；全部完成时提示运行 coding-start 用户手动运行 /erp-workflow:plan-start
coding-start B 阶段入口 + 阶段分发器（只做分发）。① 校验 Plan 已完成（docs/08 § 一 ①②③ 全勾）② 后端完成性检查（§ 二 + git tag）③ 前端完成性检查（§ 三 + tag）④ 真值表派发到 phase-driver 用户手动运行 /erp-workflow:coding-start；milestone 每阶段完成后自动回调
interrupt-check 检查 CLAUDE.md 的 3 项中断清单；触发则追加 Blocker 到 spec 文件并停下 feature-tdd（同一测试 >10 次失败）/ milestone（环境失败横幅 ③）按需调用

计划阶段（skills/plan/）

Skill 作用 流程中谁调用
init 计划 ①：依赖检查 / git init / 创建 CLAUDE.md + docs/01/index.md + docs/04 § 零 + docs/08；引导填项目概述 / 技术栈 / 需求索引；按模块生成 REQ 卡片骨架；停下等人工审阅 REQ plan-start
design 计划 ②：生成 docs/04 架构规范大纲 + scripts（test.sh / setup-test-db.sh）+ .env.local + .gitignore 合并；从 docs/01 REQ 正向设计 docs/03-数据库设计文档.md（schema SSoT）；停下等人工审阅 docs/03 plan-start
build-db 计划 ③：解析 docs/03 → sql/migrations/V1__initial_schema.sql（5 维度校验 DDL ↔ docs/03）→ DROP+CREATE 本地 schema 并 apply V1；生成 docs/05 API 契约 + 回填 REQ 依赖接口；追加模块清单到 docs/08 § 二；打印 Plan 完成横幅并停下 plan-start

编码阶段（skills/coding/）

Skill 作用 流程中谁调用
phase-driver 阶段驱动（phase 参数区分）。backend：切 module-<id> 分支，扫 docs/08 § 二 计算未完成 REQ，推进第一个未完成 REQ；本模块全 approve → milestone。frontend：prototype/ 门禁 → FE 清单准备（§ 三 占位则推导写入，§ 三 已有则加载）→ 切 frontend-phase 分支，推进未完成 FE；全 approve → milestone。幂等可重入 coding-start 派发；feature-review approve 后回调
feature-spec 功能规格（两阶段共用）：为 REQ（后端）/ FE（前端）生成"规格 + 任务级计划"合并文档（docs/superpowers/specs/*.md）；路径护栏按 phase 区分 phase-driver 推进单元时调用
feature-tdd TDD 实现（两阶段共用）：按 spec/plan 写失败测试 → 实现 → Agent 子会话验证通过 → commit（后端：controller/service/repository/DTO/migration；前端：frontend/ 下组件/路由/API client） feature-spec 链式调用
feature-review 验证 + AI 自审（两阶段共用）：子会话跑全量测试 → 委托 reviewer agent（后端：superpower-code-reviewer；前端：fe-code-reviewer）。approve → 勾选 docs/08 对应子项 + 回 phase-driver；request-changes → fix → 重跑（最多 5 轮，第 5 轮仍 request-changes 则停下） feature-tdd 链式调用
milestone 里程碑（phase 由当前分支推断）：内置测试闸门（Agent 子会话：后端 scripts/test.sh；前端 vitest + Playwright）→ 6 节完成报告 → 本地 git merge --no-ff 进默认分支 → 回写 docs/08 里程碑: 字段 → git tag -a milestone/<id> → 自动回调 coding-start（无人工介入）。完成由本地 git tag -l 判定 phase-driver（本阶段全部单元 approve 后）

Agent 清单（2 个）

Agent 用途 谁调用
superpower-code-reviewer 对后端 REQ diff 做 AI 自审，产出 must_fix[] / nice_to_have[] / gaps feature-review（phase=backend）：Agent(subagent_type=superpower-code-reviewer)
fe-code-reviewer 对前端 FE-NN diff 做 7 维 AI 自审：prototype 一致性 / Design Tokens / 无障碍 / 响应式 / 业务校验前端复刻 / API 一致性 / 状态机覆盖 feature-review（phase=frontend）：Agent(subagent_type=fe-code-reviewer)

Banners 清单（2 份）

流程图抽到独立 .txt 文件，SKILL.md 步骤 0 用 bash cat 输出——保证 ASCII 边框对齐不被 LLM 复读破坏。

所属 Skill Banner 文件 用途
plan-start banners/flow.txt 整体流程图（▶ 标在 plan-start 分发横幅前）
coding-start banners/flow.txt 整体流程图（▶ 标在 coding-start 分发横幅前）

Templates 清单（22 份模板文件，21 个不同名——commit-message-template.md 由 feature-tdd / feature-review 各持一份）

所属 Skill 模板文件 用途
init CLAUDE-template.md 项目根的 CLAUDE.md（4 条通用准则 + ERP 专属约定 + skill 索引）
init docs-01-index-template.md 需求清单索引骨架
init docs-08-initial-template.md 工作流进度文件骨架（Plan ①②③ checkbox）
init docs-04-stack-template.md docs/04 § 零 默认技术栈总览（零槽位，cp 即可）
init req-card-template.md 单张 REQ-XXX-NNN 卡片骨架（6 个 {{...}} 占位符由 CC 替换）
init _module-template.md 模块子目录的 _module.md 模块头
design docs-04-skeleton-template.md docs/04 § 一+ 编码规范大纲
design docs-03-header-template.md docs/03 数据库设计头部
design docs-03-table-template.md docs/03 单表小节模板
design scripts-setup-test-db-template.sh drop + create 空库脚本（0 槽位）
design scripts-test-template.sh test.sh 骨架（多个命令槽位，由 design 按技术栈推断填充）
design env-local-template 6 字段凭据模板（DB_* + JWT_SECRET）
design gitignore-append-template 插件推荐忽略项（.env.local、.tmp/、构建产物等）
build-db docs-05-header-template.md docs/05 API 契约头部
build-db docs-05-endpoint-template.md docs/05 单接口小节
build-db docs-08-module-row-template.md docs/08 § 二 单模块 bullet 行
feature-spec feature-spec-plan-template.md 功能规格 + 任务级计划合并文档
feature-review feature-review-template.md 自审报告结构
feature-review commit-message-template.md review fix commit 信息
feature-tdd commit-message-template.md TDD 每步 commit 信息
milestone milestone-report-template.md 完成报告模板（6 节）
interrupt-check interrupt-block-template.md Blocker 节追加模板

Scripts 清单（2 份）：

所属 Skill 脚本文件 用途
init scripts/render.sh 渲染单个 _module.md 或 REQ-*.md（替换 6 个占位符）
design scripts/merge-gitignore.sh 合并 .gitignore（逐行判重）

流程使用情况：所有模板都被对应 skill 的 SKILL.md 引用，没有孤儿模板。

前置依赖

  • MySQL 8.x 实例已就绪（推荐本地 / *.local host；build-db 的安全守护要求 host 在白名单且 schema 名含 test/dev/local，避免误删生产库）
  • mysql 命令行：build-db 验证连接 + 自动 DROP+CREATE schema 后 apply V1；scripts/setup-test-db.sh 在测试闸门前后 drop+create 空库
  • Spring Boot + Flyway（必需）：pom.xml 声明 flyway-core + flyway-mysql；Spring 启动时自动 apply sql/migrations/V*.sql。本插件生成的 setup-test-db.sh 只清库，schema 必须由 Flyway 应用
  • 本地 git 仓库（纯本地，无需远程 / push / GitLab）：init 执行 git init；编码阶段每模块由 milestone 本地 git merge --no-ff 进默认分支并 git tag -a milestone/<id>，完成信号由 git tag -l 判定
  • 本地可运行 mvn test / pnpm test：测试闸门 scripts/test.sh 由 design 生成

设计原则

参见 init/templates/CLAUDE-template.md 末尾的「通用工作准则」4 条：① Think Before Coding ② Simplicity First ③ Surgical Changes ④ Goal-Driven Execution。

最关键的 1 条："所有测试与验证派发到全新子会话执行，主会话只接收结构化结论"——避免主会话被测试输出污染，并让测试结果作为独立证据存档。