该不该给AI编程套上工作流?claude-code-workflows适用场景判断清单与四套插件选择指南
该不该给AI编程套上工作流?claude-code-workflows适用场景判断清单与四套插件选择指南
用 Claude Code 写代码,小改动很爽,大改动容易"跑偏"——探索了半天,却没交付你要的结果。claude-code-workflows 就是解决这个问题的 Claude Code 插件:它在动手前锁定目标和排除项,设计对照代码库检查,每个任务提交前验证,大改动还加独立安全审查。这篇文章给出一份"该不该用"的自我判断清单,以及四套插件的完整选择指南,帮你 30 秒内做出正确决定。
一、先搞清楚:工作流到底帮你解决什么?
直接让 AI 写代码时,常见翻车场景有这几类:
- 🎯 目标漂移:设计账户恢复功能时,AI 发现令牌处理有不一致,就一头扎进去重构,你想要的恢复行为反而没说清
- 🧩 设计自洽但跑偏:方案逻辑上没毛病,但漏掉了你真正要的行为
- ✅ 测试通过但没证明:测试全绿,却没真正观察到它声称要验证的东西
claude-code-workflows 的思路是:先约定结果和边界,再让 AI 自由发挥实现细节。范围获批后,它自主完成验证、质量检查、提交和最终审查,只在需要改变约定结果或执行不可逆操作时才问你。
💡 核心原则:目标和实现边界已经清楚 → 直接用 Claude Code;需要范围对齐、可追溯的设计决策、跨上下文交接或独立验证 → 用工作流。
二、适用场景判断清单:逐条对号入座
下面这张清单直接来自项目的设计理念(见 README.md 的 "When is the workflow useful?" 章节),命中 3 条以上就值得启用工作流:
| # | 判断项 | 说明 |
|---|---|---|
| 1 | 变更范围超过单个职责/模块 | 跨多个文件或跨前后端,AI 探索时可能被"顺带发现"的问题带偏 |
| 2 | 需要留下长期有效的设计决策 | 比如架构选型、数据格式变更,需要 Design Doc / ADR 存档 |
| 3 | 工作会跨多个上下文/会话/成员交接 | 需要 Work Plan 作为权威来源,让新人(或新会话)能接着干 |
| 4 | 涉及安全敏感面 | 文件路径、鉴权、外部输入等,需要独立安全审查把关 |
| 5 | 需求本身还没收敛 | "加个缓存"这种带方案的需求,需要先确认目标而非直接开工 |
| 6 | 团队多仓库要保持统一的质量控制 | 插件化让团队在不规定 AI 具体步骤的前提下套用同一套机制 |
反过来,以下情况别硬套工作流(官方明说"一次性实验或原型 → 直接用 Claude Code"):
- 🚫 一次性原型、实验性代码
- 🚫 目标和安全边界都清楚的常规改动
- 🚫 你已有自己的编排体系(自定义提示词 / CI),只需要编码最佳实践指南
工作流会增加 Agent 调用和文档产物,属于"花小钱买保障",收益必须覆盖成本。用不上全部检查时,可以启用 lite mode(轻量模式):在任意 recipe 请求里写明 "Lite mode" 即可,阶段和批准点不变,只是跳过对照代码库的设计检查与独立安全审查(详见 references/lite-mode.md)。
三、四套插件怎么选?一张表说清
项目在 .claude-plugin/marketplace.json 中声明了 4 套插件,全部 MIT 协议:
| 插件 | 定位 | 入口 recipe | 适合谁 |
|---|---|---|---|
dev-workflows |
后端 / API / CLI / 通用变更 | /recipe-implement、/recipe-design |
后端或通用项目 |
dev-workflows-frontend |
React / TypeScript 前端 | /recipe-front-design → /recipe-front-plan → /recipe-front-build |
前端专项 |
dev-workflows-fullstack |
后端 + 前端一体交付 | /recipe-fullstack-implement |
全栈项目 |
dev-skills |
只要技能指南,不要流程编排 | 无 recipe,技能自动加载 | 已有编排体系的团队 |
几个容易踩的选型细节:
- 一次只装一个工作流插件。
dev-workflows-fullstack已包含前后端全部工作流(24 个 agent + 29 个 skill),装全栈就别再装前两套 dev-skills不要和工作流插件同装:两者共享 skill,重复描述可能让 Claude Code 在上下文达到上限后忽略技能。切换方式是先/plugin uninstall再/plugin install- 选型口诀:纯后端选
dev-workflows;纯 React 前端选dev-workflows-frontend;前后端都动选dev-workflows-fullstack;只要规范指南选dev-skills
各插件的 agent 与 skill 清单可对照源码查看:dev-workflows/agents/、dev-workflows-frontend/agents/、dev-workflows-fullstack/agents/、dev-skills/skills/。
四、快速上手:一键安装步骤
要求使用支持插件市场的 Claude Code 版本(Node ≥ 22 环境用于仓库本地同步脚本,见 package.json)。
# 1. 启动 Claude Code
claude
# 2. 添加插件市场
/plugin marketplace add shinpr/claude-code-workflows
# 3. 按项目类型安装(三选一)
/plugin install dev-workflows@claude-code-workflows
# /plugin install dev-workflows-frontend@claude-code-workflows
# /plugin install dev-workflows-fullstack@claude-code-workflows
# 4. 若提示,先执行 /reload-plugins,再调用 recipe
/recipe-implement "Add rate limiting to the public API"
所有工作流入口都以 recipe- 前缀命名,输入 /recipe- 后按 Tab 即可补全查看已安装的候选项。团队场景可以用项目级安装,把 .claude/settings.json 提交到仓库,让所有贡献者使用同一套插件:
claude plugin marketplace add shinpr/claude-code-workflows --scope project
claude plugin install dev-workflows-fullstack@claude-code-workflows --scope project
五、工作流是怎么跑的?看懂 4 步任务周期
整体路由很简单:一个明显实现路径的变更 → 直接进任务周期;否则先检查、设计、审批范围,再进任务周期。路径由决策数量决定,而不是文件数量。
每个任务的执行是固定的四步循环(源自 recipe-implement/SKILL.md):
- task-executor 实现:专职 agent 按任务文件实现
- 针对性验证:测试改动涉及集成/E2E 时,由 integration-test-reviewer 审查
- quality-fixer 质量检查:返回
pass才能提交;发现桩代码会打回重做 - git commit:质量通过才允许提交
全部任务完成后,Medium/Large 规模还会追加 code-reviewer + security-reviewer 双审查,且审查建议不会自动变成新任务——由主会话判断哪些属于约定结果,其余说明理由后拒绝。
几个值得了解的关键机制:
- 🔍 需求收敛(criteria.md):
outcome必须是唯一可观测结果,不是功能清单;"加个缓存层"这类伪装成需求的方案会被单独审视 - 📐 规模分级:Small / Medium / Large 由决策数量决定。Small 直接实现、跳过文档型审查;Large 才上 PRD
- 📄 文档即交接:Work Plan 位于
docs/plans/(临时工作状态,建议加入.gitignore),而 PRD / ADR / UI Spec / Design Doc 分别住在docs/prd/、docs/adr/、docs/ui-spec/、docs/design/,应当提交 - 🎨 前端额外能力:UI 分析 + UI Spec(比如"一个组件加载中、另一个已失败时整页行为未定义"这类状态组合,会被记录并追踪到设计与测试中),加组件架构与 React Testing Library 检查
常用 recipe 速查:
| Recipe | 用途 |
|---|---|
/recipe-implement |
端到端实现(范围 → 设计 → 计划 → 实现 → 审查) |
/recipe-design → /recipe-plan → /recipe-build |
先设计后实现,可跨会话/跨成员交接 |
/recipe-diagnose |
选修复方案前先调查根因,不改代码(recipe-diagnose/SKILL.md) |
/recipe-review |
对照约定结果审查已完成的实现 |
/recipe-reverse-engineer |
从代码反推 PRD 和 Design Doc,给遗留系统补文档 |
/recipe-quality-profile |
设置仓库特有的质量规则 |
/recipe-update-doc |
需求/设计变更后更新并审查文档 |
六、真实案例:42 文件的变更为什么值得套流程
README 记录了一次真实执行:mcp-local-rag 的增量同步功能,涉及文件系统扫描、存储、CLI 和 MCP 接口共 42 个文件。其中两个细节最能说明工作流的价值:
- 独立安全审查两次把实现打回:抓到"验证之前就读文件"和"通过符号链接父目录逃逸路径边界"两个真实安全问题——这正是单会话自己写自己审最容易漏的
- 原有 Work Plan 引用的 ADR 和 Design Doc 并不存在,用户选择以 Work Plan 为权威来源后,recipe 将其拆成 13 项任务;最终 PR 明确记录了哪些功能被有意排除(watch 模式、持久化任务),排除项有据可查
小改动用不着这套火力;但跨多个职责、有真实安全面的变更,"独立审查"这一步往往物超所值。
七、常见误区与 FAQ
误区 1:所有任务都走全流程。 规模分级就是为了解决这点——Small 变更直接进 4 步任务周期,不产文档、不做文档型审查;用不上全部检查再加 lite mode。
误区 2:把工作流插件和技能插件混装。 dev-skills 与任一工作流插件共享 skill,同装会导致技能被忽略,二者只能选一。
问:测试挂了、构建挂了怎么办? 工作流会在已批准目标范围内处理测试、类型检查、lint 和构建失败,包括同一职责或契约连带需要的相邻改动。
问:docs/plans/ 要提交吗? 不要。recipe 把它视为临时工作状态,成功执行后会自动清理已消耗的 task 文件;Work Plan 可保留供审查或续建,建议 .gitignore 忽略。
问:会替我做所有决定吗? 不会。常规技术决策由 Claude 处理;只有当约定结果或排除项必须改变,或不可逆外部操作需要授权时,才会暂停等你。
八、总结:先问自己 3 个问题
- 这个变更范围是否跨职责、有没可能被 AI"顺手发现"带偏?
- 设计决策是否需要长期留档、供后续会话或同事接手?
- 交付前是否值得一次独立安全审查?
三个问题里有两个答"是",就装对应的工作流插件:纯后端 dev-workflows、纯前端 dev-workflows-frontend、全栈 dev-workflows-fullstack、只要指南 dev-skills。反之,一次性原型和边界清晰的改动,直接让 Claude Code 上就行——工具的价值,正在于它清楚自己什么时候该上场。