spec-gathering

需求收集技能

概述

通过结构化提问收集用户需求，并生成经过验证的需求文档。此技能可将模糊的任务描述转化为可执行的结构化需求。

核心原则： 提出明智的问题，生成有效的结构化输出。除此之外，不做其他事情。

使用时机

始终适用：

• 开始开发新功能或新项目时
• 澄清含糊不清的任务描述时
• 用户只提供了高层目标，未说明具体细节时
• 开始编写规格说明前

例外情况：

• 复现步骤明确的简单 Bug 修复
• 范围显而易见的单文件修改
• 用户明确提供了完整需求

铁律

NO SPEC WRITING WITHOUT VALIDATED REQUIREMENTS FIRST

开始编写规格说明前，必须先让用户确认需求。

工作流

阶段 1：加载项目上下文

与用户交流前，先了解项目结构。

步骤：

1. 如果项目结构文件存在，则阅读这些文件
2. 确定服务、技术栈和端口
3. 了解现有模式和约定

# Read project structure
cat .claude/context/product.md 2>/dev/null || echo "No product context"
cat .claude/context/tech-stack.md 2>/dev/null || echo "No tech stack"

阶段 2：了解任务

如果用户提供了任务描述，请先确认：

“我理解您想要：［任务描述］。这样理解正确吗？还有需要澄清的地方吗？”

如果用户没有提供任务，请询问：

“您想要构建或修复什么？请描述您需要的功能、Bug 或更改。”

等待用户回复。

阶段 3：确定工作流类型

根据任务确定工作流类型：

如果任务听起来像……	工作流类型
“添加功能 X”、“构建 Y”	feature
“从 X 迁移到 Y”、“重构 Z”	refactor
“修复 X 导致的 Bug”、“调试 Y”	investigation
“从 X 迁移数据”	migration
单个服务的小型更改	simple

请用户确认：

“这听起来像是一个 ［workflow_type］ 任务。您觉得合适吗？”

阶段 4：确定服务和范围

根据项目上下文和任务，提出可能受影响的部分：

“根据您的任务和项目结构，我认为涉及：

• ［service1］（主要）- ［原因］
• ［service2］（集成）- ［原因］

还涉及其他服务或部分吗？”

等待用户确认或纠正。

阶段 4.5：调用 Context-Compressor（渐进式披露模式 / ECLAIR 模式）

手动收集需求前，使用 context-compressor 技能（渐进式披露模式）优化澄清流程：

Skill({
  skill: 'context-compressor',
  context: {
    taskDescription: taskDescription,
    projectContext: projectContext,
    services: identifiedServices,
    mode: 'progressive-disclosure',
  },
});

Context-Compressor（渐进式披露模式）会执行：

1. E：检查 - 分析任务描述中的歧义
2. C：分类 - 按 CRITICAL、HIGH、MEDIUM、LOW 优先级排序
3. L：限制 - 将澄清问题数量限制为 3-5 个
4. A：假设 - 根据项目模式应用合理的默认值
5. I：推断 - 利用现有代码模式和技术栈
6. R：记录 - 使用 [ASSUMES: X] 记录所有假设

返回内容：

• 按优先级排序的澄清问题（最多 5 个）
• 使用 [ASSUMES:] 标记的合理默认值
• 更新后的需求理解

阶段 5：收集详细需求（使用 Context-Compressor）

只提出 Context-Compressor 确定的关键澄清问题：

预算： 最多提出 3-5 个澄清问题

流程：

1. 优先询问 CRITICAL 级别的问题（安全、数据丢失、破坏性更改）

   • 示例：“系统是否需要基于角色的访问控制？”
   • 示例：“用户是否可以删除数据？此操作可撤销吗？”

2. 如果预算允许，再询问 HIGH 级别的问题（用户体验、架构、可扩展性）

   • 示例：“预期用户负载是多少？”
   • 示例：“是否需要支持离线模式？”

3. 对于 MEDIUM/LOW 级别的问题，使用 [ASSUMES:] 标记并应用默认值

   • 示例：“[ASSUMES: JWT 令牌有效期为 1 小时]”
   • 示例：“[ASSUMES: REST API 遵循现有的 /api/v1/ 模式]”

收集回答并记录所有假设。

阶段 6：确认并输出（包含假设）

总结你理解的内容，包括已澄清的需求和假设：

“请确认我理解得是否正确：

任务：[摘要] 类型：[workflow_type] 范围：[受影响区域列表]

已澄清的需求（已提出的问题）：

1. ✅ [问题] → [答案]
2. ✅ [问题] → [答案]
3. ✅ [问题] → [答案]

已应用的智能默认值（因预算限制或内容明确而未询问）：

[ASSUMES: X] [ASSUMES: Y] [ASSUMES: Z]

成功标准：

1. [标准 1]
2. [标准 2]

这样正确吗？”

等待用户确认。如果用户反对任何假设，允许他们修改假设或请求调整。

阶段 7：将需求映射到模板令牌（包含假设）

与用户确认需求和假设后，将收集到的数据映射到模板令牌：

