README.md 20.6 KB

Edit Raw Blame History



erp-workflow

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

把"从零到 N 个模块上线"的整个流程固化成 21 个 skill + 1 个 agent + 2 个 hook + 37 份模板，让 CC 在 schema 演化用 Flyway migration、需求可追溯、人工审核可控的前提下推进编码。


这个插件做什么
📋 阶段 A：规划（一次性，入口 /erp-workflow:plan-start）

   A0 初始化项目 → A1 锁范围（生成 REQ 卡片）
                          ↓
              ⏸ 审阅 REQ → 重新运行 /plan-start
                          ↓
   A2 生成骨架 → A3 生成 DB 设计（REQ → docs/03 + 回填依赖表）
                          ↓
              ⏸ 审阅 docs/03 → 重新运行 /plan-start
                          ↓
   A4 初始化 DB（docs/03 → V1 migration → 自动 apply 到本地 MySQL）
                          ↓
   A5 生成下游文档（docs/02 / docs/05 / docs/06 § 五 / docs/10）
                          ↓
                  用户显式 /erp-workflow:coding-start

🔁 阶段 B：编码（按模块循环，入口 /erp-workflow:coding-start）
   功能循环：Brainstorm → Plan → TDD → Verify → Review
   模块循环：本地测试闸门 → 写模块报告 → 创建 GitLab MR → ⏸ 用户 Approve+Merge → 下次 coding-start 自动扫描 MR 状态为 merged → 下一模块

⚙️ 后台守门：占位符未填 / 中断触发 / 跨模块改动未记录


首次使用


进入空项目目录并启动 Claude Code：
mkdir my-erp && cd my-erp
claude --plugin-dir /path/to/erp-workflow-plugin


Plan 阶段入口（一次性规划）：
/erp-workflow:plan-start


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


第一段（首次运行）：执行 A0 → A1（创建骨架 / 锁技术栈 / 填需求 / 生成 REQ 卡片骨架）后停下，等你审阅并补全 docs/01-需求清单/<module>/REQ-*.md（CC 已起草 req_id / title / goal / rules / constraints / acceptance；输入 / 输出 各保留「主表 + 从表1」骨架表，留 - 等你按业务补；依赖表 / 依赖接口保留 TBD(A3/A5 自动补) 由后续 skill 回填——Plan 阶段第一个人工关口：业务范围）

第二段（REQ 审阅完重新运行）：继续 A2 → A3（生成骨架 / 从 REQ 正向设计 docs/03-数据库设计文档.md 并回填 REQ 依赖表）后再次停下，等你审阅 docs/03 的表 / 字段 / 索引 / 外键（第二个人工关口：数据库 schema —— A4 会基于它翻译 DDL 并 apply 到 MySQL，所以这关口与 REQ 审阅同等重要）

第三段（docs/03 审阅完重新运行）：执行 A4 → A5（解析 docs/03 → 生成 V1 migration → 自动 DROP+CREATE 本地 schema 并 apply → 生成下游文档），Plan 完成后再次停下


每次运行都会自动接上次停下的地方继续；中途可以随时关闭 CC，下次运行同样的命令即可恢复。Plan 完成后不会自动进入编码，需要你手动运行 /erp-workflow:coding-start。


两个审阅断点的勾选位置都在 docs/08-模块任务管理.md § 一：A1 审阅完后系统已自动勾选 A1 全部子项；A3 审阅完后需要手动勾选「用户已审阅 docs/03 表结构」+ A3 父项 [ ] → [x]，下次 /plan-start 才会派发到 A4。


Coding 阶段入口（模块循环）：

/erp-workflow:coding-start

Plan 全部完成后由你显式触发。按 docs/02 § 二 REQ 开发顺序清单扫描，决定当前模块：
对每个 REQ 所属模块查询 docs/08 的 MR: 字段，必要时调 GitLab API 取 state：


MR: — → 该模块是当前模块（未建过 MR）

MR: !<iid> 且 API state == merged → 模块已完成，跳过

