ContextQMD
Back to Imewlconverter

Speckit.Specify

.codebuddy/commands/speckit.specify.md

3.3.110.9 KB
Original Source

用户输入

text
$ARGUMENTS

在继续之前, 你必须考虑用户输入(如果不为空).

概述

用户在触发消息中 /speckit.specify 后输入的文本就是功能描述. 假设你始终可以在本次对话中访问它, 即使下面字面上显示 $ARGUMENTS. 除非用户提供了空命令, 否则不要要求用户重复.

基于该功能描述, 执行以下操作:

  1. 为分支生成一个简短名称(2-4个词):

    • 分析功能描述并提取最有意义的关键词
    • 创建一个2-4个词的简短名称, 捕捉功能的核心
    • 尽可能使用动-名词格式(例如, "add-user-auth", "fix-payment-bug")
    • 保留技术术语和缩写(OAuth2、API、JWT等)
    • 保持简洁但足够描述性, 便于快速理解功能
    • 示例:
      • "I want to add user authentication" → "user-auth"
      • "Implement OAuth2 integration for the API" → "oauth2-api-integration"
      • "Create a dashboard for analytics" → "analytics-dashboard"
      • "Fix payment processing timeout bug" → "fix-payment-timeout"

  2. 在创建新分支之前检查现有分支:

    a. 首先, 获取所有远程分支以确保我们有最新信息:

    bash
    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/[0-9]+-<short-name> 的目录

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

    • 从所有三个来源提取所有编号
    • 找到最高编号 N
    • 对新分支编号使用 N+1

    d. 使用计算出的编号和简短名称运行脚本 .specify/scripts/bash/create-new-feature.sh --json "$ARGUMENTS":

    • 传递 --number N+1 和 --short-name "your-short-name" 以及功能描述
    • Bash 示例: .specify/scripts/bash/create-new-feature.sh --json "$ARGUMENTS" --json --number 5 --short-name "user-auth" "添加用户认证"
    • PowerShell 示例: .specify/scripts/bash/create-new-feature.sh --json "$ARGUMENTS" -Json -Number 5 -ShortName "user-auth" "添加用户认证"

    重要说明:

    • 检查所有三个来源(远程分支、本地分支、规范目录)以找到最高编号
    • 仅匹配具有精确简短名称模式的分支/目录
    • 如果没有找到具有此简短名称的现有分支/目录, 从编号 1 开始
    • 你必须且只能运行此脚本一次
    • JSON 在终端中作为输出提供 - 请始终参考它以获取你要查找的实际内容
    • JSON 输出将包含 BRANCH_NAME 和 SPEC_FILE 路径
    • 对于参数中的单引号(如 "I'm Groot"), 使用转义语法: 例如 'I'''m Groot'(或尽可能使用双引号: "I'm Groot")

  3. 加载 .specify/templates/spec-template.md 以了解必需的章节.

  4. 遵循此执行流程:

    1. 从输入解析用户描述 如果为空: 错误 "未提供功能描述"
    2. 从描述中提取关键概念 识别: 参与者、操作、数据、约束
    3. 对于不明确的方面:
      • 基于上下文和行业标准做出有根据的猜测
      • 仅在以下情况下标记为 [NEEDS CLARIFICATION: 具体问题]:
        • 选择显著影响功能范围或用户体验
        • 存在多个合理的解释且有不同的含义
        • 没有合理的默认值
      • 限制: 最多 3 个 [NEEDS CLARIFICATION] 标记
      • 按影响优先级排序: 范围 > 安全/隐私 > 用户体验 > 技术细节
    4. 填写用户场景和测试章节 如果没有明确的用户流程: 错误 "无法确定用户场景"
    5. 生成功能需求 每个需求必须是可测试的 对未指定的细节使用合理的默认值(在假设章节中记录假设)
    6. 定义成功标准 创建可衡量的、技术无关的结果 包括定量指标(时间、性能、数量)和定性措施(用户满意度、任务完成) 每个标准必须无需实现细节即可验证
    7. 识别关键实体(如果涉及数据)
    8. 返回: 成功(规范准备好进行规划)

  5. 使用模板结构将规范写入 SPEC_FILE, 用从功能描述(参数)派生的具体细节替换占位符, 同时保持章节顺序和标题.

  6. 规范质量验证: 编写初始规范后, 根据质量标准进行验证:

    a. 创建规范质量检查清单: 使用检查清单模板结构在 FEATURE_DIR/checklists/requirements.md 生成检查清单文件, 包含这些验证项目:

    markdown
    # 规范质量检查清单: [功能名称]

**目的**: 在继续规划之前验证规范的完整性和质量
**创建时间**: [日期]
**功能**: [指向 spec.md 的链接]

## 内容质量

