mcpField
S
specify

specify

github.com/ariadoss开发1262 次安装3 天前更新
代码仓库

关于 specify

specify 是一种工作流技能，可将功能描述转化为编号 Git 分支和结构化规格说明。它还涵盖可选的 BuildBetter 上下文收集及反复质量检查，并在完成后报告规划准备情况。

主要功能

  1. 01提炼简短功能分支名
  2. 02检查分支和规格目录编号
  3. 03在可用时收集 BuildBetter 上下文
  4. 04创建并验证功能规格说明
  5. 05报告规划准备情况

适用场景

  1. 01根据书面需求启动功能
  2. 02避免重复使用已有分支编号
  3. 03在规划前检查规格说明

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/ariadoss/superskills --skill specify

安装后在 Claude Code 中输入/specify确认已加载。

详细介绍

模板： 如果你需要下文引用的模板文件（spec-template.md、plan-template.md 等），可在 BB-Skills 仓库的 templates/ 目录中找到。如果已在本地安装，请检查 ~/.bb-skills/templates/ 或项目的 templates/ 目录。

用户输入

$ARGUMENTS

继续之前，你必须考虑用户输入（如果非空）。

大纲

用户调用此技能时输入的文本就是功能描述。假设在本次对话中始终可以获取该描述。除非用户提交了空命令，否则不要要求用户重复输入。

根据该功能描述，执行以下操作：

  1. 为分支生成简洁的短名称（2-4 个词）：

    • 分析功能描述，提取最有意义的关键词
    • 创建一个能体现功能核心的 2-4 词短名称
    • 尽可能使用“动作-名词”格式（例如，“add-user-auth”“fix-payment-bug”）
    • 保留技术术语和缩写（OAuth2、API、JWT 等）
    • 短名称应简洁明了，同时足以让人一眼看懂功能
    • 示例：
      • “我想添加用户身份验证” -> “user-auth”
      • “为 API 实现 OAuth2 集成” -> “oauth2-api-integration”
      • “创建分析仪表盘” -> “analytics-dashboard”
      • “修复支付处理超时错误” -> “fix-payment-timeout”

  2. 创建新分支前检查是否已有分支：

    a. 首先，获取所有远程分支，确保信息是最新的：

    git fetch --all --prune

    b. 从所有来源中查找该短名称对应的最大功能编号：

    • 远程分支：git ls-remote --heads origin | grep -E 'refs/heads/[0-9]+-<short-name>$'
    • 本地分支：git branch | grep -E '^[* ]*[0-9]+-<short-name>$'
    • Specs 目录：检查是否存在与 specs/[0-9]+-<short-name> 匹配的目录

    c. 确定下一个可用编号：

    • 提取所有三个来源中的编号
    • 找出最大编号 N
    • 新分支编号使用 N+1

    d. 创建功能分支和 spec 目录结构：

    • 创建并切换到名为 N+1-<short-name> 的新分支
    • 创建 specs 目录：specs/N+1-<short-name>/
    • 在 specs/N+1-<short-name>/spec.md 初始化 spec 文件

    重要：

    • 检查所有三个来源（远程分支、本地分支、specs 目录），以找到最大编号
    • 仅匹配短名称完全一致的分支/目录
    • 如果不存在具有此短名称的分支/目录，则从编号 1 开始
    • 每个功能只能创建一个分支

  3. 收集 BuildBetter 上下文（尽力而为）：

    • 根据 spec 文件路径推导 FEATURE_DIR。
    • 如果可以收集 BuildBetter 上下文，则运行收集器，根据功能描述收集客户证据。
    • 收集器会写入：
      • FEATURE_DIR/buildbetter-context.json
      • FEATURE_DIR/buildbetter-context.md
      • FEATURE_DIR/user-stories.md
    • 处理收集器状态：
      • ok：直接使用 BuildBetter 证据。
      • partial：使用现有证据，并保留警告。
      • skipped：在没有 BuildBetter 数据的情况下继续，并在 spec 假设中添加说明。
      • error：在没有 BuildBetter 数据的情况下继续，明确发出警告，并保留任何已生成的产物。

  4. 加载 spec 模板和 BuildBetter 产物（如果存在），以了解必需章节和证据上下文。

  5. 按照以下执行流程进行：

    1. 解析 Input 中的用户描述 如果为空：ERROR "No feature description provided"
    2. 从描述和 BuildBetter 证据中提取关键概念 识别：参与者、操作、数据、约束
      • 如果 buildbetter-context.md 中有内容，则提取客户的原话
      • 如果 user-stories.md 中有内容，则提取现有用户故事
      • 如果有证据 ID（BB-EXTRACTION-*），则将每项需求／故事关联到一个或多个证据 ID
    3. 对于不明确之处：
      • 根据上下文和行业标准做出合理推测
      • 仅在以下情况下标记为 [NEEDS CLARIFICATION: specific question]：
        • 该选择会显著影响功能范围或用户体验
        • 存在多种合理解释，且影响各不相同
        • 不存在合理的默认选项
      • 限制：最多使用 3 个 [NEEDS CLARIFICATION] 标记
      • 按影响优先级排列待澄清事项：范围 > 安全／隐私 > 用户体验 > 技术细节
    4. 填写 User Scenarios & Testing 部分 如果无法确定清晰的用户流程：ERROR "Cannot determine user scenarios"
      • 优先列出有证据支持的用户旅程
    5. 生成 Functional Requirements 每项需求都必须可测试 对未指定的细节采用合理的默认值（在 Assumptions 部分记录假设）
    6. 定义 Success Criteria 创建可衡量且与技术无关的成果 同时包含定量指标（时间、性能、数量）和定性指标（用户满意度、任务完成情况） 每项标准都必须在不涉及实现细节的情况下可验证
    7. 识别关键实体（如涉及数据）
    8. 添加证据可追溯性注释：
      • 每个主要用户故事都包含 Evidence References
      • 在相关需求中添加证据 ID
      • 如果 BuildBetter 不可用，明确标记假设并注明这些假设没有证据支持
    9. 返回：SUCCESS（规格说明已准备好进入规划阶段）

  6. 使用模板结构将规格说明写入规格说明文件，并在保留章节顺序和标题的同时，根据功能描述和 BuildBetter 上下文中的具体信息替换占位符。

  7. 规格说明质量验证：初始规格说明写入后，根据质量标准进行验证：

    a. 创建规格说明质量检查清单：使用检查清单模板结构，在 FEATURE_DIR/checklists/requirements.md 创建检查清单文件，并包含以下验证项：

    # Specification Quality Checklist: [FEATURE NAME]

