Back to Details

speckit-specify-zh

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

用户输入

User Input

text
$ARGUMENTS
在继续之前，您必须考虑用户输入（如果非空）。
text
$ARGUMENTS
Before proceeding, you must consider the user input (if non-empty).

大纲

Outline

触发消息中用户在触发词后键入的文本就是功能描述。假设在此对话中始终可以使用该功能描述，即 
$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
  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. 首先获取所有远程分支以确保拥有最新信息：
    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"）
  3. 加载 
    .specify/templates/spec-template.md
    以了解必需的部分。
  4. 遵循此执行流程：
    1. 解析来自输入的用户描述 如果为空：错误"未提供功能描述"
    2. 从描述中提取关键概念 识别：参与者、动作、数据、约束
    3. 对于不清楚的方面：
      • 基于上下文和行业标准做出有根据的猜测
      • 仅在以下情况下标记[需要澄清：具体问题]：
        • 选择显著影响功能范围或用户体验
        • 存在多种合理解释且有不同的含义
        • 不存在合理的默认值
      • 限制：最多总共3个[需要澄清]标记
      • 按影响优先排序：范围 > 安全/隐私 > 用户体验 > 技术细节
    4. 填写用户场景与测试部分 如果没有清晰的用户流程：错误"无法确定用户场景"
    5. 生成功能性需求 每个需求都必须是可测试的 对未指定的详细信息使用合理的默认值（在假设部分记录假设）
    6. 定义成功标准 创建可测量的、技术无关的结果 包括定量指标（时间、性能、数量）和定性措施（用户满意度、任务完成度） 每个标准必须在没有实现细节的情况下可验证
    7. 识别关键实体（如果涉及数据）
    8. 返回：成功（规范已准备好进行规划）
  5. 使用模板结构将规范写入SPEC_FILE，用从功能描述（参数）派生的具体细节替换占位符，同时保持部分顺序和标题不变。
  6. 规范质量验证：编写初始规范后，根据质量标准对其进行验证：
    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. 更新检查清单：每次验证迭代后，使用当前通过/失败状态更新检查清单文件
  7. 报告完成情况，包括分支名称、规范文件路径、检查清单结果以及下一阶段（
    speckit-clarify
    或 
    speckit-plan
    ）的准备情况。
注意：脚本会创建并检出新分支并在写入前初始化规范文件。
The text the user types after the trigger word in the trigger message is the feature description. Assume this feature description is always available in this conversation, i.e., 
$ARGUMENTS
. Do not ask the user to repeat unless they provided an empty command.
Based on this feature description, please perform the following actions:
  1. Copy all files (including subdirectories) from 
    assets/specify/
    to the 
    .specify
    directory under the repository root directory while preserving the original directory structure, skip existing files, do not overwrite existing files with the same name. The -n (--no-clobber) option of the cp command can prevent overwriting existing files. At this stage, your project folder content should be similar to the following:
text
Repository root directory
└── .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
  1. Generate a concise short name (2-4 words) for the branch:
    • Analyze the feature description and extract the most meaningful keywords
    • Create a 2-4 word short name that captures the essence of the feature
    • Use verb-noun format whenever possible (e.g., "add-user-auth", "fix-payment-bug")
    • Retain technical terms and abbreviations (OAuth2, API, JWT, etc.)
    • Keep it concise yet descriptive enough to understand the feature at a glance
    • Examples:
      • "I want to add user authentication" → "user-auth"
      • "Implement OAuth2 integration for API" → "oauth2-api-integration"
      • "Create analytics dashboard" → "analytics-dashboard"
      • "Fix payment processing timeout error" → "fix-payment-timeout"
  2. Check existing branches before creating a new branch:
    a. First fetch all remote branches to ensure you have the latest information:
    bash
    git fetch --all --prune
    b. Find the highest feature number with the short name across all sources:
    • Remote branches: 
      git ls-remote --heads origin | grep -E 'refs/heads/[0-9]+-<short-name>$'
    • Local branches: 
      git branch | grep -E '^[* ]*[0-9]+-<short-name>$'
    • Specification directories: Check directories matching 
      specs/[0-9]+-<short-name>
    c. Determine the next available number:
    • Extract all numbers from all three sources
    • Find the largest number N
    • Use N+1 for the new branch
    d. Run the script 
    create-new-feature.ps1 -Json "$ARGUMENTS"
    using the calculated number and short name:
    • Pass 
      --number N+1
      and 
      --short-name "your-short-name"
      along with the feature description
    • Bash example: 
      create-new-feature.sh -Json "$ARGUMENTS" --json --number 5 --short-name "user-auth" "Add user authentication"
    • PowerShell example: 
      create-new-feature.ps1 -Json "$ARGUMENTS" -Json -Number 5 -ShortName "user-auth" "Add user authentication"
    Important:
    • Check all three sources (remote branches, local branches, specification directories) to find the highest number
    • Only match branches/directories with the exact short name pattern
    • If no existing branches/directories with this short name are found, start from number 1
    • Run this script only once per feature
    • JSON is provided as output in the terminal - always refer to it for the actual content you are looking for
    • The JSON output will include BRANCH_NAME and SPEC_FILE path
    • For single quotes in arguments like "I'm Groot", use escape syntax: e.g., 'I'''m Groot' (or use double quotes if possible: "I'm Groot")
  3. Load 
    .specify/templates/spec-template.md
    to understand the required sections.
  4. Follow this execution flow:
    1. Parse the user description from the input If empty: Error "No feature description provided"
    2. Extract key concepts from the description Identify: Actors, Actions, Data, Constraints
    3. For unclear aspects:
      • Make educated guesses based on context and industry standards
      • Only mark [Needs clarification: specific question] if:
        • The choice significantly impacts feature scope or user experience
        • There are multiple reasonable interpretations with different implications
        • No reasonable default exists
      • Limit: Maximum 3 [Needs clarification] marks total
      • Prioritize by impact: Scope > Security/Privacy > User Experience > Technical Details
    4. Fill in the User Scenarios & Testing section If no clear user flow: Error "Unable to determine user scenarios"
    5. Generate functional requirements Each requirement must be testable Use reasonable defaults for unspecified details (document assumptions in the Assumptions section)
    6. Define success criteria Create measurable, technology-agnostic results Include quantitative metrics (time, performance, quantity) and qualitative measures (user satisfaction, task completion rate) Each criterion must be verifiable without implementation details
    7. Identify key entities (if data is involved)
    8. Return: Success (Specification is ready for planning)
  5. Write the specification to SPEC_FILE using the template structure, replacing placeholders with specific details derived from the feature description (arguments), while maintaining the section order and titles unchanged.
  6. Specification Quality Verification: After writing the initial specification, verify it against quality standards:
    a. Create Specification Quality Checklist: Generate a checklist file in 
    FEATURE_DIR/checklists/requirements.md
    using the checklist template structure, refer to: assets/quality-checklist-template.md
    b. Run Verification Checks: Review the specification against each checklist item:
    • For each item, determine if it passes or fails
    • Record specific issues found (reference relevant specification sections)
    c. Handle Verification Results:
    • If all items pass: Mark the checklist as complete and proceed to step 6
    • If any items fail (excluding [Needs clarification]):
      1. List the failed items and specific issues
      2. Update the specification to address each issue
      3. Re-run verification until all items pass (maximum 3 iterations)
      4. If still failing after 3 iterations, record remaining issues in the checklist comments and issue a warning to the user
    • If [Needs clarification] marks exist:
      1. Extract all [Needs clarification: ...] marks from the specification
      2. Limit Check: If there are more than 3 marks, only keep the top 3 most important ones by scope/security/user experience impact, and make educated guesses for the rest
      3. For each clarification needed (maximum 3), present options to the user by referring to assets/clarification-template.md
      4. Critical - Table Formatting: Ensure markdown tables are correctly formatted:
        • Use consistent spacing, aligned pipes
        • Each cell should have spaces around content: 
          | Content |
          instead of 
          |Content|
        • Header separators must have at least 3 dashes: 
          |--------|
        • Test that tables render correctly in markdown preview
      5. Number the questions in order (Q1, Q2, Q3 - maximum 3 total)
      6. Present all questions together before waiting for a response
      7. Wait for the user's response with their choices for all questions (e.g., "Q1: A, Q2: Custom - [Details], Q3: B")
      8. Update the specification by replacing each [Needs clarification] mark with the user's selected or provided answer
      9. Re-run verification after all clarifications are resolved
    d. Update Checklist: After each verification iteration, update the checklist file with the current pass/fail status
  7. Report completion status, including branch name, specification file path, checklist results, and readiness for the next phase (
    speckit-clarify
    or 
    speckit-plan
    ).
Note: The script creates and checks out the new branch and initializes the specification file before writing.

通用指南

General Guidelines

快速指南

Quick Guide

  • 关注用户需要什么以及为什么
  • 避免如何实现（无技术栈、API、代码结构）
  • 为业务利益相关者而非开发人员编写
  • 不要创建嵌入规范中的任何检查清单。那将是单独的命令
  • Focus on what the user needs and why
  • Avoid how to implement (no tech stack, APIs, code structure)
  • Write for business stakeholders, not developers
  • Do not create any checklists embedded in the specification. That will be a separate command

