nesnilnehc/skills/analyze-requirements

技能（Skill）：分析需求

目的 (Purpose)

诊断需求层面的问题，将模糊的意图转化为有效的、可测试的需求。引导开发人员从“我想构建 X”到明确的问题陈述、优先需求、明确的约束和有限的范围——所有这些都在任何设计或实施开始之前。

---

核心目标（Core Objective）

首要目标：生成一份已验证的需求文档，其中每个需求都是可测试的、范围明确的并且以实际问题为基础。

成功标准（必须满足所有要求）：

1. ✅ 明确的问题：存在明确的问题陈述，但未引用任何解决方案或技术
2. ✅ 需求可通过 ID 进行测试：每个需求都有验收标准和唯一的“R-NN”ID（例如 R-01、R-02）； ID 连续，无间隙或重复
3. ✅ 列出的约束：实际约束（预算、时间、技能、依赖性）与假设分离
4. ✅ 范围有限：V1 边界是明确的，列出了延迟的项目并触发重新考虑记录
5. ✅ 用户确认：用户明确批准已验证需求（表示“已批准”、“看起来不错”、“继续”或同等内容）
6. ✅ 文档持久化：需求文档按照 docs/ARTIFACT_NORMS.md 写入 docs/requirements-planning/<topic>.md 并提交

验收测试：不熟悉该项目的人是否可以阅读需求文档并理解问题，谁有它，“完成”是什么样的，以及什么超出了范围 - 而无需提出澄清问题？

---

范围边界（范围边界）

本技能负责：

• 意图模糊→已验证需求文档
• 问题发现和阐明
• 需要澄清和编写验收标准
• 约束清单和假设映射
• 范围定义和优先级（V1 与更高版本）
• 需求质量评估（清晰度、特异性、完整性）

本技能不负责：

• 设计和架构决策（使用“设计解决方案”）
• 实施计划或任务清单（使用实施计划技能）
• 代码编写（使用开发技能）
• 代码审查（使用“审查代码”）
• 技术选型（提到约束条件，但技术选型属于设计阶段）

转交点：当需求已验证（满足所有成功标准）时，移交给“设计解决方案”进行设计探索，如果设计很琐碎，则移交给实施计划。

---

使用场景（用例）

• 新项目启动：开发人员说“我想构建 X”——在任何设计之前提取真正的问题并验证需求。
• 功能请求分类：利益相关者提交模糊的功能请求 - 澄清问题、范围和验收标准。
• 范围蔓延预防：项目不断增长 - 应用优先级和明确的 V1 边界。
• 需求验证：现有需求感觉不完整 - 诊断它们处于哪种状态并进行改进。
• 约束发现：项目中期的意外阻碍——在隐藏的约束和假设破坏工作之前将其暴露出来。

---

行为（行为）

交互（互动）政策

• 默认：从输入推断当前状态；从最早的未解决状态开始
• 选择选项：一次一个问题；尽可能提供“[A][B][C]”
• 确认：退出设计转交之前；在写需求文档之前

第 0 阶段：Norms Resolution

按 specs/artifact-contract.md §8 Runtime Norms Resolution Protocol 实现：

1. 按 §8.2 发现顺序解析项目规范 → 确定 requirements artifact_type 的 path_pattern（默认：docs/requirements/{slug}.md；项目可覆盖为任意自定义路径，如聚合式 work/{parent_slug}/requirement.md）
2. 按 §8.3 占位符语法替换；未解析占位符按 §8.6 追问用户
3. 若调用方 frontmatter 输入含 upstream_ref：在产出制品的 frontmatter emit parent: <upstream_ref>
4. 记录 resolved_path + frontmatter 增量供第 3 阶段"坚持"使用

硬门：验证前无设计

DO NOT propose architecture, choose technologies, create designs,
or write code until requirements are validated.

Requirements describe PROBLEMS and NEEDS, not SOLUTIONS.
If a requirement mentions technology, it is a solution in disguise.

第 0 阶段：分类

开始时宣布：“我正在使用分析需求技能在任何设计或实施之前验证需求。”

对输入执行快速质量评估：

