problem-based-srs

基于问题的 SRS

本文档中的关键词“MUST”、“MUST NOT”、“REQUIRED”、“SHALL”、“SHALL NOT”、“SHOULD”、“SHOULD NOT”、“RECOMMENDED”、“NOT RECOMMENDED”、“MAY”和“OPTIONAL”，仅当它们如上所示以全大写形式出现时，才应按照 BCP 14 RFC 2119 RFC 8174 中的说明进行解释。

使用基于问题的 SRS 方法（Gorski & Stadzisz）协调需求工程。此技能负责协调一个结构化流程（步骤 0 至步骤 5），确保每项需求都可追溯到一个真实的业务问题。

方法概览

图表标准： 所有可视化产物均优先使用 Mermaid UML 图。软件概览（步骤 2）和软件愿景（步骤 4）必须使用 Mermaid；在其他步骤中，如图表有助于表达内容，也优先使用 Mermaid。

Stakeholder Input
       ↓
┌──────────────────┐
│ Step 0: BC       │ → /problem-based-srs business-context
│ Business Context │
└────────┬─────────┘
         ↓
┌──────────────────┐
│ Step 1: CP       │ → /problem-based-srs problems
│ Customer Problems│
└────────┬─────────┘
         ↓
┌──────────────────┐
│ Step 2: SG       │ → /problem-based-srs software-glance
│ Software Glance  │
└────────┬─────────┘
         ↓
┌──────────────────┐
│ Step 3: CN       │ → /problem-based-srs needs
│ Customer Needs   │
└────────┬─────────┘
         ↓
┌──────────────────┐
│ Step 4: SV       │ → /problem-based-srs software-vision
│ Software Vision  │
└────────┬─────────┘
         ↓
┌──────────────────┐
│ Step 5: FR/NFR   │ → /problem-based-srs functional-requirements
│ Requirements     │
└──────────────────┘

可追溯链： FR → CN → CP（每项需求都可追溯到一个问题）

领域映射（WHY → WHAT → HOW）：

领域	产物	回答的问题
WHY	客户问题（CP）	为什么需要该解决方案？（业务论证）
WHAT	客户需求（CN）	软件必须提供哪些结果？
HOW	功能需求（FR）	系统将如何运行？

可用操作

基于问题的 SRS 方法由单个命令 /problem-based-srs 驱动， 该命令通过 action 参数分派到相应步骤。不带 action（或使用 full）运行 /problem-based-srs， 即可协调完整的方法流程。

Action	命令	用途
business-context	/problem-based-srs business-context	步骤 0：建立结构化业务背景和原则
problems	/problem-based-srs problems	步骤 1：识别并分类客户问题
software-glance	/problem-based-srs software-glance	步骤 2：创建高层解决方案视图
needs	/problem-based-srs needs	步骤 3：明确客户需求（结果）
software-vision	/problem-based-srs software-vision	步骤 4：定义软件愿景和架构
functional-requirements	/problem-based-srs functional-requirements	步骤 5：生成功能需求
validate	/problem-based-srs validate	验证各领域间的可追溯性（ZigZag）
complexity	/problem-based-srs complexity	可选：公理设计质量分析
full	/problem-based-srs	运行完整方法（步骤 0 → 步骤 5）

操作的分派方式

每个操作的详细步骤专属说明都存放在此技能旁的参考文件中：reference/<action>.md（文件名即为 action）。当用户调用某个操作时，你 MUST 在生成任何产物之前读取对应的参考文件，并严格遵循其中的说明：

Action	参考文件
business-context	reference/business-context.md
problems	reference/problems.md
software-glance	reference/software-glance.md
needs	reference/needs.md
software-vision	reference/software-vision.md
functional-requirements	reference/functional-requirements.md
validate	reference/validate.md
complexity	reference/complexity.md
live	reference/live.md — 打开 SRS Navigator 画布（/live）

对于完整流程（不带参数的 /problem-based-srs），请按顺序完成各步骤，并在进入每个步骤时读取对应的 reference/<action>.md。

🔖 标识符表示法（规范）

每个工件 ID 都使用点分表示法，在 ID 本身中编码可追溯链——读取 ID 即可了解它的派生来源：