**Purpose**: 在进入规划阶段前验证规格说明的完整性和质量
**Created**: [DATE]
**Feature**: [Link to spec.md]

## Content Quality

- [ ] 不包含实现细节（语言、框架、API）
- [ ] 聚焦于用户价值和业务需求
- [ ] 面向非技术相关方编写
- [ ] 已完成所有必需章节

## Requirement Completeness

- [ ] 不存在 [NEEDS CLARIFICATION] 标记
- [ ] 需求可测试且没有歧义
- [ ] 成功标准可衡量
- [ ] 成功标准与技术无关（不包含实现细节）
- [ ] 已定义所有验收场景
- [ ] 已识别边缘情况
- [ ] 范围界定清晰
- [ ] 已识别依赖项和假设

## Feature Readiness

- [ ] 所有功能需求都有明确的验收标准
- [ ] 用户场景涵盖主要流程
- [ ] 功能满足 Success Criteria 中定义的可衡量结果
- [ ] 规格说明中不包含任何实现细节

## Notes

- 标记为未完成的项目需要在使用 bb-clarify 或 bb-plan 技能前更新规格说明

    b. 运行验证检查：根据清单中的每一项检查规范：

    • 确定每一项是通过还是未通过
    • 记录发现的具体问题（引用相关规范章节）

    c. 处理验证结果：

    • 如果所有项目都通过：将清单标记为已完成，并继续执行步骤 8

    • 如果有项目未通过（不包括 [NEEDS CLARIFICATION]）：

      1. 列出未通过的项目和具体问题
      2. 更新规范以解决每个问题
      3. 重新运行验证，直到所有项目都通过（最多 3 次迭代）
      4. 如果 3 次迭代后仍未通过，在清单备注中记录剩余问题并提醒用户

    • 如果仍有 [NEEDS CLARIFICATION] 标记：

      1. 从规范中提取所有 [NEEDS CLARIFICATION: ...] 标记

      2. 数量限制检查：如果标记超过 3 个，仅保留影响范围、安全性或用户体验最大的 3 个，并对其余标记做出合理推断

      3. 对于每个需要澄清的问题（最多 3 个），按以下格式向用户提供选项：

        ## 问题 [N]：[主题]

