name: 规格收集 description: ‘用于规格创建的需求收集工作流。当开始新功能、任务或需要结构化需求的项目时使用。’ version: 1.0.0 model: sonnet invoked_by: both user_invocable: true tools: [读取, 写入, 编辑, Bash, 向用户提问] best_practices:

提出智能问题，生成结构化输出
在继续前确认理解
尽早识别服务和依赖关系 error_handling: 优雅处理 streaming: 支持 source: auto-claude verified: false lastVerifiedAt: 2026-02-19T05:29:09.098Z

需求收集技能

概述

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

核心原则： 提出智能问题，生成有效的结构化输出。仅此而已。

何时使用

始终使用：

开始新功能或项目时
澄清模糊的任务描述时
当用户提供高层次目标而无具体细节时
在规格编写开始前

例外情况：

具有清晰复现步骤的简单错误修复
范围明显的单文件更改
用户明确提供完整需求时

铁律

未经验证的需求，不得编写规格

需求必须在用户确认后才能进行规格创建。

工作流程

阶段 1: 加载项目上下文

在联系用户前理解项目结构。

步骤：

如果存在，读取项目结构文件
识别服务、技术栈和端口
理解现有模式和约定

# 读取项目结构
cat .claude/context/product.md 2>/dev/null || echo "无产品上下文"
cat .claude/context/tech-stack.md 2>/dev/null || echo "无技术栈"

阶段 2: 理解任务

如果提供了任务描述，确认它：

“我理解您想要：[任务描述]。这是正确的吗？有任何澄清吗？”

如果未提供任务，询问：

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

等待用户响应。

阶段 3: 确定工作流程类型

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

如果任务听起来像…	工作流程类型
“添加功能 X”、“构建 Y”	`功能`
“从 X 迁移到 Y”、“重构 Z”	`重构`
“修复错误 X”、“调试 Y”	`调查`
“从 X 迁移数据”	`迁移`
单一服务，小更改	`简单`

确认：

“这听起来像是一个 [工作流程类型] 任务。对吗？”

阶段 4: 识别服务和范围

基于项目上下文和任务，建议受影响区域：

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

[服务1] (主要) - [原因]

[服务2] (集成) - [原因]

还有其他服务或区域涉及吗？"

等待确认或修正。

阶段 4.5: 调用渐进披露 (ECLAIR 模式)

在手动收集需求前，使用渐进披露技能优化澄清过程：

Skill({
  skill: '渐进披露',
  context: {
    taskDescription: 任务描述,
    projectContext: 项目上下文,
    services: 识别的服务,
  },
});

渐进披露执行：

E: 检查 - 分析任务描述中的模糊性
C: 分类 - 按 CRITICAL、HIGH、MEDIUM、LOW 优先级
L: 限制 - 应用 3-5 个澄清上限
A: 假设 - 从项目模式应用智能默认值
I: 推断 - 使用现有代码模式和技术栈
R: 记录 - 用 [ASSUMES: X] 记录所有假设

返回：

优先澄清问题 (最多 5 个)
带 [ASSUMES:] 记号的智能默认值
更新后的需求理解

阶段 5: 收集详细需求 (使用渐进披露)

仅询问渐进披露识别的关键澄清问题：

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

过程：

首先询问 CRITICAL 优先级问题 (安全、数据丢失、破坏性更改)
- 示例：“系统是否需要基于角色的访问控制？”
- 示例：“用户应该能够删除数据吗？这是可逆的吗？”
如果预算允许，询问 HIGH 优先级问题 (UX、架构、可扩展性)
- 示例：“预期的用户负载是多少？”
- 示例：“这应该支持离线模式吗？”
对于 MEDIUM/LOW 优先级，使用 [ASSUMES:] 记号带默认值
- 示例：“[ASSUMES: JWT 令牌，1 小时过期]”
- 示例：“[ASSUMES: REST API 遵循现有 /api/v1/ 模式]”

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

阶段 6: 确认和输出 (带假设)

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

"让我确认我理解：

任务： [摘要] 类型： [工作流程类型] 范围： [受影响区域列表]

澄清后的需求 (已询问的问题)：