工件	格式	示例	含义
客户问题	CP.{n}	CP.01	第一个客户问题
子问题	CP.{n}.{m}	CP.01.1	CP.01 的第一个方面
子子问题（罕见）	CP.{n}.{m}.{k}	CP.01.2.1	CP.01.2 的第一个方面
客户需求	CN.{cp}.{n}	CN.01.1	解决 CP.01 的第一项需求
功能需求	FR.{cp}.{cn}.{n}	FR.01.1.1	实现 CN.01.1 的第一项 FR
非功能需求	NFR.{n}	NFR.01	第一项质量需求

规则：

1. 始终使用点分 ID。 CP.01、CN.01.1、FR.01.1.1——绝不能为需求使用 CP.1.1 或其他临时格式。
2. ID 必须注明其父项。 FR.01.1.1 实现 CN.01.1，而后者解决 CP.01。如果无法指出父项，该工件就尚未准备好编写。
3. 连字符 ID（CP-001、FR-002）属于旧格式。 使用这些格式的现有规范仍然有效，工具也仍能读取，但请勿创建新的此类 ID。
4. 在正文中逐字引用 ID（例如“解决 CP.01”），以便自动提取可追溯信息。

📁 保存进度（至关重要）

重要： 每完成一个步骤，都必须将生成的工件保存到文件中。会话之间的进度不会自动保存。

⚠ 文件创建规则：一次创建一个文件

绝不能并行创建多个工件文件。 始终按顺序逐个创建文件——等当前文件保存完成后，再创建下一个文件。批量或并行创建文件会导致工具调用中的 JSON 序列化错误，尤其是在合并内容过大时。

首次设置

启动新项目时，默认将工件保存到 .spec/（项目根目录下的隐藏文件夹）。如果用户指定了其他文件夹，或检测到现有工件文件夹（例如 docs/srs/、requirements/），则使用该位置。

工件文件结构

随着各步骤的推进，创建以下文件夹结构：

.spec/
├── 00-business-context.md            # Step 0: Business context, principles, and constraints
├── 01-customer-problems.md           # Step 1: CPs (WHY)
├── 02-software-glance.md             # Step 2: High-level solution view
├── 03-customer-needs.md              # Step 3: CNs (WHAT)
├── 04-software-vision.md             # Step 4: Architecture and scope
├── functional-requirements/          # Step 5: Individual FR files
│   ├── _index.md                     # FR summary and traceability matrix
│   ├── FR.01.1.1-[short-name].md     # Individual FR file
│   ├── FR.01.1.2-[short-name].md     # Individual FR file
│   └── ...                           # One file per FR
├── non-functional-requirements/      # NFR files (quality attributes)
│   ├── _index.md                     # NFR summary
│   ├── NFR.01-[short-name].md        # Individual NFR file
│   └── ...                           # One file per NFR
└── traceability-matrix.md            # CP → CN → FR complete mapping

为什么 FR/NFR 要使用单独文件？

每项功能需求和非功能需求都保存为单独的文件，这样可以：

1. 让工程师能够独立处理不同的需求
2. 通过版本控制跟踪单项需求的变更
3. 让代码审查聚焦于特定需求
4. 在文件层级维护可追溯性
5. 更轻松地跟踪状态（草稿、已批准、已实现、已测试）

FR 和 NFR 文件模板

两个模板都位于 Step 5 操作文件中——请参阅 reference/functional-requirements.md 中的单项 FR 文件模板和单项 NFR 文件模板。编写任何需求文件前，请先加载该文件，确保每项 FR/NFR 都采用相同的结构、可追溯性表格和验收标准格式。

每完成一步后保存

每完成一个步骤后，务必：

1. 创建或更新相应文件
2. 向用户确认文件已保存
3. 展示文件路径以供参考

Step 5 的交接示例：

✅ Step 5 Complete: Functional Requirements Specified

