AI赋能需求工程：从模糊需求到清晰蓝图的结构化方法

1. 项目概述：从模糊需求到清晰蓝图的工程化技能

在软件开发或产品设计领域，我们最常听到的抱怨是什么？——“需求不清晰”。产品经理丢过来一句话描述，业务方给出一堆模糊的期望，开发团队一头雾水地开始编码，最终交付时才发现“这不是我想要的”。这种场景每天都在上演，它不仅消耗团队士气，更直接导致项目延期、成本超支和产品质量低下。

SwiftyJourney/requirements-engineering-skill正是为了解决这个核心痛点而生。这不是一个简单的工具库或模板，而是一套内置于 Claude Code、Cursor 等智能编码助手（Agent）中的“工程化需求分析”技能。它的核心价值在于，将“需求工程”这个看似主观、依赖个人经验的活动，转化为一套结构化、可重复、可验证的标准化流程。简单来说，它教会你的 AI 助手，如何像一个经验丰富的系统分析师或技术负责人那样思考，把一句模糊的“用户能登录”拆解成包含行为驱动开发（BDD）叙述、验收标准、用例、数据模型、接口契约乃至流程图的完整技术规格说明书。

这套方法论源自 Essential Developer 的实战精华，尤其在其广受好评的 iOS Lead Essentials 课程中得到了充分验证。它不只是“写文档”，而是建立一种“活着的规范”——需求与代码同步演进，每一个功能块都具备完整的可追溯性。无论你是需要向团队明确需求的产品经理，还是渴望在编码前获得清晰指引的开发者，或是负责协调各方的技术负责人，掌握这套技能都能让你从“被动接收需求”转变为“主动定义和澄清需求”，从根本上提升协作效率和交付质量。

2. 核心方法论与七大产出物解析

2.1 需求工程的六步标准化流程

这套技能将需求澄清过程标准化为六个可操作的步骤，每一步都旨在将模糊性转化为确定性。

第一步：识别（Identify）这不仅仅是“看到需求”，而是训练一种敏感性，能快速从对话、文档或会议记录中嗅出“模糊的味道”。典型的模糊需求信号包括：大量使用“应该”、“可能”、“方便地”等不确定性词汇；描述功能而非具体行为（如“提升用户体验”）；缺乏明确的行为主体和成功标准。在这一步，你需要做的是标记出这些模糊点，而不是试图立即解决它们。

第二步：澄清（Clarify）这是整个流程中最具“人味”的一步，需要运用经典的5W1H（Who, What, Where, When, Why, How）提问法进行深入挖掘。例如，面对“用户能管理个人资料”这个需求，你需要追问：

• Who:是注册用户还是所有访客？有没有管理员角色？
• What:“管理”具体指什么？查看、编辑、上传头像、删除账户？
• Where:在哪个页面或模块进行管理？
• When:是随时可操作，还是需要满足某些前置条件（如邮箱已验证）？
• Why:用户为什么要做这个操作？背后的业务目标是什么？
• How:操作的具体流程是怎样的？有没有异常情况？

通过这一系列提问，你将收集到构建精确规格所需的所有原始信息。

第三步：用BDD定义行为（Specify BDD）在澄清的基础上，我们开始进行结构化输出。行为驱动开发（BDD）框架在这里扮演了关键角色。它要求我们从不同用户角色的视角，用“叙事”的方式描述功能价值。一个完整的BDD叙事通常遵循“作为一个[角色]，我想要[功能]，以便于[商业价值]”的格式。紧接着，便是用“Given-When-Then”语法编写验收标准，这些标准本质上是可自动化的测试用例，为后续开发提供了不可辩驳的通过标准。

第四步：定义用例（Define Use Cases）BDD描述了“做什么”和“为什么”，而用例则详细规定了“怎么做”。一个健壮的用例不仅包含成功的主流程（Happy Path），还必须涵盖各种异常流程（Error Courses）和取消流程（Cancel Courses）。特别是“取消流程”，这是Essential Developer方法论中强调的一个关键模式。对于任何异步操作（如网络请求、文件上传），都必须明确用户如何取消、取消后系统状态如何回滚，这直接关系到系统的健壮性和用户体验。