| 维度 | 股份范围 |检查什么 | | :--- | :--- | :--- | | 清晰度 | 0–100% |有没有一个明确的解释？术语有定义吗？ | | 特异性 | 0–100% |是否提供了上下文？是否提到了成功标准？范围有限制吗？ | | 完整性 | 0–100% |是否提供了所有必要的信息？是否提到了限制条件？ |

决策矩阵：

|总分|行动| | :--- | :--- | | < 40% |从状态 RA0 开始（问题发现） | | 40–70% |确定最早的问题状态并从那里开始 | | > 70% |快速验证并关注差距 |

第 1 阶段：诊断 — 确定当前状态

按顺序进展状态。不要跳过状态——如果问题不清楚，不要讨论需求。

状态 RA0：无问题声明

症状：从解决方案开始（“我想构建 X”）；功能列表无接地问题； “每个人都需要这个”推理；无法明确谁有什么问题。

关键问题（一次问一个）：

• “什么具体的挫折或痛点导致了这个想法？”
• “人们（或你）今天在做什么？”
• “如果这不存在会发生什么？谁受苦以及如何受苦？”
• “如果你是用户，是什么促使你现在想到这个？”

干预：

• 问题陈述简介：了解谁遇到了什么问题以及问题为何重要
• “五位用户”测试：说出 5 个会受益的具体人（即使其中一个是你自己）
• 待完成的工作：“当我[情况]时，我想要[动机]，这样我就可以[结果]”
• 问题考古学：追根溯源到特定的挫折事件

退出标准：存在未提及任何解决方案或技术的问题陈述。

说明 RA1：解决方案优先的思维

症状：问题清晰之前的技术选择（“需要数据库”、“应该使用 React”）； 需求描述的是实施而不是需求；不参考技术就无法解释需求。

关键问题：

• “这个功能背后的需求是什么？”
• “如果这项技术不存在，你还需要什么？”
• “你是在解决你的问题还是复制别人的解决方案？”
• “这项技术是必需的（限制）还是只是熟悉（偏好）？”

干预：

• “删除解决方案”练习：描述需求，无需任何实施词语
• 功能提取：将每个需求重写为“系统必须[动词]...”，不带技术术语
• 约束与偏好的区别：将硬约束与默认值分开

退出标准：每个需求都描述了需求，而不是实现。技术参考要么被删除，要么被明确记录为真正的约束。

状态 RA2：模糊需求

症状：无法描述“完成”是什么样子；基于形容词的需求（“快速”、“简单”、“直观”）； 无法测试的需求； “用户应该能够……”没有具体说明。

关键问题：

• “你能给出一个具体的示例场景吗？”
• “与出色的实施相比，令人失望的实施会是什么样子？”
• “满足这一需求的最低限度是多少？”
• “你怎么知道这个要求是否得到满足？”

干预：

• 验收场景写作：“给定[背景]，当[行动]，然后[结果]”
• 特异性阶梯：具体是谁？具体做什么？具体什么时候？
• “完成看起来像......”练习：描述能够满足的最小的事情
• 可测试性检查：如果你不能为其编写测试，那么你还没有理解它

退出标准：每个要求都有接受标准。不再有仅形容词的需求。

状态 RA3：隐藏的约束

症状：意外依赖性出现较晚；没有明确的约束库存；假设被视为事实；在讨论中发现阻碍因素。

关键问题：

• “存在哪些外部依赖关系？”
• “你实际上拥有什么资源、技能和时间？”
• "What would kill this project if it turned out to be true?"
• “您认为您尚未验证的事实是什么？”

干预：

• 约束清单：列出预算、时间、技能、依赖性、集成作为真实约束
• 假设映射：将已验证事实与未验证假设分开
• 风险事前分析：“6 个月后，这次失败了。为什么？”
• 依赖关系发现：在这之前必须存在什么？

退出标准：存在约束清单，明确区分实际约束与假设。

状态 RA4：范围蔓延

症状：每个功能都感觉同样重要；无V1边界； “当我们这样做时……”补充； 需求的增长速度快于他们的满足程度。