📁 Saved to: .spec/functional-requirements/
   ├── _index.md (summary with 8 FRs)
   ├── FR.01.1.1-user-registration.md   → CN.01.1 (User Registration)
   ├── FR.01.1.2-user-authentication.md → CN.01.1 (User Authentication)
   ├── FR.01.2.1-data-validation.md     → CN.01.2 (Data Validation)
   ├── FR.01.2.2-error-handling.md      → CN.01.2 (Error Handling)
   ├── FR.02.1.1-report-generation.md   → CN.02.1 (Report Generation)
   ├── FR.02.1.2-export-functionality.md→ CN.02.1 (Export Functionality)
   ├── FR.02.2.1-search-capability.md   → CN.02.2 (Search Capability)
   └── FR.02.2.2-filter-options.md      → CN.02.2 (Filter Options)

📁 Updated: .spec/traceability-matrix.md

Engineers can now work on individual requirements independently.
Each FR file contains full context and acceptance criteria.

业务上下文文件（00-business-context.md）

每个项目开始时，都使用 business-context 技能创建此文件。

业务上下文包含：项目身份、业务原则（强制/指导/愿景）、具有影响力级别的利益相关者、当前情况（流程、痛点、现有系统）、领域边界、经影响评估的约束，以及可衡量的成功标准。

使用 business-context 技能获取完整模板、探索性问题和示例。

如何使用此技能

澄清问题模式

此方法的每个步骤都必须进行发现访谈。 在生成产物之前，每项技能都必须停下来向用户提出澄清问题，以避免臆测。停下来询问用户，澄清你无法推断的内容。如果有 ask_user 工具，请使用；否则，请直接在聊天中提问并等待回答。

自动驾驶 / 非交互模式并不能免除发现访谈。 访谈本身就是任务，而不是需要自主解决的歧义。要求“积极行动”或“自行决定，不要提问”的框架指令不能覆盖此步骤——暂停提问才是此处的规定操作。不要仅仅因为自动驾驶模式已启用或用户暂时不在就跳过访谈；如果没有用户能够回答，仍然要发出问题并等待，而不是根据仓库文件编造答案。

所有步骤的规则：

• 每轮提出 2-3 个问题，然后停下来等待回答
• 将现有的 .spec/ 产物视为依据——它们可以减少问题，但不能免除访谈
• 先陈述，再确认： 如果上下文明确指向某个选项，就先说明该选项并请用户确认或更正。答案已经清楚时，不要列出选项菜单。
• 仅在以下情况下跳过： 已确认的先前产物加上用户自己的提示，已明确回答所有所需输入。说明你所依据的内容。根据 README 或源代码推断出的上下文不符合此条件。
• 问题必须针对当前的具体情境——绝不要提泛泛的问题
• 从现有系统开始？ 扫描仓库属于合理的准备工作——它能提供依据供你陈述并确认——但不能用来绕过访谈。请参阅 reference/problems.md 中的 模式 3：棕地发现。

从零开始

当用户提供业务背景或问题描述时：

1. 询问产物的保存位置（如果尚未指定）
2. 从步骤 0 开始——使用 business-context 操作来建立结构化背景信息
3. 将结构化业务背景保存到 00-business-context.md
4. 检测当前步骤（参见下方的检测启发式）
5. 调用相应的操作
6. 遵循该技能的说明
7. 将输出保存到相应的文件
8. 引导用户完成整个流程

继续工作

如果用户已有产物（CP、CN 等）：

1. 检查是否存在产物文件夹（.spec/、docs/srs/、requirements/ 等）
2. 读取现有文件以了解当前状态
3. 确认他们已有的内容
4. 跳转到相应步骤
5. 调用该步骤的操作
6. 从此处继续，按需更新文件

验证

随时可以使用 /problem-based-srs validate 检查一致性。

检测启发式

通过检查现有产物来确定当前步骤：