**背景**：[引用相关规范章节]

**需要了解的信息**：[NEEDS CLARIFICATION 标记中提出的具体问题]

**建议答案**：

| 选项 | 答案 | 影响 |
|------|------|------|
| A | [第一个建议答案] | [这对该功能意味着什么] |
| B | [第二个建议答案] | [这对该功能意味着什么] |
| C | [第三个建议答案] | [这对该功能意味着什么] |
| 自定义 | 提供您自己的答案 | [说明如何提供自定义输入] |

**您的选择**：_[等待用户回复]_

      4. 关键事项——表格格式：确保 Markdown 表格格式正确：

        • 使用一致的间距，并对齐竖线
        • 每个单元格的内容两侧都应有空格：| 内容 |，而不是 |内容|
        • 表头分隔行至少应有 3 个短横线：|--------|
        • 在 Markdown 预览中检查表格是否正确渲染

      5. 按顺序为问题编号（Q1、Q2、Q3，最多 3 个）

      6. 一次性列出所有问题，然后等待回复

      7. 等待用户回复所有问题的选项（例如，“Q1: A, Q2: 自定义 - [详细信息], Q3: B”）

      8. 将用户选择或提供的答案写入规范，替换每个 [NEEDS CLARIFICATION] 标记

      9. 所有澄清问题解决后，重新运行验证

    d. 更新清单：每次验证迭代后，更新清单文件中的当前通过/未通过状态

  8. 报告完成情况，包括分支名称、规范文件路径、BuildBetter 产物路径、清单结果，以及是否已准备好进入下一阶段（使用 bb-clarify 或 bb-plan 技能）。

一般指南

快速指南

  • 聚焦于用户需要什么以及为什么需要。
  • 避免说明如何实现（不涉及技术栈、API、代码结构）。
  • 面向业务相关方，而非开发人员。
  • 不要在规范中创建内嵌清单。这将由单独的命令处理。
章节要求
  • 必需章节：每个功能都必须填写
  • 可选章节：仅在与该功能相关时添加
  • 如果某个章节不适用，则将其完全删除（不要保留为“无”）
面向 AI 生成

根据用户提示创建此规范时：

  1. 做出有依据的推测：利用上下文、行业标准和常见模式来补全缺失信息
  2. 记录假设：在“假设”部分记录合理的默认值
  3. 限制澄清项：最多使用 3 个 [NEEDS CLARIFICATION] 标记——仅用于以下关键决策：
    • 会显著影响功能范围或用户体验
    • 存在多种合理解释，且会带来不同影响
    • 没有任何合理的默认值
  4. 确定澄清优先级：范围 > 安全/隐私 > 用户体验 > 技术细节
  5. 以测试人员的角度思考：任何模糊的需求都应无法通过“可测试且明确”的检查项
  6. 常见的待澄清领域（仅在没有合理默认值时）：
    • 功能范围和边界（是否包含/排除特定用例）
    • 用户类型和权限（存在多种相互冲突的合理解释时）
    • 安全/合规要求（具有重大法律/财务影响时）

合理默认值示例（无需询问）：

  • 数据保留：采用该领域的行业标准做法
  • 性能目标：除非另有说明，否则采用标准 Web/移动应用的预期
  • 错误处理：提供用户友好的消息和适当的回退方案
  • 身份验证方式：Web 应用采用标准的基于会话或 OAuth2 的方式
  • 集成模式：采用适合项目的模式（Web 服务使用 REST/GraphQL，库使用函数调用，工具使用 CLI 参数等）
成功标准指南

成功标准必须：

  1. 可衡量：包含具体指标（时间、百分比、数量、比率）
  2. 与技术无关：不得提及框架、语言、数据库或工具
  3. 以用户为中心：描述用户/业务成果，而非系统内部情况
  4. 可验证：无需了解实现细节即可测试/验证

好例子：

  • “用户可以在 3 分钟内完成结账”
  • “系统支持 10,000 个并发用户”
  • “95% 的搜索可在 1 秒内返回结果”
  • “任务完成率提高 40%”

坏例子（侧重实现）：

  • “API 响应时间低于 200ms”（过于技术化，应改为“用户可以即时看到结果”）
  • “数据库可处理 1000 TPS”（实现细节，应改为面向用户的指标）
  • “React 组件渲染高效”（特定于框架）
  • “Redis 缓存命中率高于 80%”（特定于技术）

评论

支持 Markdown