关键问题：

• “如果你只能运送 3 件东西，它们是什么？”
• “你可以削减哪些内容并仍然解决核心问题？”
• “最小的有用版本是什么？”
• “什么会触发重新考虑推迟的项目？”

干预：

• 剪切优先方法：从所有内容开始，仅添加必要的内容
• 力量等级：严格排序，没有联系
• 行走骨架：识别最薄有用的版本
• 莫斯科：必须/应该/可以/不会
• 推迟的功能列表，带有明确的触发器以供重新考虑

退出标准：V1 边界明确。延迟项目与触发器一起列出。对于范围内的内容没有任何含糊之处。

说明 RA5：要求已验证

指标：

• 存在问题陈述但没有解决方案参考
• 每个要求都可以通过验收标准进行测试
• 列出约束条件（真实与假设）
• 范围受明确的 V1 定义限制
• 可以向不熟悉的人解释并让他们理解需求

下一步：将已验证的需求文档移交给“设计解决方案”。

第 2 阶段：验证 — 与用户确认

1. 以结构化格式呈现需求摘要（参见输出部分）
2. 请求明确批准：“这些需求是否准确地反映了您的需求？”
3. 如果需要则迭代：如果发现差距则返回相关状态

第 3 阶段：坚持 — 编写文档

1. 确定输出位置：
   • 默认：docs/requirements-planning/<topic>.md
   • 兼容性：使用 docs/需求/<topic>.md 的现有项目可能会暂时保留该路径
   • 询问用户是否首选不同的位置
2. 按照输出模板编写文档
3. 致力于版本控制
4. 宣布完成并转交

---

输入与输出（输入&输出）

输入（输入）

• 用户请求：模糊的想法、功能请求、问题陈述或需要验证的现有需求。
• 项目上下文：现有代码库、文档、约束（在探索过程中发现）。
• 用户响应：对诊断问题的回答、评估反馈、已验证需求的批准。

输出（输出）

已验证的需求文档

# [Topic] Requirements

**Date:** YYYY-MM-DD
**Status:** Validated
**Approved by:** [User name or "User"]

## Problem Statement

[Who has what problem and why it matters. No solution or technology references.]

## Need Hierarchy

### Must Have (V1)

| ID | Need | Acceptance Criteria | Status |
| :--- | :--- | :--- | :--- |
| R-01 | [Testable need] | Given [X], when [Y], then [Z] | Validated |
| R-02 | [Testable need] | [Measurable criterion] | Validated |

### Should Have (V1 if time permits)

| ID | Need | Acceptance Criteria | Status |
| :--- | :--- | :--- | :--- |
| R-03 | [Testable need] | [Criterion] | Validated |

### Could Have (Post-V1)

| ID | Need | Trigger to reconsider | Status |
| :--- | :--- | :--- | :--- |
| R-04 | [Deferred need] | [When to revisit] | Deferred |

## Constraint Inventory

### Real Constraints (Validated)

- [Budget, time, skills, dependencies, integrations]

### Assumptions (Unvalidated)

- [Assumptions that need validation, with plan to validate]

## Scope Definition

- **In scope (V1):** [Explicit list]
- **Out of scope:** [Explicit list]
- **Walking skeleton:** [Thinnest useful version]

## Open Questions

- [Any remaining unknowns with plan to resolve]

状态生命周期 (Status Lifecycle)

该技能生成的每个需求条目初始状态应设为 Validated（已验证）或 Deferred（已推迟）。 下游执行、计划或开发流程（例如 breakdown-tasks 和执行 Agent）负责在实施期间更新文档中这些需求的状态（例如更新为 In Progress、Implemented、Dropped 等）。本技能不负责此后的状态更新。

对话与文件

|转到文件|保持对话状态 | | :--- | :--- | |问题陈述|五个为什么探索 | |需要具有验收标准的层次结构|优先讨论 | |限制库存|假设发现对话| |范围定义 |削减/保留谈判 | |验证需求 |澄清问题|

---

限制（限制）

硬边界（Hard Boundaries）