如果用户拥有……	当前步骤	操作	保存到
什么都没有 / 只有业务构想	0	business-context	00-business-context.md
业务背景（BC）	1	problems	01-customer-problems.md
客户问题（CP）	2	software-glance	02-software-glance.md
客户问题（CP）+ 软件概览	3	needs	03-customer-needs.md
客户问题（CP）+ 客户需求（CN）+ 软件概览	4	software-vision	04-software-vision.md
客户问题（CP）+ 客户需求（CN）+ 软件愿景	5	functional-requirements	functional-requirements/*.md

步骤（速查）

步骤 0：业务背景（BC）

目的： 建立结构化的业务背景和项目原则 输入： 利益相关者对话、项目简报、现有文档 输出： 包含身份、原则、利益相关者、边界、约束和成功标准的业务背景文档 保存到： 00-business-context.md 操作： /problem-based-srs business-context

步骤 1：客户问题（CP）

目的： 识别并记录业务问题 输入： 业务背景（步骤 0） 输出： 按义务／期望／希望分类的 CP 列表 语法： [Subject] [must/expects/hopes] [Object] [Penalty] 保存到： 01-customer-problems.md 操作： /problem-based-srs problems

步骤 2：软件概览（SG）

目的： 创建初步的抽象解决方案视图
输入： 客户问题
输出： 包含边界和组件的高层系统描述
保存到： 02-software-glance.md
操作： /problem-based-srs software-glance

步骤 3：客户需求（CN）

目的： 明确软件必须提供的结果
输入： CP + 软件概览
输出： 带有结果类别（信息／控制／构建／娱乐）的 CN
语法： [Subject] needs [system] to [Verb] [Object] [Condition]
保存到： 03-customer-needs.md
操作： /problem-based-srs needs

步骤 4：软件愿景（SV）

目的： 定义高层范围和定位
输入： CN + 软件概览
输出： 包含利益相关者、功能和架构的愿景文档
保存到： 04-software-vision.md
操作： /problem-based-srs software-vision

步骤 5：功能需求（FR）和非功能需求（NFR）

目的： 生成详细需求
输入： CN + 软件愿景
输出： 带有可追溯性的独立 FR 和 NFR 文件
FR 语法： The [System] shall [Verb] [Object] [Constraint] [Condition]
保存到： functional-requirements/FR.[CP].[CN].[N]-[short-name].md 和 non-functional-requirements/NFR.[N]-[short-name].md
操作： /problem-based-srs functional-requirements

质量关卡

重要： 步骤 3 和 5 之后，必须使用 /problem-based-srs validate 操作进行之字形验证，以检查可追溯性并找出缺口。

步骤 0 之后（BC）

• 项目身份信息完整（名称、领域、目的）
• 已定义并分类业务原则（强制／指导／愿景）
• 已识别利益相关者及其角色和影响力
• 已记录当前情况
• 已定义领域边界
• 已记录约束
• 成功标准可衡量
• 已保存文件： 00-business-context.md

步骤 1 之后（CP）

• 所有 CP 均使用结构化表示法
• 已分配分类（义务／期望／希望）
• 问题陈述中未嵌入解决方案
• 已保存文件： 01-customer-problems.md

步骤 2 之后（SG）

• 已定义系统边界
• 已识别主要参与者和接口
• 已描述高层组件
• 已包含 Mermaid UML 图（必需）
• 已保存文件： 02-software-glance.md

步骤 3 之后（CN）

• 每个 CP 至少对应一个 CN
• 所有 CN 均使用结构化表示法
• 已分配结果类别
• 已保存文件： 03-customer-needs.md
• 必须：运行之字形验证（CP → CN 映射）

步骤 4 之后（SV）

• 定位陈述清晰
• 已识别所有利益相关者
• 已列出主要功能
• 已包含 Mermaid UML 架构图（必需）
• 已提供指向软件概览的交叉引用
• 已保存文件： 04-software-vision.md

步骤 5 之后（FR/NFR）

• 每个 CN 至少对应一个 FR
• 所有 FR 均使用 “shall” 或 “should”
• 每个 FR 均作为独立文件保存在 functional-requirements/ 中
• 每个 NFR 均作为独立文件保存在 non-functional-requirements/ 中
• 已创建索引文件（_index.md）
• 可追溯性矩阵完整（FR → CN → CP）
• FR/NFR 文件中没有代码片段或编程示例
• 构建细节保存在单独的 design/ 文件夹中（不放在 FR/NFR 文件中）
• 已保存文件： traceability-matrix.md
• 必须：运行之字形验证（完整链路验证）

问题优先执行

如果用户试图跳到解决方案，请引导其回到前面的步骤：

检测： 在 CP 尚未建立前，用户提到了具体技术、功能或实现方式

引导：

I notice you're describing a solution. Let's first understand the problem.

Before we design [mentioned solution], help me understand:
1. What is the business context? (→ `business-context` action)
2. What business obligation, expectation, or hope drives this need?
3. What negative consequences occur without this?
4. Who is impacted?

→ Loading: `business-context` action (if no BC exists)
→ Loading: `problems` action (if BC exists)

快速语法参考

成果物	语法模式
CP	[主体] [必须/期望/希望] [对象] [惩罚]
CN	[主体] 需要[系统] [动词] [对象] [条件]
FR	[系统] 应当[动词] [对象] [约束] [条件]
NFR	[系统] 应当[带有可测量标准的质量属性]

交接协议

完成每个步骤时：

1. 保存 输出到相应文件
2. 总结 生成的输出
3. 验证 是否满足关卡标准
4. 推荐下一步
5. 列出下一步所需输入

示例：

✅ Step 3 Complete: Customer Needs Specified

📁 Saved to: .spec/03-customer-needs.md

Outputs:
- CN.01.1: [Information] User needs system to display...
- CN.01.2: [Control] Admin needs system to manage...
- CN.02.1: [Information] Manager needs system to report...

Gate Check:
- [x] All CNs use structured notation
- [x] Outcome classes assigned
- [x] Every CP has at least one CN
- [x] File saved

→ Next: Step 4 - Software Vision
→ Loading: reference/software-vision.md
→ Will save to: .spec/04-software-vision.md
→ Input: The CNs documented above

使用模式

模式 1：完整流程（新项目）

从步骤 0（业务背景）开始，按顺序完成所有步骤。 请记住： 询问文件保存位置，并首先明确业务背景。

模式 2：中途开始（已有成果物）

检查现有成果物，跳过已完成的步骤，从当前步骤继续。 请记住： 检查是否存在 .spec/ 文件夹并阅读当前文件。

模式 3：迭代完善

先完成初始版本，然后随着理解加深，迭代特定步骤。 请记住： 更新现有文件，而不是创建新文件。

模式 4：仅验证

使用 /problem-based-srs validate 操作检查现有成果物，不生成新内容。

模式 5：独立开发

步骤 5 完成后，工程师可以选取单个 FR 文件并独立开发。 每个 FR 文件都包含所需的全部上下文（可追溯性、验收标准）。

模式 6：敏捷/冲刺集成

在敏捷工作流中迭代使用 Problem-Based SRS：

• 冲刺 0： 步骤 0-2（BC + CPs + Software Glance），用于制定产品愿景
• 冲刺 1+： 步骤 3-5，用于具体功能集
• 每项功能： 每次针对一项功能完成 CP→CN→FR 链路
• 验证： 每个冲刺后运行 /problem-based-srs validate，确保可追溯性

模式 7：最小可行 SRS

用于快速原型或 MVP：

1. 确定 2-3 个核心 CP（仅义务）
2. 创建精简版 Software Glance
3. 推导必要的 CN
4. 仅生成关键 FR
5. 扩展前跳过详细验证

何时使用各项操作

• business-context： 用户正在启动新项目，需要建立结构化背景
• problems： 用户已有业务背景，但尚未整理问题
• software-glance： 用户已有 CP，需要高层次的解决方案概览
• needs： 用户已有 CP + SG，需要明确预期结果
• software-vision： 用户已有 CN，需要编写详细的愿景文档
• functional-requirements： 用户已有 CN + SV，需要制定功能需求
• validate： 用户需要检查可追溯性或一致性
• complexity： 用户明确要求进行公理化设计分析

可选：复杂度分析

如需进行更深入的质量分析，用户可以明确调用 /problem-based-srs complexity 操作，开展基于公理化设计的规格质量分析。适用于关键系统、大型规格或正式评审。这不属于标准流程的一部分。

示例

完整演练请参阅：

• CRM 示例 — 业务领域（客户关系管理）
• MicroER 示例 — 技术领域（可再生能源系统）

根据当前步骤逐项运行操作，以尽量减少上下文用量。