1. 项目概述从模糊需求到清晰蓝图的工程化技能在软件开发或产品设计领域我们最常听到的抱怨是什么——“需求不清晰”。产品经理丢过来一句话描述业务方给出一堆模糊的期望开发团队一头雾水地开始编码最终交付时才发现“这不是我想要的”。这种场景每天都在上演它不仅消耗团队士气更直接导致项目延期、成本超支和产品质量低下。SwiftyJourney/requirements-engineering-skill正是为了解决这个核心痛点而生。这不是一个简单的工具库或模板而是一套内置于 Claude Code、Cursor 等智能编码助手Agent中的“工程化需求分析”技能。它的核心价值在于将“需求工程”这个看似主观、依赖个人经验的活动转化为一套结构化、可重复、可验证的标准化流程。简单来说它教会你的 AI 助手如何像一个经验丰富的系统分析师或技术负责人那样思考把一句模糊的“用户能登录”拆解成包含行为驱动开发BDD叙述、验收标准、用例、数据模型、接口契约乃至流程图的完整技术规格说明书。这套方法论源自 Essential Developer 的实战精华尤其在其广受好评的 iOS Lead Essentials 课程中得到了充分验证。它不只是“写文档”而是建立一种“活着的规范”——需求与代码同步演进每一个功能块都具备完整的可追溯性。无论你是需要向团队明确需求的产品经理还是渴望在编码前获得清晰指引的开发者或是负责协调各方的技术负责人掌握这套技能都能让你从“被动接收需求”转变为“主动定义和澄清需求”从根本上提升协作效率和交付质量。2. 核心方法论与七大产出物解析2.1 需求工程的六步标准化流程这套技能将需求澄清过程标准化为六个可操作的步骤每一步都旨在将模糊性转化为确定性。第一步识别Identify这不仅仅是“看到需求”而是训练一种敏感性能快速从对话、文档或会议记录中嗅出“模糊的味道”。典型的模糊需求信号包括大量使用“应该”、“可能”、“方便地”等不确定性词汇描述功能而非具体行为如“提升用户体验”缺乏明确的行为主体和成功标准。在这一步你需要做的是标记出这些模糊点而不是试图立即解决它们。第二步澄清Clarify这是整个流程中最具“人味”的一步需要运用经典的5W1HWho, What, Where, When, Why, How提问法进行深入挖掘。例如面对“用户能管理个人资料”这个需求你需要追问Who:是注册用户还是所有访客有没有管理员角色What:“管理”具体指什么查看、编辑、上传头像、删除账户Where:在哪个页面或模块进行管理When:是随时可操作还是需要满足某些前置条件如邮箱已验证Why:用户为什么要做这个操作背后的业务目标是什么How:操作的具体流程是怎样的有没有异常情况通过这一系列提问你将收集到构建精确规格所需的所有原始信息。第三步用BDD定义行为Specify BDD在澄清的基础上我们开始进行结构化输出。行为驱动开发BDD框架在这里扮演了关键角色。它要求我们从不同用户角色的视角用“叙事”的方式描述功能价值。一个完整的BDD叙事通常遵循“作为一个[角色]我想要[功能]以便于[商业价值]”的格式。紧接着便是用“Given-When-Then”语法编写验收标准这些标准本质上是可自动化的测试用例为后续开发提供了不可辩驳的通过标准。第四步定义用例Define Use CasesBDD描述了“做什么”和“为什么”而用例则详细规定了“怎么做”。一个健壮的用例不仅包含成功的主流程Happy Path还必须涵盖各种异常流程Error Courses和取消流程Cancel Courses。特别是“取消流程”这是Essential Developer方法论中强调的一个关键模式。对于任何异步操作如网络请求、文件上传都必须明确用户如何取消、取消后系统状态如何回滚这直接关系到系统的健壮性和用户体验。第五步建模与契约Model Contract至此需求的行为层面已经清晰。接下来需要深入到数据层面和协作层面。“模型规格”用于精确定义领域实体通常以属性/类型表格的形式呈现明确每个字段的名称、数据类型、约束条件和是否可选。“负载契约”则定义了系统间尤其是前后端的通信协议明确API的端点、HTTP方法、请求/响应体的JSON结构。这一步的输出物是开发者和测试人员最直接的编码和测试依据。第六步可视化与归档Visualize Document最后将前五步的文本信息转化为视觉图表。流程图可以清晰地展示用户操作和系统判断的逻辑分支架构图则描绘了系统内部模块的依赖关系。将这些图表与之前的文本规格整合便形成了一份完整的“功能规格说明书”。这份文档是活的会随着迭代不断更新确保文档与代码永不脱节。2.2 七大规格产出物详解与实战示例下面我们以一个具体的例子——“用户通过邮箱和密码登录”——来逐一拆解这七大产出物看看它们如何将一句话需求具象化。1. BDD叙事与验收标准这是需求的“用户故事”和“测试合同”。叙事“作为一名未登录的访客我想要通过输入邮箱和密码登录我的账户以便于访问我的个人数据和专属功能。”验收标准示例场景使用有效凭证登录Given 用户位于登录页面And 输入了已注册的邮箱userexample.comAnd 输入了正确的密码When 用户点击“登录”按钮Then 系统应验证凭证And 导航至用户主页And 在界面显示“登录成功”提示场景使用错误密码登录Given 用户位于登录页面And 输入了已注册的邮箱And 输入了错误的密码When 用户点击“登录”按钮Then 系统应显示“邮箱或密码错误”提示And 用户仍停留在登录页面2. 用例用例详细描述了系统的行为流。以“登录”主用例为例其步骤可能包括1. 用户输入邮箱2. 用户输入密码3. 用户提交表单4. 系统验证输入格式5. 系统调用认证服务6. 系统处理响应成功则创建会话并跳转失败则显示错误。同时必须定义“取消课程”例如在系统验证过程中用户点击了“取消”按钮系统应中止验证流程并清空表单。3. 模型规格定义“用户”模型在此上下文中的相关属性。属性名类型约束说明emailString必填 格式验证用户注册邮箱passwordString必填 长度8用户密码前端传输时应为哈希值loginAttemptCountInt可选 默认0用于记录连续失败次数防止暴力破解4. 负载契约定义登录API的接口。端点POST /api/v1/auth/login请求体{ email: string, password: string }成功响应 (200 OK):{ token: jwt.access.token.string, user: { id: 123, email: userexample.com, name: John Doe } }失败响应 (401 Unauthorized):{ error: { code: INVALID_CREDENTIALS, message: 邮箱或密码错误 } }5. 流程图用流程图描绘登录过程的决策逻辑包括输入验证、认证请求、成功/失败分支、以及取消操作的处理节点。这能帮助所有成员快速理解业务逻辑全貌。6. 架构图展示登录功能涉及的模块如LoginViewController(UI) -LoginUseCase(业务逻辑) -AuthService(网络请求) -TokenManager(本地存储)。明确模块间的依赖方向如单向依赖这对于维护清晰的架构至关重要。这七大产出物共同构成了一份360度无死角的功能规格确保了从业务语言到技术实现的无损转换。3. 技能集成与多智能体开发环境实操3.1 安装与配置一键注入分析能力requirements-engineering-skill的设计理念是“无缝集成”它通过skills.sh这个技能管理平台进行分发和安装。无论你使用哪种兼容的智能编码助手安装过程都极其简单。在你的项目根目录或任意工作空间打开终端执行以下命令npx skills add SwiftyJourney/requirements-engineering-skill这条命令会从技能仓库拉取最新的技能定义文件并将其安装到你的本地技能目录中。安装完成后你的AI助手如Claude Code、Cursor在分析代码或处理需求时就能自动调用这套需求工程的方法论和提示模板。注意确保你的开发环境已安装Node.js和npm/npx因为skills.sh是基于此的工具链。对于公司内网环境可能需要配置镜像源或权限。3.2 主流智能编码助手兼容性指南该技能遵循通用的skills/约定因此兼容性很广。以下是针对不同助手的具体表现和优化使用建议1. Claude Code作为技能的原生优化平台集成度最高。安装后当你与Claude Code讨论需求时可以直接使用诸如“为‘购物车结算’功能创建BDD叙事和验收标准”或“根据这段模糊描述生成完整的用例”等指令。Claude Code会理解上下文并按照技能定义的模板和逻辑结构输出内容。你可以通过提及技能来更精确地调用。2. CursorCursor以其强大的代码理解和生成能力著称。集成此技能后其优势在于能将生成的需求规格与现有代码库进行关联分析。例如你可以要求它“基于UserAuthentication模块的现有代码为‘密码重置’功能补全模型规格和API契约。” Cursor可以分析现有代码风格和数据结构生成风格一致、可直接整合的规格。3. GitHub CopilotCopilot更侧重于代码片段补全。虽然它也能响应自然语言指令但使用此技能时建议提出更具体、更结构化的请求。例如与其说“写登录的需求”不如说“遵循Essential Developer方法论生成一个包含BDD、用例和错误处理的登录功能规格”。Copilot会利用技能中的模式来生成更规范的输出。4. WindsurfWindsurf等其他兼容Agent的使用方式类似。关键在于安装技能后你相当于为所有助手统一注入了一套标准化的“需求分析思维框架”。这能确保在不同工具、不同项目甚至不同团队成员之间产出的需求文档格式和质量是统一和可预期的。3.3 技能文件结构与自定义扩展安装后技能的文件结构清晰地展现在你面前。SKILL.md是技能的总入口和说明文档。而references/目录下的系列Markdown文件则是技能的“知识库”和“模板库”。bdd-narratives.md: 存放BDD的详细写作指南和示例。use-cases.md: 详细说明用例的四种课程Data/Primary/Error/Cancel写法。model-specs-and-contracts.md: 提供模型规格表格和JSON契约的模板。diagrams.md: 可能包含生成流程图、架构图的文本描述语法如Mermaid语法指南。domain-language.md: 强调统一领域语言的重要性。feature-specification-workflow.md: 端到端的工作流指南。实操心得不要仅仅将这套技能视为黑盒。高级用法是将其作为模板基础进行自定义扩展。例如你可以在references/目录下为你的团队添加一个our-company-guidelines.md文件里面定义你们公司特有的API响应格式标准、安全规范要求等。然后修改SKILL.md将你的自定义指南链接进去。这样当AI助手生成规格时就会同时遵循通用方法论和你们团队的具体规范产出更贴合实际的结果。4. 关键模式深度解读与避坑指南4.1 “取消课程”为异步世界设计的健壮性核心在传统的需求分析中我们往往过度关注“成功路径”而将取消、超时、中断等视为边缘情况。Essential Developer方法论将“取消课程”提升为一级公民这是一个极具远见的设计。为什么“取消课程”如此重要在现代交互式应用尤其是移动端和富客户端应用中用户随时可能中断操作切换应用、点击返回、锁屏、网络切换。如果一个文件上传请求无法取消用户就只能干等着或强制关闭应用。如果一个导航请求无法取消在快速切换页面时就会引发状态混乱。缺乏取消机制的需求是不完整的会导致代码充满漏洞和僵尸任务。如何在规格中定义“取消课程”在用例描述中你需要明确取消的触发点在哪个步骤用户可以取消例如“在系统验证凭证过程中用户点击了‘取消’按钮”。系统的取消响应系统必须执行哪些清理动作例如“中止正在进行的网络请求”、“清空密码输入框”、“恢复界面至可交互状态”。状态的一致性取消后系统的业务状态和UI状态必须回滚到一个明确的、一致的点通常是操作开始前的状态。避坑指南最常见的错误是只在UI层处理取消如隐藏加载动画但后台的网络请求或计算任务仍在继续。在规格中必须明确要求“取消操作必须向后台任务发送取消信号并确保资源被正确释放”。这通常会驱动开发者在设计接口时就考虑为UseCase或Service注入CancellationToken之类的机制。4.2 关注点分离从巨型用例到精准职责另一个关键模式是“关注点分离”。它反对编写一个庞大的、无所不包的“用户管理用例”而是鼓励将其拆分为多个单一职责的用例例如LoadUserProfileUseCase、ValidateUserInputUseCase、CacheUserDataUseCase、UpdateUserRemoteUseCase。这样做的好处是什么可测试性每个小用例只做一件事输入输出明确单元测试极其容易编写。可复用性ValidateUserInputUseCase既可以在注册时用也可以在编辑资料时用。可维护性当验证逻辑需要修改时你只需改动一个独立的用例不会牵一发而动全身。清晰的架构这天然地导向了清晰的分层架构如Clean Architecture用例Use Case成为协调业务规则的核心单元。在需求规格中如何体现在撰写用例时如果发现一个用例的描述超过了10个步骤或者包含了“先做A如果成功再做B同时还要处理C”这种复杂逻辑就应该考虑拆分。在规格文档中你可以通过“子用例”或“用例组合”的方式来描述。例如“注册用例”会组合调用“验证邮箱格式用例”、“检查邮箱唯一性用例”和“创建用户用例”。4.3 领域语言对齐与“活着的规范”“领域语言对齐”要求业务、产品、开发、测试使用同一套词汇表。在需求规格中如果一个概念在BDD叙事里叫“购物车”在模型规格里叫“购物篮”在API契约里叫Cart在数据库里叫basket混乱就产生了。实践方法在项目启动或每个迭代初期由技术负责人或架构师牵头在domain-language.md中维护一份术语表。所有规格文档都必须引用并遵循这份术语表。AI助手在生成内容时也会基于此来保持一致性。而“活着的规范”是这一套方法的终极目标。它意味着需求规格不是一次性的、签完字就扔进档案柜的文档。它应该与代码仓库一起管理随着每次功能迭代而更新。理想状态下每当你修改一个功能的验收标准Given-When-Then对应的自动化测试代码也应该同步更新并且CI/CD流水线会运行这些测试来验证“规范”是否仍然被满足。这样规格文档就成为了系统行为的唯一可信来源。5. 端到端实战从模糊需求到完整规格让我们通过一个更复杂的例子串联起整个工作流。假设你收到这样一个需求“我们需要一个文章打赏功能让读者可以给作者一点鼓励。”5.1 步骤一与二识别与澄清模糊点首先识别出这个需求的模糊之处“打赏”具体指什么用什么打赏有什么限制流程如何 接着进行5W1H澄清Who:打赏者已登录读者、被打赏者文章作者、系统处理支付和通知。What:“打赏”行为可能包括选择金额、支付、生成记录、通知作者。Where:在文章详情页的某个位置如文章底部。When:读者阅读文章时随时可以操作。前提可能是读者账户已实名认证且有余额。Why:激励作者创作更多优质内容增强社区互动。How:读者点击“打赏”按钮 - 弹出金额选择面板 - 选择金额并确认 - 调用支付 - 成功后显示感谢提示并通知作者。5.2 步骤三产出BDD叙事与验收标准叙事1读者视角“作为一名喜欢某篇文章的已登录读者我想要通过简单的操作给作者一笔打赏以便于表达我的赞赏并鼓励作者继续创作。”叙事2作者视角“作为一名内容创作者我希望及时收到读者打赏的通知和记录以便于了解读者的反馈并管理我的创作收益。”验收标准示例读者成功打赏Given 用户已登录且账户余额充足And 用户正在浏览一篇允许打赏的文章详情页When 用户点击“打赏”按钮And 在弹出的面板中选择“5元”金额并点击“确认支付”Then 系统应从用户账户扣除5元And 向作者账户增加5元扣除平台手续费后And 创建一条打赏记录And 向作者发送一条打赏通知And 在界面显示“打赏成功感谢您的支持”提示5.3 步骤四拆解关键用例这里可以拆解出多个关注点分离的用例LoadArticleRewardInfoUseCase: 加载文章是否可打赏、作者信息、默认金额选项等。ValidateRewardRequestUseCase: 验证打赏请求用户是否登录、余额是否充足、文章状态是否正常。ProcessRewardPaymentUseCase: 核心支付处理逻辑协调账户扣款、加款、记录生成。SendRewardNotificationUseCase: 发送通知给作者。CancelRewardUseCase: 定义在支付请求发出后但未完成前用户取消操作的处理流程如关闭支付窗口。5.4 步骤五定义模型与契约模型规格RewardTransaction:属性名类型约束说明idUUID必填 唯一交易IDfromUserIdString必填打赏者IDtoUserIdString必填作者IDarticleIdString必填文章IDamountDecimal必填 0打赏金额元platformFeeDecimal必填平台手续费statusEnum必填pending,completed,failed,cancelledcreatedAtDateTime必填创建时间负载契约POST /api/v1/rewards:请求体{ articleId: article_123, amount: 5.00 }成功响应 (201 Created):{ rewardId: txn_abc123, status: completed, message: 打赏成功 }5.5 步骤六可视化与归档绘制一个“文章打赏流程图”涵盖从点击按钮开始经过验证、支付处理、成功/失败分支、取消分支到最后更新UI和发送通知的完整流程。同时绘制一个简单的架构图展示前端组件、RewardUseCase、PaymentService、NotificationService和Repository之间的依赖关系。最后将上述所有产出物整合到一个名为Feature_Spec_Reward_System.md的文档中放入项目文档目录。至此一个模糊的“打赏功能”想法已经转变为一套团队任何成员都可理解、可执行、可测试的精密工程蓝图。6. 常见问题、排查技巧与进阶思考6.1 实施过程中的典型问题与解决方案问题1感觉流程太繁琐拖慢了项目启动速度。分析这是最常见的质疑。关键在于理解这不是“瀑布模型”的繁文缛节而是为“敏捷开发”提供高质量的输入。一个模糊的需求直接进入开发导致的返工和沟通成本远高于前期花时间澄清。解决对于小型功能或原型可以适当简化。例如不一定每次都画全所有图表但BDD验收标准和核心的用例/模型规格必须写。熟练后利用AI助手生成初稿然后人工评审和修正效率会非常高。问题2AI生成的规格看起来合理但深入开发时发现遗漏了边界情况。分析AI基于模式生成可能无法穷尽所有业务特有的复杂逻辑。解决建立“规格评审会”机制。在开发启动前产品、开发、测试三方一起过一遍AI生成的规格进行“需求攻击”专门寻找模糊点和边界情况。这是将AI作为“初级分析师”使用人类专家进行“质量把关”的高效模式。问题3如何确保“活着的规范”真的能活起来而不是又一次文档与代码脱节分析这需要流程和工具的支持。解决版本化将功能规格文档Markdown文件放在与代码同一Git仓库中随代码一起提交和评审。建立链接在规格文档中可以添加指向相关代码文件如UseCase实现类、API控制器的链接。反之在代码注释中也可以引用规格文档的章节。自动化验证将BDD验收标准转化为自动化集成测试如Cucumber。当代码修改导致测试失败时开发者就必须去更新规格或修复代码从而强制保持同步。6.2 技能使用的独家心得与技巧技巧一从“问题”出发而非从“技能”出发。不要为了用技能而用技能。当你面对一段模糊的需求感到困惑时再调用它。你可以直接对AI说“这段需求描述很模糊请运用需求工程技能帮我提出至少5个澄清问题。” 或者 “基于我们刚才的对话请生成一份关于‘用户上传头像’功能的初步模型规格和API契约。”技巧二将技能作为团队沟通的“中间语言”。在跨职能团队会议中可以将AI生成的初步规格特别是流程图和用例作为讨论的基线。大家围绕这个具体的、可视化的草案进行修改和补充这比围绕一句抽象的话争论要高效得多。它能立刻暴露不同角色对同一需求理解的偏差。技巧三迭代式细化而非一次性完美。不必强求第一次就产出完美无缺的终极规格。可以先快速生成一个“最小可行规格”MVS包含最核心的BDD叙事、主成功用例和关键模型。在开发过程中随着理解的深入再不断补充异常流程、取消课程和更详细的契约。技能支持这种渐进式细化的方式。技巧四结合架构技能形成闭环。SwiftyJourney还提供了ios-architecture-expert等相关技能。你可以在产出需求规格后立即要求AI“基于刚才生成的‘打赏功能’规格遵循Clean Architecture为我设计iOS端的模块结构和依赖关系图。” 这样从需求到设计再到代码框架AI可以为你提供一条龙的思想辅助极大地提升从想法到落地原型的效率。最终requirements-engineering-skill的价值不在于替代人类的思考而在于将人类从繁琐、重复、易错的结构化信息整理工作中解放出来让我们能更专注于创造性的问题解决和深度的业务理解。它是一副“思考的脚手架”一副“沟通的翻译器”帮助每一个团队将模糊的愿景扎实地夯成可建造的基石。