第五步：建模与契约（Model & Contract）至此，需求的行为层面已经清晰。接下来需要深入到数据层面和协作层面。“模型规格”用于精确定义领域实体，通常以属性/类型表格的形式呈现，明确每个字段的名称、数据类型、约束条件和是否可选。“负载契约”则定义了系统间（尤其是前后端）的通信协议，明确API的端点、HTTP方法、请求/响应体的JSON结构。这一步的输出物是开发者和测试人员最直接的编码和测试依据。

第六步：可视化与归档（Visualize & Document）最后，将前五步的文本信息转化为视觉图表。流程图可以清晰地展示用户操作和系统判断的逻辑分支；架构图则描绘了系统内部模块的依赖关系。将这些图表与之前的文本规格整合，便形成了一份完整的“功能规格说明书”。这份文档是活的，会随着迭代不断更新，确保文档与代码永不脱节。

2.2 七大规格产出物详解与实战示例

下面，我们以一个具体的例子——“用户通过邮箱和密码登录”——来逐一拆解这七大产出物，看看它们如何将一句话需求具象化。

1. BDD叙事与验收标准这是需求的“用户故事”和“测试合同”。

• 叙事：“作为一名未登录的访客，我想要通过输入邮箱和密码登录我的账户，以便于访问我的个人数据和专属功能。”
• 验收标准示例：
  • 场景：使用有效凭证登录
    • Given 用户位于登录页面
    • And 输入了已注册的邮箱[e-mail]
    • And 输入了正确的密码
    • When 用户点击“登录”按钮
    • Then 系统应验证凭证
    • And 导航至用户主页
    • And 在界面显示“登录成功”提示
  • 场景：使用错误密码登录
    • Given 用户位于登录页面
    • And 输入了已注册的邮箱
    • And 输入了错误的密码
    • When 用户点击“登录”按钮
    • Then 系统应显示“邮箱或密码错误”提示
    • And 用户仍停留在登录页面

2. 用例用例详细描述了系统的行为流。以“登录”主用例为例，其步骤可能包括：1. 用户输入邮箱；2. 用户输入密码；3. 用户提交表单；4. 系统验证输入格式；5. 系统调用认证服务；6. 系统处理响应（成功则创建会话并跳转，失败则显示错误）。同时，必须定义“取消课程”：例如，在系统验证过程中，用户点击了“取消”按钮，系统应中止验证流程并清空表单。

3. 模型规格定义“用户”模型在此上下文中的相关属性。

属性名	类型	约束	说明
email	String	必填， 格式验证	用户注册邮箱
password	String	必填， 长度>=8	用户密码（前端传输时应为哈希值）
loginAttemptCount	Int	可选， 默认0	用于记录连续失败次数，防止暴力破解

4. 负载契约定义登录API的接口。

• 端点：POST /api/v1/auth/login
• 请求体：

  { "email": "string", "password": "string" }