const tokens = {
  // Required tokens
  FEATURE_NAME: gatheredRequirements.taskName,
  VERSION: '1.0.0',
  AUTHOR: 'Claude',
  DATE: new Date().toISOString().split('T')[0],
  STATUS: 'draft',

  // Required: Acceptance criteria (minimum 1, maximum 50)
  ACCEPTANCE_CRITERIA_1: gatheredRequirements.criteria[0] || '[Define acceptance criterion 1]',
  ACCEPTANCE_CRITERIA_2: gatheredRequirements.criteria[1] || '[Define acceptance criterion 2]',
  ACCEPTANCE_CRITERIA_3: gatheredRequirements.criteria[2] || '[Define acceptance criterion 3]',

  // Optional tokens (can be empty strings if not gathered)
  TERM_1: gatheredRequirements.terms?.[0] || '',
  TERM_2: gatheredRequirements.terms?.[1] || '',
  TERM_3: gatheredRequirements.terms?.[2] || '',

  HTTP_METHOD: gatheredRequirements.httpMethod || '',
  ENDPOINT_PATH: gatheredRequirements.endpointPath || '',
  PROJECT_NAME: gatheredRequirements.projectName || 'Agent Studio',

  // Assumptions from context-compressor (optional but recommended)
  ASSUMPTIONS_MADE: gatheredRequirements.assumptions.map(a => `- ${a}`).join('\n') || '',
  CLARIFICATIONS_ASKED: gatheredRequirements.clarifications || 0,
};

渲染前验证：

• 检查所有必填令牌均已填充（FEATURE_NAME、VERSION、AUTHOR、DATE、STATUS）
• 检查至少有一个 ACCEPTANCECRITERIA* 令牌内容有意义（不是占位符）
• 验证所有假设均使用 [ASSUMES:] 标记记录
• 如果缺少必需数据，提示用户补充
• 如果澄清问题超过 5 个，提醒用户需求可能不完整

阶段 8：通过模板渲染规格说明

调用 template-renderer skill 来创建规格说明：

Skill({
  skill: 'template-renderer',
  args: {
    templateName: 'specification-template',
    outputPath: `.claude/context/artifacts/specifications/${featureNameSlug}-spec.md`,
    tokens: tokens,
  },
});

输出位置：.claude/context/artifacts/specifications/[feature-name]-spec.md

渲染后验证：

# Check file created
SPEC_FILE=".claude/context/artifacts/specifications/[feature-name]-spec.md"
test -f "$SPEC_FILE" && echo "✓ Spec created" || echo "✗ Spec creation failed"

# Check no unresolved tokens
grep -E '[{]{2}' "$SPEC_FILE" && echo "✗ Unresolved tokens found" || echo "✓ All tokens resolved"

# Check YAML frontmatter valid
YAML_COUNT=$(head -50 "$SPEC_FILE" | grep -E "^---$" | wc -l)
test "$YAML_COUNT" -eq 2 && echo "✓ YAML valid" || echo "✗ YAML invalid"

验证清单

完成需求收集之前：

• 已与用户确认任务描述
• 已以渐进式披露模式调用 context-compressor skill（阶段 4.5）
• 遵守澄清问题数量限制（最多 3–5 个问题）
• 已提出并回答 CRITICAL 优先级问题
• 所有假设均使用 [ASSUMES:] 标记记录
• 已确定并确认工作流类型
• 已识别范围和受影响区域
• 已记录具体需求
• 已定义验收标准（至少 1 项，并映射到 ACCEPTANCE_CRITERIA_1/2/3）
• 已记录约束条件
• 用户已确认最终摘要（包括假设）
• 继续之前，用户可以修改任何假设
• 已完成令牌映射（所有必填令牌均已填充，包括 ASSUMPTIONS_MADE）
• 已成功调用模板渲染器
• 已创建规格说明文件（没有未解决的令牌）
• YAML frontmatter 有效（包含 2 个分隔符，且已填写必填字段）
• 规格说明输出中包含 [ASSUMES:] 标记

常见错误

一味假设，而不提问

错误原因： 假设可能导致最终构建的内容不符合需求。

正确做法： 提出澄清问题，确认你理解正确。

跳过确认

错误原因： 用户可能误解了你的摘要。

正确做法： 始终总结并等待用户明确确认。

需求含糊

错误原因： “做得更好”无法直接落实。

正确做法： 询问具体内容：需要什么行为？预期结果是什么？如何验证？

与其他技能集成

此技能与以下技能配合良好：

• context-compressor：在阶段 4.5（渐进式披露模式）中调用，使用 ECLAIR 模式（3-5 个问题上限、智能默认值、[ASSUMES:] 标记）优化澄清流程
• template-renderer：在阶段 8 后自动使用，将收集到的需求和假设填入规格说明模板
• spec-critique：用于验证生成的规格说明
• complexity-assessment：在需求明确后评估复杂度
• brainstorming：在收集需求前用于创意探索

工作流链：

spec-gathering (→ context-compressor in Phase 4.5) → template-renderer → spec-critique → planner

Context-Compressor 集成详情（渐进式披露模式）：