✅ [问题] → [答案]

✅ [问题] → [答案]

✅ [问题] → [答案]

应用的智能默认值 (由于预算或清晰度未询问)：

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

成功标准：

[标准 1]

[标准 2]

这是正确的吗？"

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

阶段 7: 映射需求到模板令牌 (带假设)

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

const tokens = {
  // 必需令牌
  FEATURE_NAME: gatheredRequirements.taskName,
  VERSION: '1.0.0',
  AUTHOR: 'Claude',
  DATE: new Date().toISOString().split('T')[0],
  STATUS: '草案',

  // 必需: 接受标准 (最少 1，最多 50)
  ACCEPTANCE_CRITERIA_1: gatheredRequirements.criteria[0] || '[定义接受标准 1]',
  ACCEPTANCE_CRITERIA_2: gatheredRequirements.criteria[1] || '[定义接受标准 2]',
  ACCEPTANCE_CRITERIA_3: gatheredRequirements.criteria[2] || '[定义接受标准 3]',

  // 可选令牌 (如果未收集，可以为空字符串)
  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_MADE: gatheredRequirements.assumptions.map(a => `- ${a}`).join('
') || '',
  CLARIFICATIONS_ASKED: gatheredRequirements.clarifications || 0,
};

渲染前验证：

检查所有必需令牌已填充 (FEATURE_NAME, VERSION, AUTHOR, DATE, STATUS)
检查至少一个 ACCEPTANCECRITERIA* 令牌有意义 (非占位符)
验证所有假设用 [ASSUMES:] 记号记录
如果缺少必需数据，提示用户提供缺失信息
如果澄清 > 5，警告用户潜在需求不完整

阶段 8: 通过模板渲染规格

调用 模板渲染器 技能创建规格：

Skill({
  skill: '模板渲染器',
  args: {
    templateName: '规格模板',
    outputPath: `.claude/context/artifacts/specifications/${featureNameSlug}-spec.md`,
    tokens: tokens,
  },
});

输出位置： .claude/context/artifacts/specifications/[功能名称]-spec.md

渲染后验证：

# 检查文件创建
SPEC_FILE=".claude/context/artifacts/specifications/[功能名称]-spec.md"
test -f "$SPEC_FILE" && echo "✓ 规格创建" || echo "✗ 规格创建失败"

# 检查无未解析令牌
grep "{{" "$SPEC_FILE" && echo "✗ 发现未解析令牌" || echo "✓ 所有令牌已解析"

# 检查 YAML 前文有效
YAML_COUNT=$(head -50 "$SPEC_FILE" | grep -E "^---$" | wc -l)
test "$YAML_COUNT" -eq 2 && echo "✓ YAML 有效" || echo "✗ YAML 无效"

验证清单

完成需求收集前：

[ ] 任务描述已与用户确认
[ ] 渐进披露技能已调用 (阶段 4.5)
[ ] 澄清预算已尊重 (最多 3-5 个问题)
[ ] CRITICAL 优先级问题已询问并回答
[ ] 所有假设用 [ASSUMES:] 记号记录
[ ] 工作流程类型已确定并确认
[ ] 范围和受影响区域已识别
[ ] 具体需求已捕获
[ ] 接受标准已定义 (最少 1，映射到 ACCEPTANCE_CRITERIA_1/2/3)
[ ] 约束已记录
[ ] 用户确认最终摘要 (包括假设)
[ ] 用户允许在继续前覆盖任何假设
[ ] 令牌映射完成 (所有必需令牌已填充，包括 ASSUMPTIONS_MADE)
[ ] 模板渲染器已成功调用
[ ] 规格文件已创建 (无未解析令牌)
[ ] YAML 前文有效 (2 个分隔符，必需字段存在)
[ ] [ASSUMES:] 记号出现在规格输出中

常见错误

假设而非询问

为什么错： 假设导致构建错误的东西。

应做： 询问澄清问题。确认理解。

跳过确认

为什么错： 用户可能误解您的摘要。

应做： 总是总结并等待明确确认。

模糊需求

为什么错： “让它更好”不可操作。

应做： 获取具体：什么行为？什么结果？如何验证？

与其他技能的集成

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

渐进披露：在阶段 4.5 调用，以优化澄清过程与 ECLAIR 模式 (3-5 限制，智能默认值，[ASSUMES:] 记号)
模板渲染器：在阶段 8 后自动使用，以用收集的需求和假设渲染规格模板
规格批判：用于验证生成的规格
复杂度评估：需求清晰后评估复杂度
头脑风暴：用于需求收集前的创意探索

工作流程链：

规格收集 (→ 渐进披露在阶段 4.5) → 模板渲染器 → 规格批判 → 规划器

渐进披露集成详情：

何时：在阶段 5 开始前调用 (手动提问前)
为何：限制澄清到 3-5 个问题 (减少认知负载)，应用智能默认值，记录所有假设
输出：优先问题 + 带 [ASSUMES:] 记号的默认假设
影响：规格包括记录的假设，可在实施期间覆盖

示例

示例 1: 功能请求 (端到端带渐进披露和模板渲染)

输入： “为应用添加用户认证”

过程：

确认任务： “您想添加用户认证。这是正确的吗？”
- 用户确认

调用渐进披露 (阶段 4.5)：

Skill({
  skill: '渐进披露',
  context: {
    taskDescription: "添加用户认证",
    projectContext: {...}
  }
});

渐进披露返回：
- CRITICAL 问题 (3 个问题，预算 5)：
  1. “用户应该能够通过电子邮件重置密码吗？” → 是
  2. “我们需要基于角色的访问控制 (RBAC) 吗？” → 是 (管理员、用户、访客)
  3. “需要单点登录 (SSO) 吗？” → 否
- 应用的假设 (带 [ASSUMES:])：
  - [ASSUMES: JWT 令牌，1 小时过期]
  - [ASSUMES: bcrypt 用于密码哈希，成本因子 12]
  - [ASSUMES: HTTPS 对所有端点必需]
识别范围： “这将涉及后端 API、数据库和前端登录页面。”
- 用户确认范围
基于澄清和默认值定义成功标准
映射到令牌：

{
  FEATURE_NAME: "用户认证",
  VERSION: "1.0.0",
  AUTHOR: "Claude",
  DATE: "2026-01-28",
  STATUS: "草案",
  ACCEPTANCE_CRITERIA_1: "用户可以用电子邮件和密码注册",
  ACCEPTANCE_CRITERIA_2: "登录前需要电子邮件验证",
  ACCEPTANCE_CRITERIA_3: "用户可以通过电子邮件链接重置密码",
  ACCEPTANCE_CRITERIA_4: "基于角色的访问控制工作 (管理员/用户/访客)",
  ASSUMPTIONS_MADE: "- JWT 令牌，1 小时过期
- bcrypt 成本因子 12
- HTTPS 必需",
  CLARIFICATIONS_ASKED: 3
}

调用模板渲染器：

Skill({
  skill: '模板渲染器',
  args: {
    templateName: '规格模板',
    outputPath: '.claude/context/artifacts/specifications/user-authentication-spec.md',
    tokens: tokens,
  },
});

输出：

渲染的规格在 .claude/context/artifacts/specifications/user-authentication-spec.md
所有令牌已解析
假设用 [ASSUMES:] 记号清晰记录
YAML 前文有效
准备进行规格批判审查 (用户可以挑战任何假设)

示例 2: 错误调查

输入： “页面加载缓慢”

过程：

澄清： “具体哪个页面？您认为什么是慢？”
上下文： “这什么时候开始的？有任何最近更改吗？”
指标： “可接受的加载时间是多少？”

输出： 具有特定页面、指标和成功标准的调查需求。

故障排除

问题: 用户给出单字答案

症状： “是”、“否”、“那很好”无细节。

解决方案： 询问更具体的问题。提供选项： “您更喜欢 A、B 还是 C？”

问题: 范围不断扩展

症状： 每个答案添加新功能。

解决方案： 明确记录“范围外”。确认： “我们应该包括在此任务中还是留待以后？”

记忆协议

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

完成后：

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

假设中断：如果不在记忆中，它就没发生。