speckit-specify-zh

用户输入

$ARGUMENTS

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

大纲

触发消息中用户在触发词后键入的文本就是功能描述。假设在此对话中始终可以使用该功能描述，即 $ARGUMENTS。除非用户提供了一个空命令，否则不要要求用户重复。

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

1. 将 assets/specify/ 所有文件（包括子目录）按原目录结构复制到仓库根目录下的.specify 目录，跳过已有文件，不能覆盖原有同名文件。cp命令的 -n（–no-clobber）选项可以防止覆盖已存在的文件。 在此阶段，您的项目文件夹内容应类似于以下内容：

仓库根目录
└── .specify
    ├── memory
    │  └── constitution.md
    ├── scripts
    │  ├──bash    
    │  │  ├── check-prerequisites.sh
    │  │  ├── common.sh
    │  │  ├── create-new-feature.sh
    │  │  ├── setup-plan.sh
    │  │  └── update-claude-md.sh
    │  ├──powershell    
    │  │  ├── check-prerequisites.ps1
    │  │  ├── common.ps1
    │  │  ├── create-new-feature.ps1
    │  │  ├── setup-plan.ps1
    │  │  └── update-claude-md.ps1    
    ├── specs
    │  └── 001-create-taskify
    │      └── spec.md
    └── templates
        ├── plan-template.md
        ├── spec-template.md
        └── tasks-template.md

2. 生成一个简洁的短名称（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”

3. 在创建新分支前检查现有分支：

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

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

   • 提取所有三个来源的所有数字
   • 找到最大数字N
   • 对于新分支使用N+1

   d. 使用计算出的编号和短名称运行脚本 create-new-feature.ps1 -Json "$ARGUMENTS"：

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

   重要：

   • 检查所有三个来源（远程分支、本地分支、规范目录）以找到最高编号
   • 只匹配具有确切短名称模式的分支/目录
   • 如果未找到具有此短名称的现有分支/目录，则从编号1开始
   • 每个功能只能运行一次此脚本
   • JSON在终端中作为输出提供 – 始终参考它来获取您正在查找的实际内容
   • JSON输出将包含BRANCH_NAME和SPEC_FILE路径
   • 对于参数中的单引号如”I’m Groot”，使用转义语法：例如’I”’m Groot’（或者如果可能的话使用双引号：”I’m Groot”）

4. 加载 .specify/templates/spec-template.md 以了解必需的部分。

5. 遵循此执行流程：

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

6. 使用模板结构将规范写入SPEC_FILE，用从功能描述（参数）派生的具体细节替换占位符，同时保持部分顺序和标题不变。

7. 规范质量验证：编写初始规范后，根据质量标准对其进行验证：

   a. 创建规范质量检查清单：使用检查清单模板结构在 FEATURE_DIR/checklists/requirements.md 生成一个检查清单文件，参考：assets/quality-checklist-template.md

   b. 运行验证检查：针对每个检查清单项目审查规范：

   • 对于每个项目，确定它是通过还是失败
   • 记录发现的具体问题（引用相关的规范部分）

   c. 处理验证结果：

   • 如果所有项目都通过：标记检查清单完成并进入步骤6

   • 如果有项目失败（不包括[需要澄清]）：

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

   • 如果存在[需要澄清]标记：

     1. 从规范中提取所有[需要澄清：…]标记

     2. 限制检查：如果存在超过3个标记，则只保留按范围/安全/用户体验影响最重要的3个，并对其余的做出有根据的猜测

     3. 对于每个需要澄清的问题（最多3个），参考assets/clarification-template.md向用户呈现选项。

     4. 关键 – 表格格式化：确保markdown表格正确格式化：

        • 使用一致的间距，管道对齐
        • 每个单元格应在内容周围留有空格：| 内容 | 而不是 |内容|
        • 表头分隔符必须至少有3个破折号：|--------|
        • 测试表格在markdown预览中是否正确渲染

     5. 按顺序编号问题（Q1、Q2、Q3 – 最多总共3个）

     6. 在等待响应之前一起呈现所有问题

     7. 等待用户响应他们对所有问题的选择（例如：”Q1: A, Q2: 自定义 – [详情], Q3: B”）

     8. 通过用用户的选定或提供的答案替换每个[需要澄清]标记来更新规范

     9. 在所有澄清解决后重新运行验证

   d. 更新检查清单：每次验证迭代后，使用当前通过/失败状态更新检查清单文件

8. 报告完成情况，包括分支名称、规范文件路径、检查清单结果以及下一阶段（speckit-clarify 或 speckit-plan）的准备情况。

注意：脚本会创建并检出新分支并在写入前初始化规范文件。

通用指南

快速指南

• 关注用户需要什么以及为什么
• 避免如何实现（无技术栈、API、代码结构）
• 为业务利益相关者而非开发人员编写
• 不要创建嵌入规范中的任何检查清单。那将是单独的命令

部分要求

• 必填部分：每个功能都必须完成
• 可选部分：仅当与功能相关时才包含
• 当某个部分不适用时，完全删除它（不要留下”N/A”）

对于AI生成

从用户提示创建此规范时：

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

合理默认值示例（不要询问这些）：

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

成功标准指南

成功标准必须：

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

良好示例：

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

不良示例（实现导向）：

• “API响应时间低于200毫秒”（过于技术性，应使用”用户立即看到结果”）

• “数据库可处理1000 TPS”（实现细节，应使用面向用户的指标）

• “React组件高效渲染”（框架特定）

• “Redis缓存命中率高于80%”（技术特定）