ZCF 功能开发工作流(feat)深度指南:从需求分析到实施计划的完整规划闭环
ZCF 功能开发工作流(feat)深度指南:从需求分析到实施计划的完整规划闭环
本文以 ZCF 项目中预置的功能开发工作流(/feat)为核心,系统讲解其在 Claude Code 中的使用方法、四个核心阶段(需求确认→方案规划→UI/UX 支撑→实施计划)、内置 Planner 与 UI/UX Designer 代理的协作机制,并结合仓库源码(工作流配置、安装逻辑、SKILL 模板)揭示其底层实现原理。读完本文,你将掌握如何在编码前用 /feat 完成一次结构化、可落地、可评审的新功能规划,并懂得如何将其与六阶段工作流、Git 工作流串联成完整开发闭环。
功能概述:一款面向新功能的"规划先行"工作流
功能开发工作流(feat)是 ZCF(Zero-Config Code Flow)预置的五套工作流之一,面向新功能设计与实现,通过结构化的阶段流程,帮助开发者在编码前系统化地完成从需求分析到实施计划的完整过程,确保功能开发的质量和完整性。它不同于执行型的六阶段工作流(/workflow),定位在"想清楚再动手"——先把需求、方案、界面与任务清单固化下来。
核心特点
- 🎯 需求驱动:从需求分析开始,确保功能符合用户期望
- 📐 多方案设计:生成多个可行方案并评估优劣
- 🎨 UI/UX 支持:提供专业的 UI/UX 设计建议
- 📋 详细计划:输出可执行的任务分解和实施计划
- 🤖 专业代理:内置规划师(Planner)和 UI/UX 设计师(UI/UX Designer)代理
使用方法
Claude Code
在 Claude Code 中直接输入斜杠命令即可触发(命令注册在 SKILL 模板的 frontmatter 中,见 templates/skills/zh-CN/feat/SKILL.md):
/feat <功能描述>
示例:
/feat 实现用户评论功能,支持点赞、回复和删除
Codex(暂不支持)
⚠️ 注意:功能开发工作流(feat)目前仅在 Claude Code 中提供,Codex 暂不支持此工作流。
如果需要类似功能,可以在 Codex 中使用 /prompts:workflow 六阶段工作流来实现功能开发任务。这一点与 docs/zh-CN/workflows/index.md 中"Codex 目前仅支持六阶段工作流和 Git 工作流"的说明一致。
安装与底层实现:feat 工作流是如何被部署的
在介绍使用细节之前,有必要从源码层面理解 /feat 是如何进入你的 Claude Code 环境的,这有助于排查"命令不生效"等问题。
工作流注册表:featPlanUx 配置项
ZCF 的所有工作流都登记在 src/config/workflows.ts 的 WORKFLOW_CONFIG_BASE 常量中。与 feat 对应的是 featPlanUx 配置项(默认选中、排序第 3):
{
id: 'featPlanUx',
defaultSelected: true,
order: 3,
skills: ['feat'],
agents: [
{ id: 'planner', filename: 'planner.md', required: true },
{ id: 'ui-ux-designer', filename: 'ui-ux-designer.md', required: true },
],
autoInstallAgents: true,
category: 'plan',
outputDir: 'feat',
}
其中 skills: <a href="https://link.gitcode.com/i/4f752c7a40311681bf75680175ef4599" target="_blank">'feat'] 声明了本工作流依赖的 skill 指令文件,agents 声明了两个**必需(required: true)**的代理,autoInstallAgents: true 表示这些代理会在安装工作流时自动部署。i18n 文案中该工作流的名称为"功能规划和 UX 设计 (feat + planner + ui-ux-designer)",见 [src/i18n/locales/zh-CN/workflow.json。
安装链路:zcf init / zcf update 与代理复制
selectAndInstallWorkflows 是工作流安装的入口(src/utils/workflow-installer.ts),由 zcf init 在初始化流程中调用(src/commands/init.ts 中 options.workflows !== false 时执行),zcf update 在模板更新后也会再次执行导入。
针对 feat 工作流,安装过程做两件事:
- 安装 skill:从
templates/skills/{lang}/feat/SKILL.md读取模板,通过npx -y skills add安装到全局 skills 目录(src/utils/skills-installer.ts 中CODE_TOOL_TO_SKILLS_AGENTS为 claude-code 配置了claude-code与universal两个 agent 标识); - 自动复制代理:当
autoInstallAgents为 true 时,把templates/claude-code/{lang}/workflow/plan/agents/planner.md与ui-ux-designer.md复制到~/.claude/agents/zcf/plan/目录,并在终端打印已安装代理: zcf/plan/xxx.md。
安装前还会执行 cleanupOldVersionFiles(),清理旧版本遗留的 ~/.claude/commands/feat.md、~/.claude/agents/planner.md 等文件,避免新旧结构冲突。以上行为均有测试用例覆盖(tests/unit/utils/workflow-installer.test.ts 中验证了旧文件清理、skills 安装、代理复制等逻辑)。
工作流阶段
功能开发工作流包含四个核心阶段,下面逐一展开其目标、AI 行为与输出。
1. 需求确认
目标:深入理解功能需求和业务场景
AI 行为:
- 分析功能描述和用户需求
- 识别功能范围和边界
- 确定成功标准和验收条件
- 理解业务价值和用户场景
输出:
- 功能需求文档
- 用户故事
- 验收标准
- 成功指标
示例输出:
- 功能范围:用户评论、点赞、回复、删除
- 用户角色:普通用户、管理员
- 验收标准:用户可以发布评论、点赞他人评论、回复评论、删除自己的评论
2. 方案规划
目标:生成多个可行的技术方案并评估
AI 行为:
- 提出 2-3 个不同的技术方案
- 评估各方案的技术复杂度
- 分析方案的可扩展性和维护性
- 考虑性能、安全性和成本因素
- 推荐最适合的方案
输出:
- 多个技术方案
- 方案对比分析
- 技术选型建议
- 架构设计草图
示例输出:
- 方案 A:使用现有数据库表结构,简单快速
- 方案 B:引入评论树结构,支持无限嵌套回复
- 方案 C:使用图数据库,支持复杂关系查询
- 推荐:方案 B(平衡了复杂度和功能完整性)
3. UI/UX 支撑
目标:提供专业的用户界面和交互设计建议
AI 行为:
- 设计用户界面布局
- 提供交互流程建议
- 生成线框图和原型建议
- 编写界面文案和提示语
- 考虑用户体验和易用性
输出:
- UI 设计建议
- 交互流程图
- 界面线框图描述
- 文案和提示语
- 响应式设计考虑
示例输出:
- 评论列表布局:时间倒序、头像+昵称+内容
- 交互流程:点击回复 → 显示回复框 → 输入内容 → 提交
- 文案:"发表评论"、"回复"、"点赞(123)"
4. 实施计划
目标:输出详细的任务分解和实施计划
AI 行为:
- 将功能拆解为具体开发任务
- 确定技术实现细节
- 制定开发顺序和依赖关系
- 估算开发工作量
- 提供测试策略
输出:
- 详细任务列表
- 技术实现细节
- 开发时间估算
- 测试计划
- 部署考虑
示例输出:
- 创建评论数据模型(2 小时)
- 实现评论 API 接口(4 小时)
- 开发前端评论组件(3 小时)
- 实现点赞功能(2 小时)
- 实现回复功能(3 小时)
- 实现删除功能(1 小时)
- 编写测试用例(2 小时)
- 性能优化(1 小时)
输入分类机制:feat 的三种处理模式
从源码级看,feat 并不仅仅是"输出一份规划"的静态模板。其核心指令(templates/skills/zh-CN/feat/SKILL.md)要求 AI 每次收到用户输入时先做类型判断并明确告知用户,再按三类分别处理:
A. 需求规划处理
触发条件:识别为功能需求输入(新功能需求、项目构想、需要制定计划)。
执行动作:
- 启用 Planner Agent
- 生成详细的 Markdown 规划文档
- 将文档存储至
./.claude/plan目录,并以plan/xxx.md的格式命名 - 文档包含:目标定义、功能分解、实施步骤、验收标准
B. 讨论迭代处理
触发条件:用户要求继续讨论、修改或完善已有规划。
执行动作:
- 检索并分析上次生成的规划文件
- 识别用户反馈和确认内容
- 启用 Planner Agent
- 生成新的规划文档,文件名按序号递增:上一次是
plan/xxx.md,这次就是plan/xxx-1.md;上一次是plan/xxx-1.md,这次就是plan/xxx-2.md,以此类推(保留历史版本,不覆盖) - 重新组织待实施任务优先级
C. 执行实施处理
触发条件:用户确认规划完成,要求开始具体实施。
执行动作:
- 按规划文档顺序启动任务执行
- 每个子任务开始前进行任务类型识别
- 前端任务特殊处理:
- 检查是否存在可用的 UI 设计
- 如无设计方案,必须使用 UI/UX Designer Agent
- 完成 UI 设计后再进行开发实施
这一分类机制意味着同一个 /feat 命令可以承载"规划→讨论→实施"的完整生命周期,而非一次性问答。
关键执行原则与质量保证
SKILL 指令还对 AI 的行为约束提出了明确要求(同样可在 templates/skills/zh-CN/feat/SKILL.md 中核对):
关键执行原则
- 强制响应要求:每次交互必须首先说明"我判断此次操作类型为:[具体类型]",类型判断必须准确且明确传达给用户
- 任务执行规范:严格按照文档化规划执行;子任务启动前必须明确任务性质和依赖关系;前端任务必须确保 UI 设计完整性
- 状态管理机制:维护任务完成状态跟踪;及时更新规划文档状态;确保用户对进度的可见性
质量保证要点
- 类型判断准确性:每次交互开始的类型识别必须准确
- 文档一致性:规划文档与实际执行保持同步
- 依赖关系管理:特别关注前端任务的 UI 设计依赖
- 用户沟通透明:所有判断和动作都要明确告知用户
两大内置代理:Planner 与 UI/UX Designer
feat 工作流的专业度来自两个预置代理,其提示词模板存放在 templates/claude-code/zh-CN/workflow/plan/agents/ 下。
Planner:任务拆解规划专家
Planner 代理(planner.md)被定义为"专业的项目规划和任务分解专家",核心职责包括:
- 深度分析任务:理解核心目标、约束条件和成功标准
- 系统性拆解:运用 WBS(工作分解结构)方法分解子任务
- 优先级排序:按依赖关系、重要性和紧急程度排序
- 风险识别:预见技术难点、资源瓶颈并提供应对策略
- 资源评估:估算每个步骤的时间、技能和工具资源
它的输出被严格限定为结构化 Markdown 规划文档,固定结构包含:已明确的决策、整体规划概述(项目目标 / 技术栈 / 主要阶段 / 详细任务分解,每个任务带目标、输入、输出、涉及文件、预估工作量)、需要进一步明确的问题(给出推荐方案、等待用户选择)、用户反馈区域。特别值得注意的是:当子任务涉及页面样式时,Planner 必须调用 ui-ux-designer agent,将设计响应合并进子任务描述。它"只返回文档内容,不执行任何开发任务",并遵循"避免过度复杂规划、注意代码复用、可测试可验证"的务实原则。
UI/UX Designer:界面与交互设计专家
UI/UX Designer 代理(ui-ux-designer.md)负责提供符合项目 UI 框架标准的界面与交互设计建议,其输出必须包含固定结构:
- 设计分析:分析当前状态和改进机会
- 布局草图:ASCII 布局图,直观展示组件位置和层次关系
- 设计规范:组件层次结构、颜色方案、排版系统、间距系统、组件规范
- 交互设计:交互状态、动画效果和用户反馈
- 可访问性考虑:对比度、焦点管理、键盘导航等
- 响应式设计:不同窗口尺寸下的布局适配
同样,"它只负责提供设计规范和建议,不执行具体的开发任务",输出会被上层 agent 整合进项目规划——这正是前文"执行实施处理"中前端任务先设计后开发的实现支撑。
使用场景
场景 1:新功能开发
/feat 添加购物车功能,支持多商品、数量修改和批量结算
适合需要完整规划的新功能,从需求到实施的完整流程。
场景 2:功能增强
/feat 增强用户个人中心,添加数据统计和活动历史展示
适合在现有功能基础上的增强和扩展。
场景 3:复杂业务逻辑
/feat 实现订单系统,支持多种支付方式、优惠券和物流跟踪
适合包含复杂业务逻辑的功能,需要仔细规划和技术选型。
最佳实践
1. 需求描述要清晰
提供清晰、详细的功能描述可以获得更好的规划结果:
# 好的描述
/feat 实现用户评论功能,支持文本、图片、点赞、回复、删除,管理员可以审核和删除任何评论
# 不够清晰的描述
/feat 评论功能
2. 结合项目上下文
在执行功能开发工作流前,建议先初始化项目配置:
# 1. 初始化项目(如果还没做)
/init-project
# 2. 执行功能开发工作流
/feat <功能描述>
这样可以确保功能设计与项目整体架构一致。/init-project 来自 commonTools 工作流(skills: ['init-project'],见 src/config/workflows.ts)。
3. 规划完成后执行
功能开发工作流的输出可以直接用于后续开发:
# 1. 使用功能开发工作流规划
/feat 实现用户评论功能
# 2. 根据规划结果,使用六阶段工作流实施
/workflow 实现评论的数据模型和 API 接口
# 3. 继续实施其他任务
/workflow 实现评论的前端组件和交互
# 4. 使用 Git 工作流提交
/git-commit
4. 与其他工具结合
将规划结果同步到项目管理工具:
- 📋 Issue 追踪:将任务分解同步到 GitHub Issues 或 Jira
- 📝 文档管理:将方案设计保存到项目文档
- 👥 团队协作:与团队成员分享规划结果
- 🔄 迭代管理:将功能规划纳入迭代计划
5. 持续迭代
功能开发是一个持续的过程,配合前文所述的"讨论迭代处理"机制(规划文件按 xxx-1.md、xxx-2.md 递增命名),可以多轮细化:
# 第一轮:整体规划
/feat 实现用户评论功能
# 第二轮:细化某个子功能
/feat 实现评论的回复功能,支持嵌套回复和@提醒
# 第三轮:优化和增强
/feat 优化评论性能,支持分页加载和实时更新
与其他工作流的区别
| 工作流 | 适用场景 | 特点 |
|---|---|---|
功能开发工作流 (/feat) |
新功能规划 | 需求分析、方案设计、UI/UX 规划 |
六阶段工作流 (/workflow) |
具体实施 | 完整开发流程,从研究到评审 |
BMad 工作流 (/bmad-init) |
企业级项目 | 完整团队协作和迭代管理 |
三者定位互补:/feat 负责"规划什么",/workflow 负责"如何落地",/bmad-init 负责"团队化、规模化地迭代管理"。工作流整体概览可参考 docs/zh-CN/workflows/index.md。
注意事项
Codex 不支持
功能开发工作流目前仅在 Claude Code 中提供。如果使用 Codex,可以使用六阶段工作流替代:
# Codex 中使用六阶段工作流替代
/prompts:workflow 实现用户评论功能
代理依赖
功能开发工作流依赖以下代理:
- Planner:规划师代理,负责方案设计
- UI/UX Designer:UI/UX 设计师代理,负责界面设计
这些代理会在工作流初始化时自动安装到 ~/.claude/agents/zcf/plan/(对应配置中 autoInstallAgents: true 与 agents 字段,见 src/config/workflows.ts)。代理类型定义在 src/types/workflow.ts 中。
规划结果使用
功能开发工作流输出的规划结果应该:
- ✅ 保存文档:将规划文档保存到项目目录(
./.claude/plan/) - ✅ 版本控制:纳入 Git 版本控制
- ✅ 团队共享:与团队成员分享
- ✅ 持续更新:根据实施情况更新规划
相关资源
💡 提示:功能开发工作流是规划新功能的理想工具。通过结构化的需求分析、方案设计和实施计划,可以确保功能开发的质量和完整性。建议在开始编码前先使用功能开发工作流进行完整规划——先想清楚"做什么、怎么做、界面长什么样、任务怎么拆",再用
/workflow逐步落地,最后用/git-commit完成提交,形成"规划→实施→提交"的完整闭环。