• 成功响应 (200 OK):

  { "token": "jwt.access.token.string", "user": { "id": "123", "email": "[e-mail]", "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方法论将“取消课程”提升为一级公民，这是一个极具远见的设计。

为什么“取消课程”如此重要？在现代交互式应用，尤其是移动端和富客户端应用中，用户随时可能中断操作：切换应用、点击返回、锁屏、网络切换。如果一个文件上传请求无法取消，用户就只能干等着或强制关闭应用。如果一个导航请求无法取消，在快速切换页面时就会引发状态混乱。缺乏取消机制的需求是不完整的，会导致代码充满漏洞和僵尸任务。

如何在规格中定义“取消课程”？在用例描述中，你需要明确：

1. 取消的触发点：在哪个步骤用户可以取消？（例如，“在系统验证凭证过程中，用户点击了‘取消’按钮”）。
2. 系统的取消响应：系统必须执行哪些清理动作？（例如，“中止正在进行的网络请求”、“清空密码输入框”、“恢复界面至可交互状态”）。
3. 状态的一致性：取消后，系统的业务状态和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 步骤四：拆解关键用例

这里可以拆解出多个关注点分离的用例：

1. LoadArticleRewardInfoUseCase: 加载文章是否可打赏、作者信息、默认金额选项等。
2. ValidateRewardRequestUseCase: 验证打赏请求（用户是否登录、余额是否充足、文章状态是否正常）。
3. ProcessRewardPaymentUseCase: 核心支付处理逻辑，协调账户扣款、加款、记录生成。
4. SendRewardNotificationUseCase: 发送通知给作者。
5. CancelRewardUseCase: 定义在支付请求发出后但未完成前，用户取消操作的处理流程（如关闭支付窗口）。

5.4 步骤五：定义模型与契约

• 模型规格RewardTransaction:

  属性名	类型	约束	说明
  id	UUID	必填， 唯一	交易ID
  fromUserId	String	必填	打赏者ID
  toUserId	String	必填	作者ID
  articleId	String	必填	文章ID
  amount	Decimal	必填， >0	打赏金额（元）
  platformFee	Decimal	必填	平台手续费
  status	Enum	必填	pending,completed,failed,cancelled
  createdAt	DateTime	必填	创建时间

• 负载契约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助手生成初稿，然后人工评审和修正，效率会非常高。

问题2：AI生成的规格看起来合理，但深入开发时发现遗漏了边界情况。

• 分析：AI基于模式生成，可能无法穷尽所有业务特有的复杂逻辑。
• 解决：建立“规格评审会”机制。在开发启动前，产品、开发、测试三方一起过一遍AI生成的规格，进行“需求攻击”，专门寻找模糊点和边界情况。这是将AI作为“初级分析师”使用，人类专家进行“质量把关”的高效模式。

问题3：如何确保“活着的规范”真的能活起来，而不是又一次文档与代码脱节？

• 分析：这需要流程和工具的支持。
• 解决：
  1. 版本化：将功能规格文档（Markdown文件）放在与代码同一Git仓库中，随代码一起提交和评审。
  2. 建立链接：在规格文档中，可以添加指向相关代码文件（如UseCase实现类、API控制器）的链接。反之，在代码注释中也可以引用规格文档的章节。
  3. 自动化验证：将BDD验收标准转化为自动化集成测试（如Cucumber）。当代码修改导致测试失败时，开发者就必须去更新规格或修复代码，从而强制保持同步。

6.2 技能使用的独家心得与技巧

技巧一：从“问题”出发，而非从“技能”出发。不要为了用技能而用技能。当你面对一段模糊的需求感到困惑时，再调用它。你可以直接对AI说：“这段需求描述很模糊，请运用需求工程技能，帮我提出至少5个澄清问题。” 或者 “基于我们刚才的对话，请生成一份关于‘用户上传头像’功能的初步模型规格和API契约。”

技巧二：将技能作为团队沟通的“中间语言”。在跨职能团队会议中，可以将AI生成的初步规格（特别是流程图和用例）作为讨论的基线。大家围绕这个具体的、可视化的草案进行修改和补充，这比围绕一句抽象的话争论要高效得多。它能立刻暴露不同角色对同一需求理解的偏差。

技巧三：迭代式细化，而非一次性完美。不必强求第一次就产出完美无缺的终极规格。可以先快速生成一个“最小可行规格”（MVS），包含最核心的BDD叙事、主成功用例和关键模型。在开发过程中，随着理解的深入，再不断补充异常流程、取消课程和更详细的契约。技能支持这种渐进式细化的方式。

技巧四：结合架构技能，形成闭环。SwiftyJourney还提供了ios-architecture-expert等相关技能。你可以在产出需求规格后，立即要求AI：“基于刚才生成的‘打赏功能’规格，遵循Clean Architecture，为我设计iOS端的模块结构和依赖关系图。” 这样，从需求到设计再到代码框架，AI可以为你提供一条龙的思想辅助，极大地提升从想法到落地原型的效率。

最终，requirements-engineering-skill的价值不在于替代人类的思考，而在于将人类从繁琐、重复、易错的结构化信息整理工作中解放出来，让我们能更专注于创造性的问题解决和深度的业务理解。它是一副“思考的脚手架”，一副“沟通的翻译器”，帮助每一个团队，将模糊的愿景，扎实地夯成可建造的基石。