• 验证前不进行设计：在需求已验证之前，不要提出架构、选择技术或创建设计。
• 无跳过状态：如果问题不清楚 (RA0)，请勿讨论需求 (RA2) 或范围 (RA4)。依次进行。
• 一次一个问题：不要在一条消息中用多个诊断问题淹没用户。
• 开发人员决定：诊断、提问和指导 - 开发人员对优先级和范围做出最终决定。
• 不接受含糊不清：不接受基于形容词的需求（“快速”、“直观”）。推动可测试的标准。
• 没有解决方案语言：需求必须描述问题和需求，而不是实现。标记并重写解决方案——伪装的需求。

技能边界 (Skill Boundaries)（避免重叠）

不要做这些（其他技能可以处理它们）：

• 设计和架构：提出解决方案、选择技术、创建设计文档→使用“设计解决方案”
• 实施规划：创建任务列表、文件路径、代码结构 → 使用实施规划技能
• 代码编写：编写任何实现代码→使用开发技能
• 代码审查：审查现有代码→使用review-code
• 技能精炼：改进技能文档→使用refine-skill-design

何时停止并交接：

• 用户说“已批准”、“看起来不错”、“继续”→要求已验证，移交给“设计解决方案”
• 用户问“我们应该如何设计这个？” → 移交给“设计解决方案”
• 用户问“你能写代码吗？” → 需求完成，移交给开发工作流程（如果跳过，建议设计步骤）
• 用户说需求“足够好” → 确认满足所有成功标准，然后移交

---

自检（Self-Check）

核心成功标准（必须满足所有标准）

• [ ] 问题明确：存在明确的问题陈述，但没有解决方案或技术参考
• [ ] 需求可通过 ID 进行测试：每个需求都有验收标准和唯一的“R-NN”ID； ID 连续，无间隙或重复
• [ ] 明确的状态管理：每个需求条目均有明确的初始状态（如 Validated），并在输出中包含状态列
• [ ] 列出的约束：与假设分离的实际约束
• [ ] 范围有界：V1 边界明确，带有延迟项目和触发器记录
• [ ] 用户确认：用户明确批准已验证需求
• [ ] 文档保留：需求文档写入docs/requirements-planning/<topic>.md并提交

流程质量检查

• [ ] 未跳过的状态：按顺序进行诊断状态（未从 RA0 跳转到 RA4）
• [ ] 一次一个问题：没有让用户因每条消息的多个问题而感到不知所措
• [ ] 没有解决方案语言：需求描述需求，而不是实现
• [ ] 开发人员决定：指导和质疑，但开发人员做出了最终优先级和范围调用
• [ ] 形容词已解决：没有模糊形容词，仅保留需求（“快速”、“直观”、“简单”）
• [ ] 假设分离：未验证的假设与实际约束分开标记
• [ ] 已审核的 ID：所有需求 ID 均遵循“R-NN”格式，是唯一的，并用于文档内的交叉引用

健康检查问题

在声明需求已验证之前，问问自己：

1. 如果该项目失败，最有可能与需求相关的原因是什么？
2. 开发人员正在构建他们需要的东西或者他们知道如何构建的东西吗？
3. 什么明确不在范围内？
4. 在实际限制下，范围是否可以实现？
5. 哪些假设尚未验证？
6. 不熟悉的人能否正确解释需求？

验收测试

不熟悉该项目的人是否可以阅读需求文档并理解问题、谁有这个问题、“完成”是什么样子以及什么超出了范围——而不需要提出澄清问题？

如果否：要求不完整。返回到最早未解决的状态。

如果是：要求已验证。坚持并移交给“设计解决方案”。

---

示例（示例）

示例 1：Greenfield 项目 —“我想构建一个静态站点生成器”

用户：“我想构建一个静态站点生成器。”

代理宣布：“在任何设计或实施之前，我正在使用分析需求技能来验证需求。”

分类：清晰度 30%，特异性 10%，完整性 10%。从 RA0 开始。

RA0 — 问题发现：

代理：“现有静态站点生成器的具体挫败感导致了这个想法？”

用户：“我厌倦了复杂性。我只想编写 Markdown 并获取 HTML。”

