ZCF feat 工作流实战:从功能需求一键生成用户故事、任务拆分与测试计划
ZCF feat 工作流实战:从功能需求一键生成用户故事、任务拆分与测试计划
本篇指南围绕 ZCF 内置的 feat 工作流展开,讲解它如何把"小~中规模功能开发"从需求描述、用户故事、任务拆分推进到测试计划。读完本文,你将掌握 /feat 命令的完整用法、推荐的输入要素、规划文档的版本迭代规则,以及底层由 featPlanUx 工作流、Planner Agent 与 UI-UX-Designer Agent 共同构成的实现机制,从而在自己的项目中把功能规划做成可复用、可评审的工程流程。
feat 工作流的定位
feat 是 ZCF 为"快速规划小~中规模功能开发"设计的工作流模板。它的核心价值在于:一次调用即可把需求整理、用户故事、任务拆分与测试计划"打包生成",避免在口头讨论或零散笔记里反复对齐范围。官方文档见 feat ワークフロー,它是 ワークフロー概要 中与 ZCF 6 段階ワークフロー、BMad アジャイルフロー、Spec 拡張 并列的功能规划类工作流之一。
适合使用 feat 的典型场景:
- 明确的小型/中型功能(例如"给用户系统加评论功能"),需要在动手写代码前形成书面规划;
- 需要快速产出 Issue / PR 级别的描述文档,用于团队对齐;
- 功能涉及前端界面,希望在开发前先得到 UI/UX 设计要点。
输出内容
feat 工作流生成的规划文档固定覆盖以下五个维度(完整继承自官方文档):
- 背景・目标・非功能要求的整理:明确功能要解决的问题、成功标准,以及性能、可访问性等非功能约束;
- 用户故事与验收标准:以"作为……我希望……以便……"的形式描述需求,并给出可验证的受入基准;
- 规格摘要与 UI/UX 要点(视需要):当功能涉及界面时,输出布局、交互与视觉规范要点;
- 任务拆分与优先级:按依赖关系排定实施顺序;
- 测试计划・风险与权衡:给出验证手段,以及技术选型中的取舍说明。
从源码结构看,这份"五维输出"正是由配套的 Planner Agent 模板强制约束的:规划代理的提示词要求输出固定结构的 Markdown 文档,包括"已明确的决策""整体规划概述(项目目标/技术栈/主要阶段)""详细任务分解(每个子任务含目标、输入、输出、涉及文件、预估工作量)""需要进一步明确的问题""用户反馈区域"等章节,见 planner.md。
安装与环境前提
feat 命令不是独立脚本,而是 ZCF 初始化流程中的一项可勾选工作流,工作流 ID 为 featPlanUx。在 src/config/workflows.ts 中可以看到它的注册配置:
{
id: 'featPlanUx',
defaultSelected: true, // 默认勾选
order: 3, // 安装菜单中的顺序
skills: ['feat'], // 依赖 feat skill
agents: [
{ id: 'planner', filename: 'planner.md', required: true },
{ id: 'ui-ux-designer', filename: 'ui-ux-designer.md', required: true },
],
autoInstallAgents: true, // 自动安装两个 Agent
category: 'plan',
outputDir: 'feat',
},
从源码结构看,该配置说明了 feat 的完整依赖闭包:
- skill:
feat命令本身,模板源文件为 feat/SKILL.md(en) 与 feat/SKILL.md(zh-CN),通过disable-model-invocation: true声明只能由用户显式调用,不会被模型自动触发; - agents:
planner(任务拆解规划代理)与ui-ux-designer(UI 设计代理)均为required: true,安装器在 src/utils/workflow-installer.ts 中会把二者复制到~/.claude/agents/zcf/plan/目录(CLAUDE_DIR即~/.claude,定义见 src/constants.ts); - skill 安装通道:src/utils/skills-installer.ts 中
installSkills()通过npx -y skills add <skillsPath> -y -g调用 skills CLI 完成全局安装,对claude-code工具同时注册claude-code与universal两个 agent 目标,对codex工具则注册codex,因此feat同时支持 Claude Code 与 Codex 两种宿主环境。
测试用例 tests/config/workflows.test.ts 与 tests/unit/commands/init.test.ts 也验证了 featPlanUx 位于五大默认工作流(commonTools、sixStepsWorkflow、featPlanUx、gitWorkflow、bmadWorkflow)之中,属于默认选中的初始化项。
基本用法
在已安装 feat skill 的项目中,直接在 Claude Code / Codex 会话里输入命令:
/feat Add user comment feature
命令参数(skill 模板中的 $ARGUMENTS)就是你的一句话需求描述。为了让生成质量最大化,官方文档建议在参数中补充以下信息:
| 补充信息 | 示例 | 作用 |
|---|---|---|
| 范围上限 | "本次仅做展示,投稿功能放下一个 Sprint" | 防止规划发散,锁定非目标 |
| 既有 API / DB 模型约束 | "评论表已存在,仅有 user_id、content 字段" | 让任务拆分贴合现有数据模型 |
| 性能与安全要求 | "列表页首屏 < 200ms;评论内容需 XSS 过滤" | 落入非功能要求与测试计划 |
参数越具体,Planner Agent 在"需要进一步明确的问题"章节中留下的待决问题就越少,规划文档可直接进入评审的概率越高。
底层机制:三类输入的判断与分支处理
feat skill 的完整指令见 feat/SKILL.md(zh-CN)。它的核心是一套"先判断类型、再分类处理"的工作流:
1. 输入类型判断
每次收到输入,skill 会先做一次类型识别并明确告知用户,判断标准有三类:
- 需求规划类型:用户提出新功能需求、项目构想或需要制定计划;
- 讨论迭代类型:用户要求继续讨论、修改或完善已有规划;
- 执行实施类型:用户确认规划完成,要求开始具体实施。
强制响应要求是:每次交互必须首先说明"我判断此次操作类型为:[具体类型]"。这一约定让多轮会话中的行为可预期、可审计。
2. 分支 A:需求规划处理
识别为功能需求输入后:
- 启用 Planner Agent;
- 生成详细的 Markdown 规划文档;
- 文档存储至
./.claude/plan目录,以plan/xxx.md格式命名; - 文档包含:目标定义、功能分解、实施步骤、验收标准。
3. 分支 B:讨论迭代处理
当用户要求继续讨论或修改规划时:
- 检索并分析上次生成的规划文件;
- 识别用户反馈和确认内容;
- 重新启用 Planner Agent 生成新文档,版本规则为:上一次是
plan/xxx.md,本次生成plan/xxx-1.md;上一次是plan/xxx-1.md,本次生成plan/xxx-2.md,依此类推; - 重新组织待实施任务的优先级。
这套递增后缀的命名规则(如 feat-comment.md → feat-comment-1.md → feat-comment-2.md)使得规划的每次修订都有独立的版本文件,天然形成评审留痕。
4. 分支 C:执行实施处理
用户确认规划完成后:
- 按规划文档顺序启动任务执行;
- 每个子任务开始前先做任务类型识别;
- 前端任务特殊处理:检查是否存在可用 UI 设计;如无设计方案,必须调用 UI-UX-Designer Agent,先完成 UI 设计再进入开发实施。
5. 状态管理与质量保证
skill 还定义了贯穿执行期的状态管理机制与四条质量保证要点:
- 维护任务完成状态跟踪,及时更新规划文档状态,保证用户对进度的可见性;
- 类型判断准确性:每次交互开始的类型识别必须准确;
- 文档一致性:规划文档与实际执行保持同步;
- 依赖关系管理:特别关注前端任务的 UI 设计依赖;
- 用户沟通透明:所有判断和动作都要明确告知用户。
两个配套 Agent 的职责边界
featPlanUx 工作流为 feat 挂载了两个必备 Agent,二者职责严格分离:
Planner Agent(planner.md)定位为"项目规划和任务分解专家",采用 WBS(工作分解结构)方法把复杂任务分解为 3-4 个主要阶段,每个子任务定义清晰的输入、输出、验收标准与可能改动的文件;遇到不确定的技术选型时不擅自决策,而是写入"需要进一步明确的问题"章节并列出推荐方案(方案 A/B 及优缺点),等待用户选择。模板中特别强调:只返回 Markdown 文档内容,不执行任何任务。
UI-UX-Designer Agent(ui-ux-designer.md)仅在功能涉及界面时被 Planner 引用。其输出格式固定为"设计分析 → ASCII 布局草图 → 设计规范(组件层次、颜色/排版/间距令牌、交互设计、可访问性、响应式)",并且"只负责提供设计规范和建议,不执行具体的开发任务"。Planner 模板中有一条硬规则:如果子任务涉及页面样式,必须先用 ui-ux-designer agent 得到响应后,再将其整合进子任务描述。
从安装路径看(~/.claude/agents/zcf/plan/planner.md、~/.claude/agents/zcf/plan/ui-ux-designer.md),二者按 zcf/plan 分类目录管理,与其他工作流的 Agent 隔离存放,避免命名冲突。
与 /workflow 组合:从规划到六阶段交付
官方最佳实践建议把 feat 的产出作为入口,再与 /workflow 组合,发展出更详细的设计与测试计划。/workflow 是 ZCF 的另一条工作流(skill 模板见 workflow/SKILL.md),它执行严格的六阶段序列:
Research -> Ideate -> Plan -> Execute -> Optimize -> Review
两者优先级互补:/feat 解决"这个功能值不值得做、边界在哪、拆成哪些任务",/workflow 解决"每一步怎么写、写完如何优化与评审"。典型衔接方式是:把 feat 生成的任务拆分与验收标准作为 /workflow 在 Research 阶段的输入,直接跳过需求澄清环节。此外 /workflow 有自己的文档落盘约定——执行计划存入项目根目录 .zcf/plan/current/task-name.md,任务完成后归档到 .zcf/plan/history/ 并以 [完成时间]task-name.md 重命名,与 feat 的 ./.claude/plan/plan/xxx.md 版本文件共同构成"规划留痕"体系。
最佳实践
综合官方文档与 skill 模板,推荐按以下方式使用 feat:
- 规划文档直接用于协作:把生成结果粘贴进 Issue / PR 描述,快速达成团队共识;其中"已明确的决策"与"需要进一步明确的问题"两章天然适合作为评审检查单。
- 利用版本迭代规则做多轮评审:评审反馈后不要口头改,而是再次触发"讨论迭代",让 skill 生成
plan/xxx-1.md新版本,保留决策轨迹。 - 大功能拆多个 Feat:大型功能拆成多个
feat单元,按优先级顺序逐个规划、逐个实施,避免单一规划文档膨胀失控。 - 前端功能先设计后编码:涉及界面时,坚持 skill 中的硬约束——先由 UI-UX-Designer Agent 产出 ASCII 布局草图与设计规范,再进入 Execute。
- 参数里写明非目标:把"本次不做 X"写进
/feat参数(范围上限),是抑制规划发散成本最低的手段。
版本注意:旧版文件清理机制
值得注意的是,src/utils/workflow-installer.ts 中的 cleanupOldVersionFiles() 在安装前会清理早期版本的遗留文件,包括 ~/.claude/commands/feat.md、~/.claude/agents/planner.md 与 ~/.claude/agents/ui-ux-designer.md 等旧路径。这说明 feat 已从早期的"命令文件 + 根目录 Agent"结构迁移到当前的"skills CLI 安装 + zcf/plan 分类 Agent"结构。若你从旧版本升级 ZCF,重新运行初始化并勾选 featPlanUx 工作流即可自动完成迁移,无需手动处理旧文件。
相关文件索引
| 内容 | 路径 |
|---|---|
| 官方文档(本文主体来源) | docs/ja-JP/workflows/feat.md |
| feat skill 模板(英/中) | templates/skills/en/feat/SKILL.md、templates/skills/zh-CN/feat/SKILL.md |
| 工作流注册配置 | src/config/workflows.ts |
| 工作流安装器(含旧文件清理) | src/utils/workflow-installer.ts |
| skills CLI 安装封装 | src/utils/skills-installer.ts |
| Planner / UI-UX-Designer Agent 模板 | planner.md、ui-ux-designer.md |
| /workflow 六阶段 skill | templates/skills/en/workflow/SKILL.md |
| 工作流配置测试 | tests/config/workflows.test.ts |