- [ ] 无实现细节(语言、框架、API)
- [ ] 专注于用户价值和业务需求
- [ ] 为非技术利益相关者编写
- [ ] 所有必需章节已完成

## 需求完整性

- [ ] 没有 [NEEDS CLARIFICATION] 标记剩余
- [ ] 需求是可测试且明确的
- [ ] 成功标准是可衡量的
- [ ] 成功标准是技术无关的(无实现细节)
- [ ] 所有验收场景已定义
- [ ] 边缘情况已识别
- [ ] 范围明确界定
- [ ] 依赖关系和假设已识别

## 功能准备就绪

- [ ] 所有功能需求都有明确的验收标准
- [ ] 用户场景覆盖主要流程
- [ ] 功能满足成功标准中定义的可衡量结果
- [ ] 没有实现细节泄漏到规范中

## 备注

- 标记为不完整的项目需要在 `/speckit.clarify` 或 `/speckit.plan` 之前更新规范

    b. 运行验证检查: 根据每个检查清单项目审查规范:

    • 对于每个项目, 确定是否通过或失败
    • 记录发现的具体问题(引用相关规范章节)

    c. 处理验证结果:

    • 如果所有项目都通过: 标记检查清单完成并继续步骤 7

    • 如果项目失败(不包括 [NEEDS CLARIFICATION]):

      1. 列出失败的项目和具体问题
      2. 更新规范以解决每个问题
      3. 重新运行验证直到所有项目都通过(最多 3 次迭代)
      4. 如果 3 次迭代后仍然失败, 在检查清单备注中记录剩余问题并警告用户

    • 如果 [NEEDS CLARIFICATION] 标记仍然存在:

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

      2. 限制检查: 如果存在超过 3 个标记, 仅保留 3 个最关键的(按范围/安全/用户体验影响)并为其余部分做出有根据的猜测

      3. 对于每个需要的澄清(最多 3 个), 以以下格式向用户呈现选项:

        markdown
        ## 问题 [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. 更新检查清单: 每次验证迭代后, 使用当前的通过/失败状态更新检查清单文件

  7. 报告完成情况, 包括分支名称、规范文件路径、检查清单结果以及下一阶段(/speckit.clarify 或 /speckit.plan)的准备就绪状态.

注意: 脚本在写入之前创建并检出新分支并初始化规范文件.

通用指南

快速指南

  • 专注于用户需要什么和为什么.
  • 避免如何实现(不涉及技术栈、API、代码结构).
  • 为业务利益相关者编写, 而不是为开发者.
  • 不要创建嵌入规范中的任何检查清单. 那将是一个单独的命令.

章节要求

  • 必需章节: 每个功能必须完成
  • 可选章节: 仅在与功能相关时包含
  • 当章节不适用时, 完全删除它(不要保留为 "N/A")

AI 生成

当从用户提示创建此规范时:

  1. 做出有根据的猜测: 使用上下文、行业标准和常见模式来填补空白
  2. 记录假设: 在假设章节中记录合理的默认值
  3. 限制澄清: 最多 3 个 [NEEDS CLARIFICATION] 标记 - 仅用于关键决策:
    • 显著影响功能范围或用户体验
    • 存在多个合理的解释且有不同的含义
    • 缺乏任何合理的默认值
  4. 优先澄清: 范围 > 安全/隐私 > 用户体验 > 技术细节
  5. 像测试人员一样思考: 每个模糊的需求都应该在"可测试且明确"的检查清单项目上失败
  6. NEEDS CLARIFICATION 的常见领域(仅在没有合理默认值时):
    • 功能范围和边界(包含/排除特定用例)
    • 用户类型和权限(如果可能存在多个冲突的解释)
    • 安全/合规要求(当具有法律/财务重要性时)

合理默认值的示例(不要询问这些):

  • 数据保留: 该行业的行业标准实践
  • 性能目标: 标准 Web/移动应用期望, 除非另有说明
  • 错误处理: 用户友好的消息和适当的回退
  • 认证方法: Web 应用的标准基于会话或 OAuth2
  • 集成模式: RESTful API, 除非另有说明

成功标准指南

成功标准必须是:

  1. 可衡量的: 包括具体指标(时间、百分比、计数、速率)
  2. 技术无关的: 不提及框架、语言、数据库或工具
  3. 以用户为中心的: 从用户/业务角度描述结果, 而不是系统内部
  4. 可验证的: 无需了解实现细节即可测试/验证

好的示例:

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

坏的示例(以实现为中心):

  • "API 响应时间在 200ms 以下"(太技术化, 使用"用户立即看到结果")
  • "数据库可以处理 1000 TPS"(实现细节, 使用面向用户的指标)
  • "React 组件高效渲染"(框架特定)
  • "Redis 缓存命中率超过 80%"(技术特定)