部分要求

Section Requirements

  • 必填部分：每个功能都必须完成
  • 可选部分：仅当与功能相关时才包含
  • 当某个部分不适用时，完全删除它（不要留下"N/A"）
  • Required Sections: Must be completed for every feature
  • Optional Sections: Include only if relevant to the feature
  • When a section is not applicable, delete it entirely (do not leave "N/A")

对于AI生成

For AI Generation

从用户提示创建此规范时：
  1. 做出有根据的猜测：使用上下文、行业标准和常见模式填补空白
  2. 记录假设：在假设部分记录合理的默认值
  3. 限制澄清：最多3个[需要澄清]标记 - 仅用于那些：
    • 显著影响功能范围或用户体验的关键决策
    • 具有多种合理解释且不同含义的情况
    • 缺乏任何合理默认值的情况
  4. 优先考虑澄清：范围 > 安全/隐私 > 用户体验 > 技术细节
  5. 像测试人员一样思考：每个模糊的需求都应该未能通过"可测试且明确"的检查清单项
  6. 常见的需要澄清区域（只有在没有合理默认值时）：
    • 功能范围和边界（包括/排除特定用例）
    • 用户类型和权限（如果存在多个冲突的解释可能性）
    • 安全/合规要求（当法律/财务上重要时）
合理默认值示例（不要询问这些）：
  • 数据保留：领域内的行业标准实践
  • 性能目标：标准网页/移动应用期望，除非另有规定
  • 错误处理：用户友好的消息和适当的回退
  • 认证方法：标准基于会话或OAuth2的Web应用程序
  • 集成模式：RESTful API，除非另有说明
When creating this specification from a user prompt:
  1. Make educated guesses: Fill gaps using context, industry standards, and common patterns
  2. Document assumptions: Record reasonable defaults in the Assumptions section
  3. Limit clarifications: Maximum 3 [Needs clarification] marks - only for those:
    • Critical decisions that significantly impact feature scope or user experience
    • Situations with multiple reasonable interpretations with different implications
    • Cases where no reasonable default exists
  4. Prioritize clarifications: Scope > Security/Privacy > User Experience > Technical Details
  5. Think like a tester: Every ambiguous requirement should fail the "testable and clear" checklist item
  6. Common areas needing clarification (only if no reasonable default exists):
    • Feature scope and boundaries (including/excluding specific use cases)
    • User types and permissions (if multiple conflicting interpretations are possible)
    • Security/compliance requirements (when legally/financially important)
Examples of reasonable defaults (do not ask about these):
  • Data retention: Industry standard practices in the domain
  • Performance targets: Standard web/mobile application expectations, unless specified otherwise
  • Error handling: User-friendly messages and appropriate fallbacks
  • Authentication methods: Standard session-based or OAuth2-based web applications
  • Integration patterns: RESTful API, unless stated otherwise

成功标准指南

Success Criteria Guidelines

成功标准必须：
  1. 可衡量：包括具体指标（时间、百分比、计数、比率）
  2. 技术无关：不提及框架、语言、数据库或工具
  3. 以用户为中心：从用户/业务角度描述结果，而不是系统内部机制
  4. 可验证：无需知道实现细节即可测试/验证
良好示例：
  • "用户可在3分钟内完成结账"
  • "系统支持10,000个并发用户"
  • "95%的搜索在1秒内返回结果"
  • "任务完成率提高40%"
不良示例（实现导向）：
  • "API响应时间低于200毫秒"（过于技术性，应使用"用户立即看到结果"）
  • "数据库可处理1000 TPS"（实现细节，应使用面向用户的指标）
  • "React组件高效渲染"（框架特定）
  • "Redis缓存命中率高于80%"（技术特定）
Success criteria must:
  1. Measurable: Include specific metrics (time, percentage, count, ratio)
  2. Technology-agnostic: Do not mention frameworks, languages, databases, or tools
  3. User-centric: Describe results from the user/business perspective, not internal system mechanisms
  4. Verifiable: Testable/verifiable without knowing implementation details
Good Examples:
  • "Users can complete checkout within 3 minutes"
  • "System supports 10,000 concurrent users"
  • "95% of searches return results within 1 second"
  • "Task completion rate increases by 40%"
Bad Examples (implementation-oriented):
  • "API response time is less than 200ms" (too technical, should use "Users see results instantly")
  • "Database can handle 1000 TPS" (implementation detail, should use user-centric metrics)
  • "React components render efficiently" (framework-specific)
  • "Redis cache hit rate is higher than 80%" (technology-specific)