MR: !<iid> 且 API state ∈ {opened, closed} → 该模块是当前模块

MR: !<iid> 但 API HTTP 非 200 / 查不到 / state 非法 → 停下报错让用户排查 token / API URL / project ID / iid（绝不静默假设未 merged）


之后自动探测远程默认分支 → git checkout <默认分支> + git pull --ff-only 同步远程 → 派发到 module-start。

docs/08 § 二 每模块占一行 bullet，完成信号由 MR merged state 判定；即使用户提前触发 coding-start，未 merged 的模块仍会被选中，不会跳过。


中途恢复：任何时候运行对应入口命令——根据 Plan § 一 checkbox 和 § 二 各模块 MR state 跳到当前该做的事。


目录结构
erp-workflow-plugin/
├── .claude-plugin/
│   └── plugin.json                  # 插件清单，声明 skills 四个子目录
├── README.md                        # 本文档
├── hooks/
│   ├── hooks.json                   # hook 注册表（2 个 hook）
│   └── scripts/*.sh                 # 2 个 hook 脚本
├── agents/
│   └── superpower-code-reviewer.md  # code-reviewer agent（feature-review 调用）
└── skills/
    ├── plan/                        # 阶段 A：6 个一次性规划 skill
    ├── coding/                      # 阶段 B：9 个模块/功能循环 skill
    ├── crosscut/                    # 横切：2 个入口 + 1 中断守门 + 1 留痕 skill
    └── internal/                    # superpowers 本地 fork：2 个无门 brainstorming / writing-plans


Hook 清单（2 个，全部在 hooks/hooks.json 注册）


Hook
脚本
事件
触发条件
作用


拒绝 no-verify
deny-no-verify.sh
PreToolUse / Bash
CC 尝试 git push --no-verify

硬拦截，强制 .githooks/pre-push 生效


跨模块改动留痕
log-cross-module.sh
PostToolUse / Edit \
Write
当前处于 module-* 分支 且 编辑目标路径落在 docs/08 § 二 中非当前模块的 path 范围内（无论目标模块 MR 是否已 merged）


Skill 清单（21 个）


Plan 阶段（6 个，skills/plan/）


#
Skill
作用
流程中谁调用


A0
project-init
• 依赖检查（mysql 在 PATH，缺失则尝试自动安装）
• 空目录初始化：cp 模板创建 CLAUDE.md / docs/01/index.md / docs/08
• git init

plan-start


A1
scope-lock
• 引导填项目概述 / 技术栈 / 需求索引
• 按 docs/01-需求清单/<module>/{_module.md, REQ-*.md} 子目录结构生成 REQ 卡片骨架（CC 起草 req_id / title / goal / rules / constraints / acceptance；输入 / 输出 各保留「主表 + 从表1」骨架，每张表表头 + 1 行 - 等人工补；依赖表 / 依赖接口 留 TBD(A3/A5 自动补)）
• 停下等人工审阅 + 填输入 / 输出表，审阅完毕用 /plan-start 恢复续进 A2
A0


A2
skeleton-gen
• 生成架构文档：docs/04 § 一+ / docs/06 / docs/07 / docs/09
• 生成工具脚本：scripts/*.sh、.githooks/pre-push、.env.local
• 创建 sql/migrations/ 空目录（Flyway 准备）
• 合并 .gitignore（逐行判重）
plan-start


A3
db-design-gen
• 从 docs/01 REQ 卡片正向设计 docs/03-数据库设计文档.md（schema SSoT）
• 回填 REQ 卡片依赖表（TBD(A3 自动补) → 实际表名）
• 停下等人工审阅 docs/03，审阅完毕用 /plan-start 恢复续进 A4
A2


A4
db-init
• LLM 解析 docs/03 → sql/migrations/V1__initial_schema.sql（DDL only）
• 5 维度全量校验 DDL ↔ docs/03（表名 / 列名+列序 / 类型+nullable+默认值 / 索引名 / FK 名），fail-closed
• 验证 MySQL 连接
• 调 scripts/setup-test-db.sh 复用三层防护（与 B 阶段 test.sh 共用）→ DROP+CREATE 空库
• apply V1 + SHOW TABLES 行数自检
A3


A5
downstream-gen
• 一次性生成 docs/02 / docs/05 / docs/06 § 五 / docs/10
• 回填 REQ 卡片依赖接口（TBD(A5 自动补) → 实际 endpoint）
• 追加模块清单到 docs/08 § 二
• 最终占位符扫描（TBD 自动补 + 【人工填写：】 QA 循环）
• 打印 Plan 完成横幅并停下（不自动进 B）
A4


Coding 阶段（9 个，skills/coding/）

触发与顺序（coding-start 是唯一由用户手动触发的入口，下面所有 skill 都由 skill 链自动调用）：
/erp-workflow:coding-start          ← 用户每次手动触发
        │
        │  扫描 docs/02 REQ 序 + docs/08 MR 字段 + GitLab API state 判定当前模块：
        │  - 所有模块都 merged → 打印"所有模块已完成"
        │  - 找到第一个非 merged 模块 → 派发
        │  派发前自动探测远程默认分支（main / master），git checkout + git pull --ff-only 同步远程 base
        │
        └─→ module-start（幂等可重入，切 module-<id> 分支）
                  │
                  │ 对每个未完成 REQ，按序串链：
                  │ feature-brainstorm → -plan → -tdd → -verify → -review
                  │
                  │ review approve              → 回 module-start（推进下一 REQ）
                  │ review request-changes (<5) → fix commit → 回 feature-verify 重新执行
                  │ review request-changes (=5) → 停下（升级给人）
                  │
                  │ 模块全部 REQ approve →
                  │   test-gate（commit test-gate.md）
                  │   → module-report（commit 模块报告 + cross-module log）
                  │   → mr-create（worktree clean 校验 → push 代码+evidence → 创建 MR
                  │       → 追 MR URL 到报告 + commit → 写 MR iid 到 docs/08 + commit
                  │       → 再 push）
                  │
                  └─ ⏸ 停下等人工 Approve + Merge
                     （人工合并后再次运行 coding-start，扫描到 state=merged 自动跳过
                      → pull 默认分支 → 推进下一模块）


Skill
做什么
谁触发它


module-start
定位当前模块（docs/02 REQ 序）+ 切换或创建 module-<id> 分支 + 扫描 docs/superpowers/reviews/*.md 的 verdict=approve 计算已完成 REQ + 推进第一个未完成 REQ 的功能循环。全部完成 → test-gate。幂等可重入（中途断开后重新运行会自动跳过已 approve 的 REQ）

coding-start 派发；feature-review approve 后回调


feature-brainstorm
功能循环步骤 1：交互 brainstorm → 生成 docs/superpowers/specs/*.md


module-start 推进 REQ 时调用


feature-plan
功能循环步骤 2：spec → 任务级 plan（文件路径 + API 签名 + 测试意图 + 完成判据，代码由 TDD 阶段产出），输出 docs/superpowers/plans/*.md


feature-brainstorm 链式调用


feature-tdd
功能循环步骤 3：红绿循环（写失败测试 → 实现 → 子会话验证通过 → commit 到 module-<id> 分支）

feature-plan 链式调用


feature-verify
功能循环步骤 4：将全量测试派发到子会话执行一次，用模板渲染 evidence

feature-tdd 链式调用；feature-review 在 request-changes 修复后重新调用


feature-review
功能循环步骤 5：AI 自审，写 docs/superpowers/reviews/*.md。approve → 回 module-start；request-changes → 逐项 Edit + fix commit → 回 feature-verify 重新执行（最多 5 轮，第 5 轮仍 request-changes 则停下）

feature-verify 链式调用


test-gate
MR 前硬闸门：子会话执行 scripts/test.sh（脚本内部 drop+create 空库、Flyway apply sql/migrations/V*.sql、再执行测试）；通过 → 写 <module_id>-test-gate.md 并 git add + commit（evidence 提交到 module 分支）；失败停下

module-start 在本模块所有 REQ approve 后调用


module-report
中断检查 → 生成 12 节模块完成报告 docs/superpowers/module-reports/<date>-<module_id>.md → git add + commit（报告 + cross-module log 提交到 module 分支，mr-create 的 worktree clean 前置条件依赖此步）

test-gate 链式调用


mr-create
中断检查 → 验证当前分支 = module-<id> 且 git status --porcelain worktree 干净 → git push 推代码与全部 evidence → 用 curl 调 GitLab REST API 创建 MR（模块报告嵌入 MR 描述）→ 追加 MR URL 到报告并 commit → 把 docs/08 该模块的 MR: — 回写为 MR: !<iid> 并 commit → 再次 push；停下等人工 Approve+Merge。完成由 MR state 判定

module-report 链式调用


Crosscut（4 个，skills/crosscut/）


Skill
作用
流程中谁调用


plan-start

A 阶段入口。读取 docs/08 § 一 找第一个未勾 A 子项 → 派发对应 A skill；A 全部完成时提示运行 coding-start

用户手动运行 /erp-workflow:plan-start


coding-start

B 阶段入口。先验证 Plan 已完成；按 docs/02 § 二 REQ 序扫描，对每个 REQ 所属模块查询 MR: 字段 + GitLab API state：merged 跳过；—/opened/closed 选为当前模块；查不到则停下报错。派发前自动探测远程默认分支（main / master），git checkout + git pull --ff-only 同步远程 base，然后调用 module-start


用户手动运行 /erp-workflow:coding-start


interrupt-check
检查 CLAUDE.md 的 3 项中断清单；触发则追加 Blocker 到计划文件并停下
功能循环各步骤和生成重要制品前自动调用


cross-module-log
给 log-cross-module.sh 追加的跨模块改动存根批量补「原因 / 影响评估」

module-report § ⑦ 硬验收时一次性调用（CC 编辑中途不主动调）；module-start 初始化日志文件时也会用其模板


Internal / Superpowers Fork（2 个，skills/internal/）

superpowers:brainstorming / superpowers:writing-plans 原版内含 <HARD-GATE> 与"等用户 approve 设计 / review spec / Which approach?"等用户等待点，与本插件"除真正卡死外不停"目标冲突。fork 进来剥掉门控后作为 feature-brainstorm / feature-plan 的内部实现用。


Skill
源（superpowers 版本）
剥掉了什么


superpower-brainstorming

superpowers:brainstorming 5.0.7

<HARD-GATE> 整块、Anti-Pattern 段、Checklist 里 Visual Companion / approve-design / review-spec 三项、User Review Gate、Visual Companion 整节、终点 invoke writing-plans


superpower-writing-plans

superpowers:writing-plans 5.0.7
Execution Handoff 整节（"Which approach?" 问询）、"Complete code in every step" 硬要求（改为"API 签名 + 测试意图"粒度，完整代码留给 TDD）


Agent 清单（1 个）


Agent
源
用途
谁调用


superpower-code-reviewer

superpowers:code-reviewer 5.0.7 agent，仅改 name
对 REQ diff 做 AI 自审，产出 must_fix[] / nice_to_have[] / gaps


feature-review 步骤 1：Agent(subagent_type=superpower-code-reviewer)


Templates 清单（37 份）


所属 Skill
模板文件
用途


project-init
CLAUDE-template.md
项目根的 CLAUDE.md（4 条通用准则 + ERP 专属约定）


project-init
docs-01-index-template.md
需求清单索引骨架，等用户填模块表


project-init
docs-08-initial-template.md
工作流进度文件骨架（Plan A0~A5 checkbox）


project-init
docs-04-stack-template.md
docs/04 § 零 默认技术栈总览（零槽位，cp 即可）


scope-lock
req-card-template.md
单张 REQ-XXX-NNN 卡片骨架（6 个 {{...}} 占位符由 CC 替换；输入 / 输出 各含「主表 + 从表1」骨架表，留 - 等人工补）


scope-lock
_module-template.md
模块子目录的 _module.md 模块头（4 行：模块代码-名 / 简述 / 依赖模块 TBD / 涉及表 TBD）


skeleton-gen
docs-04-skeleton-template.md
docs/04 § 一+ 编码规范大纲（HTML 注释引导 LLM）


skeleton-gen
docs-06-static-template.md
docs/06 § 一~四 UI 模式大纲


skeleton-gen
docs-07-env-template.md
docs/07 环境配置大纲


skeleton-gen
docs-09-structure-template.md
docs/09 目录结构大纲


skeleton-gen
scripts-setup-test-db-template.sh
运行时 drop + create 空库脚本（0 槽位）；schema apply 交给 Flyway


skeleton-gen
scripts-test-template.sh
test.sh 骨架（4 个命令槽位：{{build_cmd}} / {{lint_cmd}} / {{test_cmd}} / {{e2e_cmd}}，由 skeleton-gen 按技术栈推断填充）


skeleton-gen
githooks-pre-push-template.sh
pre-push → 调 scripts/test.sh（0 槽位）


skeleton-gen
env-local-template
6 字段凭据模板（DB_* + JWT_SECRET）


skeleton-gen
gitignore-append-template
插件推荐忽略项（.env.local、.tmp/、构建产物等）


db-init
migration-v1-header-template.sql
V1 initial migration 文件头部注释


db-design-gen
docs-03-header-template.md
docs/03 数据库设计头部


db-design-gen
docs-03-table-template.md
docs/03 单表小节模板


downstream-gen
docs-02-template.md
docs/02 开发计划


downstream-gen
docs-05-header-template.md
docs/05 API 契约头部


downstream-gen
docs-05-endpoint-template.md
docs/05 单接口小节


downstream-gen
docs-06-module-pagelist-template.md
docs/06 § 五 单模块页面清单


downstream-gen
docs-08-module-row-template.md
docs/08 § 二 单模块 bullet 行


downstream-gen
docs-10-header-template.md
docs/10 验收清单头部


downstream-gen
docs-10-module-template.md
docs/10 单模块验收项


module-start
module-start-banner-template.md
模块启动横幅


module-start
cross-module-log-template.md
cross-module 日志头（副本）


feature-brainstorm
feature-spec-template.md
功能 spec 结构


feature-plan
feature-plan-template.md
功能 plan 结构


feature-tdd
commit-message-template.md
TDD 每步 commit 信息


feature-verify
feature-verify-evidence-template.md
验证证据渲染模板


feature-review
feature-review-template.md
自审报告结构


test-gate
test-gate-result-template.md
闸门结果渲染


module-report
module-report-template.md
12 节模块报告


mr-create
mr-title-template.md
MR 标题模板


mr-create
mr-description-template.md
MR 描述模板（嵌入模块报告）


interrupt-check
interrupt-block-template.md
Blocker 节追加模板


cross-module-log
cross-module-log-template.md
cross-module 日志头（主本）


cross-module-log
cross-module-log-row-template.md
单条改动行模板


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


前置依赖


MySQL 8.x 实例已就绪（推荐本地 / *.local host；A4 db-init 的安全守护要求 host 在白名单且 schema 名含 test/dev/local，避免误删生产库）

mysql 命令行：A4 db-init 验证连接 + 自动 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 应用

GitLab v3 API + Private Token：mr-create 用 curl POST /projects/:id/merge_requests 建 MR；coding-start / module-start 用 curl GET /projects/:id/merge_requests?iid=<iid> 判定 state（v3 路径参数 :merge_request_id 要内部数字 id，所以统一用 iid 过滤列表）。HTTP 头用 PRIVATE-TOKEN；凭据（GITLAB_API_URL=.../api/v3 / GITLAB_TOKEN / GITLAB_PROJECT_ID）放 .env.local


本地可运行 mvn test / pnpm test：测试闸门 scripts/test.sh 由 skeleton-gen 生成


设计原则

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

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