特工：“你今天做什么？”

用户：“我使用 Hugo，但调试配置的时间比编写内容的时间多。”

捕获的问题陈述：“单独的内容创建者浪费时间调试 SSG 配置而不是编写。需要从 Markdown 到 HTML 的零配置路径。”

RA1 — 解决方案优先检查：

代理：“您提到了 Hugo - 有什么关于 Hugo 的具体内容是您需要保留的吗？或者无论使用什么工具，“Markdown → HTML”都是核心需求吗？”

用户：“只是 Markdown 到 HTML。我不在乎如何。”

退出 RA1：需要在没有技术锁定的情况下确认。

RA2 — 特异性：

特工：“最简单有用的版本‘完成’会是什么样子？”

用户：“我将其指向 .md 文件的文件夹，然后获取具有基本样式的 .html 文件的文件夹。”

特工：“你怎么知道输出是正确的？”

用户：“每个 .md 文件都会生成一个 .html 文件。页面之间的链接有效。它在移动设备上看起来可读。”

捕获的验收标准：

• R-01：每个.md文件→一个.html文件（1:1映射）
• R-02：内部链接正确解析
• R-03：输出在移动设备上可读（视口元、可读字体大小）

RA3 — 限制：

特工：“你有什么时间和技能来做这件事？”

用户：“晚上和周末，每周大概 10 个小时。我很了解 JavaScript。”

限制库存： 时间：10 小时/周；技能：JavaScript熟练程度；依赖性：未确定。

RA4 — 范围：

代理：“如果你只能发布 3 个功能，那它们是什么？”

用户：“Markdown 到 HTML、基本 CSS 和具有实时重新加载功能的开发服务器。”

范围定义：

• V1必须：Markdown→HTML，默认CSS，开发服务器
• 延期：主题、插件、自定义模板（触发：V1可用2周后触发）
• 行走骨架：将一个 .md 文件转换为 .html 的 CLI

RA5 — 已验证：代理提供摘要，用户说“看起来不错”。写入“docs/requirements-planning/static-site-generator.md”的文档。

示例 2：边缘案例 — 解决方案伪装的需求

用户：“我需要一个带有 PostgreSQL 数据库、GraphQL API 和 Redis 缓存的 React 应用程序。”

代理宣布：“在任何设计或实施之前，我正在使用分析需求技能来验证需求。”

分类：清晰度 60%（明确的技术），特异性 20%（没有说明问题），完整性 15%。从 RA0 开始。

RA0 — 问题发现：

特工：“这些都是技术选择。你想解决什么问题？谁有问题？”

用户：“哦......我需要跟踪我的小型企业的库存。我目前使用电子表格并不断丢失数据。”

问题陈述：“小企业主由于电子表格的限制而丢失库存数据。需要可靠的库存跟踪。”

RA1 — 解决方案优先清理：

Agent：“让我们在没有技术的情况下重写需求。‘React、PostgreSQL、GraphQL、Redis’都是解决方案。它们代表什么需求？”

重写：

• ~~React 应用程序~~ →“需要可从多个设备访问的用户界面”
• ~~PostgreSQL~~ →“数据必须在服务器重新启动后保留下来并且不会丢失”
• ~~GraphQL API~~ → “需要灵活查询库存（按名称、类别、位置）”
• ~~Redis 缓存~~ → “经常访问的数据应该快速加载”

代理：“‘快速加载’可以测试吗？多快可以接受？”

用户：“库存列表页面不到 2 秒。”

退出 RA1：根据需要重写需求。技术选择推迟到设计阶段。

RA2–RA5：继续穿过各州。最终文档在没有技术假设的情况下捕获需求，允许“设计解决方案”探索正确的解决方案（这可能是一个简单的电子表格替代方案，而不是全栈应用程序）。

示例 3：边缘情况 — 项目中期范围蔓延

用户：“我们开始构建一个待办事项应用程序，但现在它需要日历集成、团队协作、文件附件和人工智能驱动的任务建议。我们落后了 3 周。”

