给 Cursor(或其它支持 Agent Skills 的 AI 编程工具)设计的一套规范驱动(spec-driven)开发流水线。1 个总控 + 6 个阶段 = 7 个 Skill,让 AI 从「自由发挥」变成「按流程走」。不同工具的 Skill 安装目录可能不同,本文以 Cursor 的
.cursor/skills为例。
一、背景:为什么需要一套工作流
上一篇 《我用 7 条铁律管住 Cursor:让 AI 写代码不再「自由发挥」》 讲的是底线 ------每次对话都生效的 code-rules.mdc,管的是 AI 的行为习惯:别建临时文件、别藏异常、别编接口。 但光有底线不够。底线管的是「AI 怎么写」,不管「AI 什么时候写什么」。没有流程约束时,AI 会出现这些问题:
- 无阶段感:一上来就开始写代码,跳过了需求对齐和方案设计。需求理解偏差了,代码写得再规范也是白搭。
- diff 不可审:探索、实现、审查混在一坨。你看到 200 行 diff,不知道哪些是探索产物、哪些是业务代码、哪些是调试残留。
- 靠记忆:跨会话时 AI 靠「上一个会话的结论」工作,但仓库代码已经变了,旧结论可能已经过期。
- 跳过验证:AI 写完代码直接说「我检查过了」,但实际没跑 lint、没跑 typecheck,甚至编译都不过。
- 随意提交 :AI 不等审查通过就
git add .+git commit,把调试代码、生成文件、IDE 私有配置一起提交了。 - 多仓混乱:多仓库联动时,AI 不知道哪个仓改什么、change 该建在哪、各仓字段怎么对齐。
LWC Workflow 把 AI 开发拆成 6 个阶段(加 1 个总控 = 7 个 Skill),每阶段有明确输入、输出和门禁,跨会话靠 git 事实重判阶段,不靠记忆。底线管习惯,工作流管节奏,两者配合 AI 既不失控也不僵化。
适合什么类型的任务
| 适合 ✅ | 不太适合 ❌ |
|---|---|
| 需求明确的功能开发(加页面、加接口、改逻辑) | 一两行的小改(直接说改点即可,无需走完整流程) |
| 多仓联动需求(B 端 + C 端联调) | 纯样式微调(改个颜色、间距) |
| 需要方案确认后才动手的中大型改动 | 探索性调研(只是看看代码怎么写的) |
| 有 OpenSpec change 的结构化变更 | 紧急热修(走 hotfix/ 分支但仍需过门禁) |
优缺点对比
| 维度 | 优点 | 缺点 |
|---|---|---|
| 质量 | 八维度 CR(Code Review,代码审查)+ P0 拦截,AI 代码必须通过预设审查标准才能提交 | 完整走六阶段比「直接让 AI 写」慢 |
| 可审性 | 每阶段有交接摘要 + 审查指纹,diff 来源清晰 | 需要用户在每个阶段确认,有交互成本 |
| 跨会话 | 靠 git 事实重判,不依赖旧记忆 | 首次使用需配置 lwc-flow.yml 和安装 skill |
| 自动化 | 分支门禁、验证清单、归档、提交推送全自动 | 不含部署/发布,需手动操作 Jenkins(或其它流水线部署)/上传 |
| 测试 | 验证清单自动跑 lint/stylelint/typecheck,也可提供浏览器核验证据 | 仍需人工验收------关键交互、真实业务数据和真机流程不能只依赖 AI |
总结
LWC Workflow 是一套重流程、强门禁的 AI 协作开发流水线。它不追求「最快」,追求的是「每一步都有据可查、本任务 diff 都经过审查」。适合对代码质量有要求、多仓协作、需要 CR 把关的团队或个人。
二、OpenSpec 简介
复杂变更可以接入 OpenSpec------一个 AI 原生的规范驱动开发工具。它把「需求」变成结构化的变更提案(change),让 AI 按文档实现,而不是按猜测实现。在 LWC Workflow 里,OpenSpec 不是独立阶段,而是作为子流程嵌入 explore、apply 和 commit:
| 所在阶段 | Skill 指令 | 作用 |
|---|---|---|
| explore | /opsx:propose |
创建变更并生成 proposal / design / tasks |
| apply | /opsx:apply |
按 tasks 实现并同步完成状态 |
| commit | /opsx:archive |
归档已完成变更 |
一两行小改或边界清晰的简单需求可以不开 OpenSpec:在 explore 中通过对话确认改点,随后进入 apply、review 和 commit。只有走 OpenSpec change 的路径,才要求校准产物、完成 tasks 和 archive。
更多实践参考:OpenSpec 最佳实践教学
官网及下载地址:openspec.dev/
三、lwc-flow 总控
lwc-flow 是整条流水线的总控入口。它自己不写环境卡、不写方案、不写代码、不审查、不提交------它只做两件事:判定当前阶段 和 分流到对应 skill。
流程图
跨会话原则
整条流水线不要求在一个会话完成。新会话说一句 lwc-flow,它会重新读取仓库事实判断阶段,不依赖旧会话记忆。具体做法:先读 lwc-flow-state.yml 状态文件当线索,再用 git 核验当前状态。对不上就作废,按仓库现状重判。
阶段判定规则
| # | 条件 | 判定 |
|---|---|---|
| 1 | 用户要初始化/刷新环境 | env |
| 2 | 仓库缺规范文件 | rules |
| 3 | 所有未推送仓工作区干净、commit 可核验、不落后不分叉 | commit-resume(只续推) |
| 4 | 多仓部分 commit 失败,仍有仓有未提交 diff | review(只对未提交仓) |
| 5 | 已有 S/A/B 的 CR,指纹一致,tasks 全完成 | commit |
| 6 | 有已确认方案,tasks 未完成 | apply |
| 7 | tasks 完成,有未提交 diff,无核验 CR | review |
| 8 | 无本任务 diff,但有未归档 change | 拦截,回 explore/apply |
| 9 | 已推送,工作区无本任务改动 | 流水线结束 |
| 10 | 无 diff,无方案,无 change | explore |
判断不唯一时问用户,不猜。
前置门禁
用户明确点名阶段只省略阶段确认,不代表可跳过门禁:
| 进入阶段 | 不可跳过的条件 |
|---|---|
| env | 已确认目标工作区;只读环境事实 |
| rules | 已确认目标仓;规范草案须用户确认后才写入 |
| explore | 已确认需求边界和目标仓;准备 propose 时通过 OpenSpec 能力预检 |
| apply | 已有用户确认方案;分支通过门禁;使用 OpenSpec change 时产物校准通过 |
| review | 有边界明确的本任务 diff;按本仓验证清单核验 |
| commit | OpenSpec 路径的 tasks 全完成;CR 为 S/A/B 且无未豁免 P0;审查指纹一致;分支通过门禁 |
硬规则
- 不直接改业务代码------交给 apply 阶段。
- 不直接 git commit------交给 commit 阶段。
- propose / archive 不是独立阶段------分别并进 explore、commit。
- 不设 lwc-deploy------用户说「部署」时指引 lwc-env 的 Jenkins(或其它流水线部署)/手动步骤。
- 部署/发布不在本流水线内------需手动操作 Jenkins(或其它流水线部署)。
四、逐阶段详解
下面用一个完整案例贯穿六阶段:给收款单页面加一个文本字段高级设置功能。工作区有 3 个仓库:
| 仓库 | 角色 | 技术栈 | 职责 |
|---|---|---|---|
| my-admin-project(B端) | 主仓 | Vue 2.6 + Ant Design Vue + Less | 加设置页和菜单入口 |
| my-h5-project(C端) | 兄弟仓 | Vue 3 + Vant 3 + TS | 收款单展示文本字段 |
| my-miniprogram(C端) | 兄弟仓 | Taro 3.4 + NutUI + TS | 小程序端展示同款字段 |
三仓共用分支 feature/lwc-20260904-receiptText。
1. env --- 环境卡
是什么 :读取 package.json、README 等输出环境卡------技术栈、安装/启动/打包命令、页面入口、预览方式。
为什么需要它:第一次进入项目时 AI 不知道怎么跑、怎么预览,后续阶段都要以环境卡为基础。
解决什么问题:消除「AI 不知道项目技术栈和启动方式」的盲飞状态。
不做什么 :不启动服务、不检查终端进程、不改文件。 分支标注:读 lwc-flow.yml,按 branch-gate.md 的 env 列校验。前缀不对或不含标识 → 标 ❌;日期过老 → 标 ⚠️。env 只标注不拦截。
完整输出报告(以 B 端为例,H5 和小程序同理):
仓库:my-admin-project(B端)
检查时间:2026-09-04 10:30
项 内容 产品名 新商户后台 当前分支 feature/lwc-20260904-receiptText技术栈 Vue 2.6 + Vue CLI 3 + Vuex + Ant Design Vue + Less 安装命令 yarn启动命令 测试: yarn serve/ 预发:yarn serve:beta打包命令 测试: yarn build:test/ 正式:yarn build页面/菜单入口 src/views/→src/router/modules/→src/config/realRoute.js→src/config/permissionMenu.js接口约定 手写 src/api/(非 Apifox);新文件须在index.jsexportAI 规范 AGENTS.md:✅ / CLAUDE.md:无 / code-rules.mdc:已启用 OpenSpec 仓库 skill:有;本机 CLI: openspec 1.6.0
方式 入口 条件 本地浏览器 http://localhost:8080/须登录 + 对应权限角色 测试站 http://admin-test.example.com/须登录 + 对应权限角色
环境 域名 部署 测试 admin-test.example.com A 正式 admin.example.com B 交接摘要:env / 完成 / 三仓环境卡输出 / 下一阶段:
lwc-rules
2. rules --- 规范卡
是什么 :读 package.json scripts + lint-staged + .husky/pre-commit,提炼隐性规范,确认后写入 AGENTS.md 或 CLAUDE.md。
为什么需要它 :老项目没规范文件时 AI 不知道目录约定、命名习惯、改了 .vue 要不要跑 stylelint。
解决什么问题:消除「AI 不知道该验什么、怎么验」的盲飞;产出该仓验证清单。
不做什么 :不写业务代码、不改依赖、不 git commit。 核心设计:现场探测,不硬编码。上百个仓库技术栈跨度 0-10 年,不可能在 skill 里写死规则。每仓现场探测产出验证清单。
完整输出报告:
规范探测报告
仓库 验证清单 写入目标 my-admin-project yarn lint+yarn lint:style(lint-staged + .husky/pre-commit)生成 AGENTS.md my-h5-project npm run lint+npm run typecheck(无 husky)生成 AGENTS.md my-miniprogram yarn lint+yarn typecheck(lint-staged)生成 AGENTS.md 交接摘要:rules / 完成 / 三仓 AGENTS.md 草案待确认 / 下一阶段:
lwc-explore
3. explore --- 方案
是什么 :探索现有实现并输出结论。复杂变更在确认后用 /opsx:propose 落盘 change 产物;小改只保留已确认的对话方案。
为什么需要它:动手前必须对齐方案,需求理解偏差会导致代码白写。
解决什么问题:消除「AI 直接写代码跳过方案设计」的问题;产出 tasks 作为实现和验收依据。
不做什么 :探索段禁止改 src/ 业务代码。 多仓 change 策略:B 端承载主体功能,H5 和小程序只消费字段 → 只在主仓建一份 change,兄弟仓由 tasks.md 覆盖。
完整输出报告:
方案报告
项 内容 change add-receipt-text-settings主仓 my-admin-project 兄弟仓 my-h5-project、my-miniprogram 产物 proposal.md / design.md / tasks.md / spec.md tasks.md 按仓库分节:
markdown## 仓库:my-admin-project - [ ] 新增 ReceiptTextSettings.vue - [ ] api/receipt.js 加接口 - [ ] realRoute.js 加菜单 + permissionMenu.js 放行 - [ ] 验证:yarn lint + yarn lint:style ## 仓库:my-h5-project - [ ] receipt/index.vue 加文本字段展示 - [ ] 验证:npm run lint + typecheck ## 仓库:my-miniprogram - [ ] pages/receipt/index.vue 加文本字段展示 - [ ] 验证:yarn lint + typecheck交接摘要:explore / 完成 / 下一阶段:
lwc-apply
4. apply --- 实现
是什么:按已确认方案改代码,最小 diff,交付前必跑验证清单。
为什么需要它:方案到代码之间需要有人执行,AI 按 tasks 逐条实现并验证。
解决什么问题:消除「AI 跳过验证直接交付」的问题;验证失败必须修完才交给 review。
不做什么:不 git commit、不 archive;没方案就拦住。 分支门禁:
| 条件 | 结果 |
|---|---|
| 前缀不在允许列表 | 拦住 |
不含个人标识 lwc |
拦住 |
| 日期距今 > 14 天 | 拦住 |
| 日期距今 > 7 天 | 先问 |
| 其余 | 通过 |
完整输出报告:
实现报告
仓库 门禁 tasks 改动文件 验证 my-admin-project ✅ 通过 4/4 ✅ ReceiptTextSettings.vue(新)、receipt.js、realRoute.js、permissionMenu.js yarn lint ✅ / lint:style ✅ my-h5-project ✅ 通过 1/1 ✅ receipt/index.vue npm run lint ✅ / typecheck ✅ my-miniprogram ✅ 通过 1/1 ✅ pages/receipt/index.vue yarn lint ✅ / typecheck ✅ 验证依据:各仓
package.jsonscripts、lint-staged 和.husky/pre-commit。预览证据:B 端本会话已核验新增菜单和设置页;H5、小程序本次只增加与金额无关的展示字段,不触发强制预览门禁。
交接摘要:apply / 完成 / 三仓验证全通过 / 下一阶段:
lwc-review
5. review --- 审查
是什么:对 diff 做八维度结构化审查,P0 拦截 commit,输出评分和审查指纹。
为什么需要它:AI 自己说「检查过了」不可信,必须用结构化清单逐维审查。
解决什么问题:消除「diff 不可审」的问题;确保 AI 代码必须通过预设审查标准才能提交。
不做什么:不改代码(除非修 review 发现的问题);不替代 apply 跑验证。 八维度:
| 维度 | 审什么 | P0 条件 |
|---|---|---|
| 1 方案与范围 | 对照 tasks/design,漏做或超范围 | 必要任务未做 |
| 2 正确性 | 逻辑错误、静态检查失败 | 编译失败、必现运行时错误 |
| 3 调用链 | 接口字段、路由菜单权限链路 | 编造接口、生成目录手改 |
| 4 回归与共享 | 公共组件/store/工具改动影响 | 有证据会坏其它入口 |
| 5 错误处理 | 空 catch、藏错误 | 主路径失败当成功 |
| 6 安全权限资金 | 支付/账单/鉴权 | 密钥进仓库、越权 |
| 7 本仓约定 | 与仓库规范/写法一致性 | 违反已写明约束 |
| 8 Diff 卫生 | 调试代码、无关文件 | 调试代码、密钥提交 |
评分:S(90-100)、A(80-89)、B(70-79)、C(60-69)、D(0-59)。P0 每条 −20,P1 −6,P2 −2,主路径每个未验证维度 −8。评分还受门禁封顶:有 P1 ≤89,有 P0 ≤69,主路径未验证 ≤79,两个及以上 P0 或安全/权限/资金 P0 ≤59。无未豁免 P0且评分达到 S/A/B,才能进入 commit。
完整输出报告(以 H5 为例):
CR 结论
可提交 · 评分 🟢 A(89)
范围:my-h5-project / feature/lwc-20260904-receiptText / 1 个文件
对照:add-receipt-text-settings
验证:
npm run lint -- receipt/index.vue:通过npm run typecheck:通过
维度 结果 说明 1 方案与范围 通过 tasks 全完成 2 正确性 通过 lint/typecheck 全过 3 调用链 通过 字段与 B 端一致 4 回归与共享 通过 未改公共组件 5 错误处理 有问题 P1:接口失败缺空态 6 安全权限资金 不适用 非支付改动 7 本仓约定 通过 写法与同类一致 8 Diff 卫生 通过 无调试代码
级别 位置 问题 为何 怎么改 ⚠️ P1 receipt/index.vue:88 缺空态 接口失败时页面没有明确反馈 加 v-if 空态提示 审查指纹
仓库 分支 HEAD tracked diff untracked 覆盖文件 my-h5-project feature/lwc-20260904-receiptText7c01abchash:a3f8...hash:e3b0...receipt/index.vue修正后重新执行受影响的验证并复审:P1 已修复,无 P0/P1/P2,评分 💚 S(100),生成新的审查指纹。
交接摘要:review / 完成 / 新指纹 hash:b4c9... / 下一阶段:
lwc-commit
6. commit --- 提交
是什么:CR 通过后,归档 change、精准暂存、本地 commit、逐仓推送。
为什么需要它:需要一个阶段把代码从「已审查」变成「已推送」,同时归档 OpenSpec change。
解决什么问题:消除「AI 随意 git add .」的问题;确保归档与代码同一笔提交;推送失败可续推。
不做什么 :不 --force、不 --no-verify、不 amend;部署不在本阶段。
完整输出报告:
提交报告(已提交 3 个仓)
仓库 commit 远程 archive my-admin-project a3f81c2✅ 已推送 add-receipt-text-settingsmy-h5-project 9b12e04✅ 已推送 无(兄弟仓) my-miniprogram c7d8f1a✅ 已推送 无(兄弟仓) 交接摘要:commit / 完成 / 流水线结束
五、核心设计理念
1. 不靠记忆靠 git 事实
AI 跨会话最常见的问题:上个会话说「方案已确认」,但这个会话没法验证。lwc-flow 的做法------每次进入都用 git 核验仓库真实状态,不读旧聊天记录。先读 lwc-flow-state.yml 状态文件当线索(线索,不是事实),再用 git 核验当前分支、HEAD、工作区是否与状态文件一致。对不上就作废,按仓库现状重判,写「状态文件已过期」。 举个例子:状态文件说「review 完成,指纹 hash:a3f81c2」,但 git diff 发现 diff 变了(你手动改了代码)→ 指纹对不上 → 状态文件作废 → 判回 review。
2. 门禁前置,不可跳过
六阶段各有前置门禁。用户明确说 lwc-flow apply 只是省略阶段确认,不代表可跳过门禁。apply 的门禁是「分支通过校验 + 已有确认方案」,使用 OpenSpec change 时还要校准产物------防止跳过探索直接写代码。review 的门禁是「有边界明确的 diff + 按本仓清单验证」------防止跳过验证直接审。commit 的门禁是「OpenSpec tasks 全完成(如有)+ CR 评 S/A/B 无未豁免 P0 + 指纹一致」------防止跳过审查直接提交。每道门都是一道安全网。
3. 规范现场探测,不硬编码
不在 skill 里写死 eslint 规则、样式方案、语法版本。每个仓库现场探测:先读 package.json 的 scripts + lint-staged + .husky/pre-commit 得出最小权威验证清单,再读 AGENTS.md / CLAUDE.md 获取已持久化的稳定规范,最后按需确认 .eslintrc* / .stylelintrc* / tsconfig.json 配置存在。 为什么不在 skill 里写死?上百个仓库,有的 eslint+stylelint,有的只有 eslint,有的啥也没有。写死「改了 .vue 跑 stylelint」在没配 stylelint 的仓就会报错。现场探测才能适配每个仓的实际情况。
4. CR 八维度 + P0 拦截
review 用八维度结构化审查。P0 每条 −20,必须改,拦截 commit;P1 −6,应该改;P2 −2,可选;主路径每个未验证维度 −8。评分按风险继续封顶:有 P1 ≤89,有 P0 ≤69,主路径未验证 ≤79,两个及以上 P0 或安全/权限/资金 P0 ≤59。OpenSpec 必做 task 未完成不接受豁免。S/A/B 才可进入 commit,C/D 回 apply。这套机制确保 AI 写的代码必须通过预设审查标准才能提交,而不是 AI 自己说「我检查过了」就提交。
5. 多仓 change 策略
多仓需求不是每仓各建一份 change。如果各仓有独立页面/流程/数据模型/发版边界,就每仓一份 change,各自归档。如果一个主仓承载主要能力,兄弟仓只消费字段/调整展示/透传参数,就只在主仓建一份 change,兄弟仓由主仓 tasks.md 覆盖。划分依据不是改动行数,而是业务边界。B 端加设置页(主体功能)+ H5/小程序加展示(薄适配)→ 一份 change,B 端为主仓。
6. 交接摘要 + 状态文件
每阶段结束输出固定字段的交接摘要,同时覆写 lwc-flow-state.yml。状态文件是线索不是事实------下次进入先读再核验,对不上就作废。
yaml
# lwc-flow-state.yml 示例
updatedAt: "2026-09-04T10:30:00+08:00"
stage: review
status: 完成
repos:
- folder: my-admin-project
branch: feature/lwc-20260904-receiptText
head: a3f81c2
change: add-receipt-text-settings
next: lwc-commit
fingerprint: "hash:a3f81c2e9d..."
六、快速上手
-
安装 Skill:
macOS / Linux:
bashmkdir -p ~/.cursor/skills cp -r skills/lwc-* ~/.cursor/skills/Windows PowerShell:
powershellNew-Item -ItemType Directory -Force ~/.cursor/skills | Out-Null Copy-Item -Recurse -Force skills/lwc-* ~/.cursor/skills/ -
配置 yml :创建
~/.cursor/lwc-flow.yml(见下方示例)。 -
配置底线 :将
code-rules.mdc复制到~/.cursor/rules/,设alwaysApply: true。 -
安装并初始化 OpenSpec(复杂变更需要,小改可跳过):
bashnode --version npm install -g @fission-ai/openspec@latest openspec --version cd your-project openspec initOpenSpec 要求 Node.js 20.19.0 或更高版本。
-
开始使用 :在 Cursor 中说
lwc-flow。
lwc-flow.yml 示例:
yaml
branchOwnerTag: your-tag
allowedBranchPrefixes:
- feature/
- hotfix/
- release/
commitTitlePrefixes:
feature/: "feat:"
hotfix/: "fix:"
release/: "chore:"
branchDateRequired: false
branchDateWarnDays: 7
branchDateBlockDays: 14
deploy:
testJenkins: "http://your-test-jenkins.example.com/jenkins/"
onlineJenkins: "http://your-online-jenkins.example.com/jenkins/"
七、与 code-rules 配合
| code-rules(底线) | LWC Workflow(工作流) | |
|---|---|---|
| 作用域 | 每次对话都生效 | 按需调用(lwc-flow 触发) |
| 管什么 | AI 的行为习惯 | AI 的协作节奏和阶段 |
| 典型规则 | 别建临时文件、别藏异常 | 先探索再写、改完必验、CR 通过才能提交 |
| 关系 | 走工作流时不关闭 | 工作流期间仍守 code-rules |
底线管习惯,工作流管节奏。两者配合,AI 既不失控也不僵化。
仓库说明
text
lwc-workflow/
├── README.md # 本文件
├── code-rules.mdc # 全局底线规则
├── lwc-flow.yml # 工作流配置
├── LICENSE # MIT
└── skills/
├── lwc-flow/ # 总控:阶段判定与分流
│ ├── SKILL.md
│ └── rules/{branch-gate.md, handoff.md}
├── lwc-env/ # 环境卡
│ ├── SKILL.md
│ └── reference/known-repos.md
├── lwc-rules/ # 规范卡
│ ├── SKILL.md
│ └── rules/project-profile.md
├── lwc-explore/ # 方案探索
│ └── SKILL.md
├── lwc-apply/ # 代码实现
│ └── SKILL.md
├── lwc-review/ # 审查
│ ├── SKILL.md
│ └── rules/{checklist.md, standards.md}
└── lwc-commit/ # 提交推送
└── SKILL.md
- GitHub : github.com/chao0225/lw...
- Gitee : gitee.com/chao1157381...
- License: MIT
- 作者: lwc