---
name: speckit-specify-zh
description: 中文功能规范创建工具，用于将自然语言功能描述转换为结构化的功能规范文档。支持自动生成分支名称、创建Git分支、初始化规范文件和质量验证。触发词包括："speckit规范"、"功能规范"、"创建规范"、"功能描述转换"、"speckit-specify"。当用户需要将功能想法转换为结构化规范时使用此技能。
---

## 用户输入

```text
$ARGUMENTS
```

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

## 大纲

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

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

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

```text
仓库根目录
└── .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. 首先获取所有远程分支以确保拥有最新信息：

      ```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. 使用计算出的编号和短名称运行脚本 `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](assets/quality-checklist-template.md)


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

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

   c. **处理验证结果**：

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

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

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

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

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

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

        3. 对于每个需要澄清的问题（最多3个），参考[assets/clarification-template.md](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%"（技术特定）