代理宣布：“在扩大范围之前，我正在使用分析需求技能来验证需求。”

分类：清晰度 50%，特异性 40%，完整性 30%。范围蔓延症状——从 RA4 开始（早期的状态可能会在 3 周后得到解决，但需要验证）。

快速 RA0 检查：“这个待办事项应用程序解决的原始问题是什么？”

用户：“我需要停止忘记我的自由项目的任务和截止日期。”

问题已确认 — 继续进行 RA4。

RA4 — 范围蔓延干预：

代理：“如果你只能从完整列表中提供 3 个功能，哪 3 个可以解决不忘记任务的核心问题？”

用户：“基本任务列表、带提醒的截止日期，以及……现在就这些了。”

代理：“所以日历集成、团队协作、文件附件和人工智能建议都是核心问题之外的附加内容。我们应该推迟它们吗？”

范围重新定义：

• V1 Must：任务CRUD、截止日期、提醒
• 延期：日历集成（触发：使用提醒 1 个月后）、协作（触发：当自由职业者成为团队时）、附件（触发：用户请求）、AI 建议（触发：100 多个任务）
• 行走骨架：CLI 或简单的 UI，可创建带有截止日期的任务并发送提醒通知

RA5 — 已验证：要求重新聚焦。 3 周的延迟变得可以控制。文档已更新。

---

反模式

解决方案规范

问题：需求描述的是实现，而不是需求。 “系统应使用 PostgreSQL”不是必需的； “数据必须在服务器重新启动后继续存在”。

修复：对于每个要求，询问“是否可以通过不同的方式来满足？”如果是，您捕获的是实现，而不是需求。

利益相关者的虚构

问题：开发人员想象需求而不是发现需求。 “用户会想要……”没有证据。

修复：如果您是用户，请诚实地表达您的需求。如果是为他人构建，请与他们交谈或引用类似的证据。不要发明用户。

无限的积压

问题：需求不断增长，但没有划分优先级。一切都同等重要。

修复：强制等级。如果你只能运送一件东西，那是什么？然后是两个？这揭示了实际的优先事项。

过早的精确度

问题：指定尚不重要的细节。在验证任何人想要通知之前设计通知首选项。

修复：用“[X]已验证后待定”对不确定区域进行存根。精准聚焦 V1 Must 项目。

约束失明

问题：没有清点真正的约束，然后在构建过程中解决它们。

修复：在最终确定需求之前明确限制库存。

---

附录：整合地图

上游（融入此技能）

|来源 |当 |它提供什么 | | :--- | :--- | :--- | |用户请求|新项目或功能创意 |原始意图分析| |现有文档|项目中期验证 |部分需求诊断 |

下游（该技能进入）

|目标技能|当 |它收到什么 | | :--- | :--- | :--- | | 设计解决方案 |要求已验证 |验证需求文档作为设计输入 | |实施规划|设计很琐碎|经验证的需求范围和限制 |

移交合同

|该技能输出 |目标技能期望| | :--- | :--- | |问题陈述|设计背景| |需要具有验收标准的层次结构|功能性需求 | |限制库存|架构限制 | |范围定义（V1 边界）|设计范围|

附录：输出合约 (Appendix: Output Contract)

本技能产出 Validated Requirements Document：

| 元素 | 格式 | 必填字段 | 路径模式 | | :--- | :--- | :--- | :--- | | 文档主体 | Markdown | front-matter（artifact_type=requirements / created_by=analyze-requirements / lifecycle=snapshot / created_at；upstream_ref 提供时含 parent 字段）；章节：问题陈述 / 需求层级 / 验收标准 / 约束清单 / 范围边界 / 集成地图 | norms-resolved 路径（默认 docs/requirements/<slug>.md） | | 需求条目 | 列表项或表格 | id / statement / acceptance_criteria（可观察、可测试）/ priority（must/should/could/won-t） | 「需求层级」节 | | 约束清单 | 列表项 | type（technical / business / regulatory）/ description / source | 「约束清单」节 | | 集成地图 | 表格 | upstream sources、downstream skills、handoff fields（供 design-solution 消费） | 「集成地图」节 |