• 时机：在阶段 5 开始时调用（手动提问前）
• 原因：将澄清问题限制在 3-5 个（降低认知负担）、应用智能默认值，并记录所有假设
• 输出：按优先级排序的问题 + 使用 [ASSUMES:] 标记的默认假设
• 影响：规格说明中包含已记录的假设，这些假设可在实现期间覆盖

示例

示例 1：功能请求（端到端，使用渐进式披露和模板渲染）

输入：“为应用添加用户身份验证”

流程：

1. 确认任务：“你想添加用户身份验证。对吗？”

   • 用户确认

2. 以渐进式披露模式调用 context-compressor（阶段 4.5）：

   Skill({
     skill: 'context-compressor',
     context: {
       taskDescription: "Add user authentication",
       projectContext: {...},
       mode: 'progressive-disclosure'
     }
   });
   

3. Context-compressor 返回：

   • 关键问题（在 5 个问题额度中提问 3 个）：

     1. “用户是否应能够通过电子邮件重置密码？”→ 是
     2. “我们是否需要基于角色的访问控制（RBAC）？”→ 是（管理员、用户、访客）
     3. “是否需要单点登录（SSO）？”→ 否

   • 应用的假设（带有 [ASSUMES:]）：

     • [ASSUMES: JWT 令牌的有效期为 1 小时]
     • [ASSUMES: 使用 bcrypt 对密码进行哈希处理，成本因子为 12]
     • [ASSUMES: 所有端点均需使用 HTTPS]

4. 确定范围：“这会涉及后端 API、数据库和前端登录页面。”

   • 用户确认范围

5. 根据澄清结果和默认值定义成功标准

6. 映射到令牌：

{
  FEATURE_NAME: "User Authentication",
  VERSION: "1.0.0",
  AUTHOR: "Claude",
  DATE: "2026-01-28",
  STATUS: "draft",
  ACCEPTANCE_CRITERIA_1: "Users can sign up with email and password",
  ACCEPTANCE_CRITERIA_2: "Email verification required before login",
  ACCEPTANCE_CRITERIA_3: "Users can reset password via email link",
  ACCEPTANCE_CRITERIA_4: "Role-based access control working (Admin/User/Guest)",
  ASSUMPTIONS_MADE: "- JWT tokens with 1-hour expiry\n- bcrypt cost factor 12\n- HTTPS required",
  CLARIFICATIONS_ASKED: 3
}

1. 调用 template-renderer：

Skill({
  skill: 'template-renderer',
  args: {
    templateName: 'specification-template',
    outputPath: '.claude/context/artifacts/specifications/user-authentication-spec.md',
    tokens: tokens,
  },
});

输出：

• 渲染后的规格说明位于 .claude/context/artifacts/specifications/user-authentication-spec.md
• 所有令牌均已解析
• 使用 [ASSUMES:] 标记清晰记录假设
• YAML frontmatter 有效
• 可交由 spec-critique 审核（用户可对任何假设提出质疑）

示例 2：Bug 调查

输入：“页面加载很慢”

流程：

1. 澄清：“具体是哪个页面？你认为多慢才算慢？”
2. 上下文：“这是从什么时候开始的？最近有任何更改吗？”
3. 指标：“什么样的加载时间可以接受？”

**输出：**包含具体页面、指标和成功标准的调查需求。

故障排除

问题：用户只给出一个词的回答

**症状：**只回答“是”“否”“可以”，没有详细说明。

**解决方案：**提出更具体的问题。提供选项：“你更倾向于 A、B 还是 C？”

问题：范围不断扩大

**症状：**每个回答都会增加新功能。

**解决方案：**明确记录“不在范围内”的内容。确认：“我们应该将此纳入当前任务，还是留待以后处理？”

铁律

1. 对于 STANDARD+ 复杂度，绝不要在规格说明通过验证前开始实现
2. 始终明确记录非功能性需求（性能、安全性、可扩展性）
3. 绝不要接受含糊的成功标准——要求提供可衡量、可测试的数值
4. 始终记录明确不在范围内的内容，而不只是范围内的内容
5. 绝不要在用户明确确认需求前将任务交给规划器

反模式

反模式	失败原因	正确做法
需求含糊（“让它更快”）	无法衡量或测试	明确指定指标：“P95 响应时间 <100ms”
缺少非功能性需求	质量属性直到为时已晚才被想起	始终记录性能、安全性和可扩展性要求
未列出范围之外的内容	实施期间范围不断扩大	明确记录此任务不包括哪些内容
跳过用户确认	误解需求并导致实施错误	交接前与用户确认所有需求
未记录边界情况	QA 阶段才发现错误处理方面的缺口	记录空输入、错误数据、超时和并发访问等情况

记忆协议

开始前： 阅读 .claude/context/memory/learnings.md

完成后：

• 新模式 -> .claude/context/memory/learnings.md
• 发现问题 -> .claude/context/memory/issues.md
• 做出决策 -> .claude/context/memory/decisions.md

假设会发生中断：如果没有记录在记忆中，就等于没发生。