speckit-specify

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

speckit-specify

本技能内容源自 GitHub Spec Kit 官方提示词模板。

上游：https://github.com/github/spec-kit
许可：MIT License, Copyright GitHub, Inc.（完整文本见同目录
```
LICENSE.txt
```
）
适配说明：官方模板面向斜杠命令场景；原文中的
```
$ARGUMENTS
```
指用户在对话中给出的请求，跨命令引用（如
```
speckit.plan
```
）在本技能体系中对应同名的
```
speckit-*
```
技能。其余内容保持与上游一致，未作改写。

本技能内容源自 GitHub Spec Kit 官方提示词模板。

上游：https://github.com/github/spec-kit
许可：MIT License, Copyright GitHub, Inc.（完整文本见同目录
```
LICENSE.txt
```
）
适配说明：官方模板面向斜杠命令场景；原文中的
```
$ARGUMENTS
```
指用户在对话中给出的请求，跨命令引用（如
```
speckit.plan
```
）在本技能体系中对应同名的
```
speckit-*
```
技能。其余内容保持与上游一致，未作改写。

User Input

用户输入

text

$ARGUMENTS

You MUST consider the user input before proceeding (if not empty).

text

$ARGUMENTS

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

Pre-Execution Checks

执行前检查

Check for extension hooks (before specification):

Check if
```
.specify/extensions.yml
```
exists in the project root.
If it exists, read it and look for entries under the
```
hooks.before_specify
```
key
If the YAML cannot be parsed or is invalid, do not skip silently: tell the user that
```
.specify/extensions.yml
```
could not be read (include the parser error) and that no hooks were checked, including any mandatory (
```
optional: false
```
) hooks registered there, then continue normally
Filter out hooks where
```
enabled
```
is explicitly
```
false
```
. Treat hooks without an
```
enabled
```
field as enabled by default.
For each remaining hook, do not attempt to interpret or evaluate hook
```
condition
```
expressions:
- If the hook has no
```
condition
```
  field, or it is null/empty, treat the hook as executable
- If the hook defines a non-empty
```
condition
```
  , skip the hook and leave condition evaluation to the HookExecutor implementation
For each executable hook, output the following based on its
```
optional
```
flag:
- Optional hook (
```
optional: true
```
  ):
```
## Extension Hooks

**Optional Pre-Hook**: {extension}
Command: `/{command}`
Description: {description}

Prompt: {prompt}
To execute: `/{command}`
```
- Mandatory hook (
```
optional: false
```
  ):
```
## Extension Hooks

**Automatic Pre-Hook**: {extension}
Executing: `/{command}`
EXECUTE_COMMAND: {command}

Wait for the result of the hook command before proceeding to the Outline.
```
  After emitting the block above you MUST actually invoke the hook and wait for it to finish before continuing. Run it the same way you would run the command yourself in this agent/session (the invocation may differ from the literal
```
{command}
```
  id shown above, e.g. a skills-mode agent runs it as
```
/skill:speckit-...
```
  or
```
$speckit-...
```
  ). Emitting the block alone does not run the hook.
If no hooks are registered or
```
.specify/extensions.yml
```
does not exist, skip silently

检查扩展 Hook（在创建规格之前）：

检查项目根目录中是否存在
```
.specify/extensions.yml
```
。
如果存在，则读取该文件并查找
```
hooks.before_specify
```
键下的条目。
如果 YAML 无法解析或内容无效，不要静默跳过：告知用户
```
.specify/extensions.yml
```
无法读取（包含解析器错误），且未检查任何 Hook（包括其中注册的任何强制 Hook（
```
optional: false
```
）），然后继续正常流程。
过滤掉明确设置为
```
enabled: false
```
的 Hook。未设置
```
enabled
```
字段的 Hook 默认视为已启用。
对于每个剩余 Hook，不要尝试解释或求值 Hook 的
```
condition
```
表达式：
- 如果 Hook 没有
```
condition
```
  字段，或该字段为 null/空，则视为可执行。
- 如果 Hook 定义了非空的
```
condition
```
  ，则跳过该 Hook，并将条件求值留给 HookExecutor 实现处理。

对于每个可执行 Hook，根据其

optional

标志输出以下内容：

可选 Hook（

optional: true

）：

## Extension Hooks

**Optional Pre-Hook**: {extension}
Command: `/{command}`
Description: {description}

Prompt: {prompt}
To execute: `/{command}`

强制 Hook（
```
optional: false
```
）：
```
## Extension Hooks

**Automatic Pre-Hook**: {extension}
Executing: `/{command}`
EXECUTE_COMMAND: {command}

Wait for the result of the hook command before proceeding to the Outline.
```
输出上述区块后，您必须实际调用该 Hook 并等待其完成，然后才能继续。调用方式应与您在此
```
agent/session
```
中自行运行命令的方式相同（实际调用形式可能不同于字面量
```
{command}
```
ID，例如 skills-mode
```
agent
```
会将其运行为
```
/skill:speckit-...
```
或
```
$speckit-...
```
）。仅输出该区块并不会运行 Hook。

如果没有注册 Hook，或
```
.specify/extensions.yml
```
不存在，则静默跳过。

Outline

大纲

The text the user typed after

__SPECKIT_COMMAND_SPECIFY__

in the triggering message is the feature description. Assume you always have it available in this conversation even if

{ARGS}

appears literally below. Do not ask the user to repeat it unless they provided an empty command.

Given that feature description, do this:

Generate a concise short name (2-4 words) for the feature:
- 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 action-noun format when possible (e.g., "add-user-auth", "fix-payment-bug")
- Preserve technical terms and acronyms (OAuth2, API, JWT, etc.)
- Keep it concise but descriptive enough to understand the feature at a glance
- Examples:
  - "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"
Branch creation (optional, via hook):
If a
```
before_specify
```
hook ran successfully in the Pre-Execution Checks above, it will have created/switched to a git branch and output JSON containing
```
BRANCH_NAME
```
and
```
FEATURE_NUM
```
. Note these values for reference, but the branch name does not dictate the spec directory name.
If the user explicitly provided
```
GIT_BRANCH_NAME
```
, pass it through to the hook so the branch script uses the exact value as the branch name (bypassing all prefix/suffix generation).
Create the spec feature directory:
Specs live under the default
```
specs/
```
directory unless the user explicitly provides
```
SPECIFY_FEATURE_DIRECTORY
```
.
Resolution order for
SPECIFY_FEATURE_DIRECTORY
:
1. If the user explicitly provided
```
SPECIFY_FEATURE_DIRECTORY
```
  (e.g., via environment variable, argument, or configuration), use it as-is
2. Otherwise, auto-generate it under
```
specs/
```
  :
  - Check
```
.specify/init-options.json
```
    for
```
feature_numbering
```
    (preferred) or
```
branch_numbering
```
    (deprecated, migration only — will be removed in a future release)
  - If
```
"timestamp"
```
    : prefix is
```
YYYYMMDD-HHMMSS
```
    (current timestamp)
  - If
```
"sequential"
```
    or absent: prefix is
```
NNN
```
    (next available 3-digit number after scanning existing directories in
```
specs/
```
    )
  - Construct the directory name:
```
<prefix>-<short-name>
```
    (e.g.,
```
003-user-auth
```
    or
```
20260319-143022-user-auth
```
    )
  - Set
```
SPECIFY_FEATURE_DIRECTORY
```
    to
```
specs/<directory-name>
```
  - If
```
branch_numbering
```
    was used (and
```
feature_numbering
```
    was absent), emit a one-line warning: "⚠️
```
branch_numbering
```
    in init-options.json is deprecated. Rename to
```
feature_numbering
```
    ."
Create the directory and spec file:
- ```
mkdir -p SPECIFY_FEATURE_DIRECTORY
```
- Resolve the active
```
spec-template
```
  through the Spec Kit preset/template resolution stack (equivalent to
```
specify preset resolve spec-template
```
  )
- Copy the resolved
```
spec-template
```
  file to
```
SPECIFY_FEATURE_DIRECTORY/spec.md
```
  as the starting point
- Set
```
SPEC_FILE
```
  to
```
SPECIFY_FEATURE_DIRECTORY/spec.md
```
- Persist the resolved path to
```
.specify/feature.json
```
  :
  json
```
{
  "feature_directory": "<resolved feature dir>"
}
```
  Write the actual resolved directory path value (for example,
```
specs/003-user-auth
```
  ), not the literal string
```
SPECIFY_FEATURE_DIRECTORY
```
  . This allows downstream commands (
```
__SPECKIT_COMMAND_PLAN__
```
  ,
```
__SPECKIT_COMMAND_TASKS__
```
  , etc.) to locate the feature directory without relying on git branch name conventions.
IMPORTANT:
- You must only create one feature per
```
__SPECKIT_COMMAND_SPECIFY__
```
  invocation
- The spec directory name and the git branch name are independent — they may be the same but that is the user's choice
- The spec directory and file are always created by this command, never by the hook
Load the resolved active
```
spec-template
```
file to understand required sections.
IF EXISTS: Load
```
/memory/constitution.md
```
for project principles and governance constraints.
Follow this execution flow:
1. Parse user description from arguments If empty: ERROR "No feature description provided"
2. Extract key concepts from description Identify: actors, actions, data, constraints
3. For unclear aspects:
  - Make informed guesses based on context and industry standards
  - Only mark with [NEEDS CLARIFICATION: specific question] if:
    - The choice significantly impacts feature scope or user experience
    - Multiple reasonable interpretations exist with different implications
    - No reasonable default exists
  - LIMIT: Maximum 3 [NEEDS CLARIFICATION] markers total
  - Prioritize clarifications by impact: scope > security/privacy > user experience > technical details
4. Fill User Scenarios & Testing section If no clear user flow: ERROR "Cannot determine user scenarios"
5. Generate Functional Requirements Each requirement must be testable Use reasonable defaults for unspecified details (document assumptions in Assumptions section)
6. Define Success Criteria Create measurable, technology-agnostic outcomes Include both quantitative metrics (time, performance, volume) and qualitative measures (user satisfaction, task completion) Each criterion must be verifiable without implementation details
7. Identify Key Entities (if data involved)
8. Return: SUCCESS (spec ready for planning)
Write the specification to SPEC_FILE using the template structure, replacing placeholders with concrete details derived from the feature description (arguments) while preserving section order and headings.

Specification Quality Validation: After writing the initial spec, validate it against quality criteria:

a. Create Spec Quality Checklist: Generate a checklist file at

SPECIFY_FEATURE_DIRECTORY/checklists/requirements.md

using the checklist template structure with these validation items:

markdown

# Specification Quality Checklist: [FEATURE NAME]

**Purpose**: Validate specification completeness and quality before proceeding to planning
**Created**: [DATE]
**Feature**: [Link to spec.md]

## Content Quality

- [ ] No implementation details (languages, frameworks, APIs)
- [ ] Focused on user value and business needs
- [ ] Written for non-technical stakeholders
- [ ] All mandatory sections completed

## Requirement Completeness

- [ ] No [NEEDS CLARIFICATION] markers remain
- [ ] Requirements are testable and unambiguous
- [ ] Success criteria are measurable
- [ ] Success criteria are technology-agnostic (no implementation details)
- [ ] All acceptance scenarios are defined
- [ ] Edge cases are identified
- [ ] Scope is clearly bounded
- [ ] Dependencies and assumptions identified

## Feature Readiness

- [ ] All functional requirements have clear acceptance criteria
- [ ] User scenarios cover primary flows
- [ ] Feature meets measurable outcomes defined in Success Criteria
- [ ] No implementation details leak into specification

## Notes

- Items marked incomplete require spec updates before `__SPECKIT_COMMAND_CLARIFY__` or `__SPECKIT_COMMAND_PLAN__`

b. Run Validation Check: Review the spec against each checklist item:

For each item, determine if it passes or fails
Document specific issues found (quote relevant spec sections)

c. Handle Validation Results:

If all items pass: Mark checklist complete and proceed to the Mandatory Post-Execution Hooks section
If items fail (excluding [NEEDS CLARIFICATION]):
1. List the failing items and specific issues
2. Update the spec to address each issue
3. Re-run validation until all items pass (max 3 iterations)
4. If still failing after 3 iterations, document remaining issues in checklist notes and warn user
If [NEEDS CLARIFICATION] markers remain:
1. Extract all [NEEDS CLARIFICATION: ...] markers from the spec
2. LIMIT CHECK: If more than 3 markers exist, keep only the 3 most critical (by scope/security/UX impact) and make informed guesses for the rest
3. For each clarification needed (max 3), present options to user in this format:
  markdown
```
## Question [N]: [Topic]

**Context**: [Quote relevant spec section]

**What we need to know**: [Specific question from NEEDS CLARIFICATION marker]

**Suggested Answers**:

| Option | Answer | Implications |
|--------|--------|--------------|
| A      | [First suggested answer] | [What this means for the feature] |
| B      | [Second suggested answer] | [What this means for the feature] |
| C      | [Third suggested answer] | [What this means for the feature] |
| Custom | Provide your own answer | [Explain how to provide custom input] |

**Your choice**: _[Wait for user response]_
```
4. CRITICAL - Table Formatting: Ensure markdown tables are properly formatted:
  - Use consistent spacing with pipes aligned
  - Each cell should have spaces around content:
```
| Content |
```
    not
```
|Content|
```
  - Header separator must have at least 3 dashes:
```
|--------|
```
  - Test that the table renders correctly in markdown preview
5. Number questions sequentially (Q1, Q2, Q3 - max 3 total)
6. Present all questions together before waiting for responses
7. Wait for user to respond with their choices for all questions (e.g., "Q1: A, Q2: Custom - [details], Q3: B")
8. Update the spec by replacing each [NEEDS CLARIFICATION] marker with the user's selected or provided answer
9. Re-run validation after all clarifications are resolved

d. Update Checklist: After each validation iteration, update the checklist file with current pass/fail status

触发消息中

__SPECKIT_COMMAND_SPECIFY__

之后用户输入的文本就是功能描述。即使下方

{ARGS}

字面显示，也应始终假定本对话中已有该功能描述。除非用户提供的是空命令，否则不要要求用户重复输入。

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

生成简洁的短名称（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”
创建分支（可选，通过 Hook）：
如果上述执行前检查中的
```
before_specify
```
Hook 已成功运行，它将创建或切换到一个 Git 分支，并输出包含
```
BRANCH_NAME
```
和
```
FEATURE_NUM
```
的 JSON。请记录这些值供参考，但分支名称不决定规格目录名称。
如果用户明确提供了
```
GIT_BRANCH_NAME
```
，请将其直接传递给 Hook，使分支脚本使用该确切值作为分支名（绕过所有前缀和后缀生成逻辑）。
创建规格功能目录：
除非用户明确提供
```
SPECIFY_FEATURE_DIRECTORY
```
，否则规格默认存放在
```
specs/
```
目录下。
SPECIFY_FEATURE_DIRECTORY
的解析顺序：
1. 如果用户明确提供了
```
SPECIFY_FEATURE_DIRECTORY
```
  （例如通过环境变量、参数或配置），则按原值使用。
2. 否则，在
```
specs/
```
  下自动生成：
  - 检查
```
.specify/init-options.json
```
    中的
```
feature_numbering
```
    （首选）或
```
branch_numbering
```
    （已弃用，仅用于迁移；未来版本将移除）。
  - 如果值为
```
"timestamp"
```
    ：前缀为
```
YYYYMMDD-HHMMSS
```
    （当前时间戳）。
  - 如果值为
```
"sequential"
```
    或不存在：前缀为
```
NNN
```
    （扫描
```
specs/
```
    中现有目录后取下一个可用的 3 位编号）。
  - 构造目录名：
```
<prefix>-<short-name>
```
    （例如
```
003-user-auth
```
    或
```
20260319-143022-user-auth
```
    ）。
  - 将
```
SPECIFY_FEATURE_DIRECTORY
```
    设置为
```
specs/<directory-name>
```
    。
  - 如果使用了
```
branch_numbering
```
    （且不存在
```
feature_numbering
```
    ），则输出一行警告：⚠️
```
init-options.json
```
    中的
```
branch_numbering
```
    已弃用，请重命名为
```
feature_numbering
```
    。
创建目录和规格文件：
- ```
mkdir -p SPECIFY_FEATURE_DIRECTORY
```
- 通过 Spec Kit 预设/模板解析栈解析当前生效的
```
spec-template
```
  （等价于
```
specify preset resolve spec-template
```
  ）。
- 将解析后的
```
spec-template
```
  文件复制到
```
SPECIFY_FEATURE_DIRECTORY/spec.md
```
  ，作为起始文件。
- 将
```
SPEC_FILE
```
  设置为
```
SPECIFY_FEATURE_DIRECTORY/spec.md
```
  。
- 将解析后的路径持久化到
```
.specify/feature.json
```
  ：
  json
```
{
  "feature_directory": "<resolved feature dir>"
}
```
  写入实际解析出的目录路径值（例如
```
specs/003-user-auth
```
  ），而不是字面量
```
SPECIFY_FEATURE_DIRECTORY
```
  。这样，下游命令（
```
__SPECKIT_COMMAND_PLAN__
```
  、
```
__SPECKIT_COMMAND_TASKS__
```
  等）无需依赖 Git 分支命名约定即可定位功能目录。
重要：
- 每次调用
```
__SPECKIT_COMMAND_SPECIFY__
```
  只能创建一个功能。
- 规格目录名和 Git 分支名彼此独立——二者可以相同，但这由用户决定。
- 规格目录和文件始终由此核心命令创建，绝不由 Hook 创建。
加载解析后当前生效的
```
spec-template
```
文件，以了解所需章节。
如果存在：加载
```
/memory/constitution.md
```
，以获取项目原则和治理约束。
遵循此执行流程：
1. 从参数中解析用户描述。如果为空：ERROR
```
No feature description provided
```
2. 从描述中提取关键概念。识别：参与者、操作、数据、约束。
3. 对于不明确之处：
  - 根据上下文和行业标准作出合理推断。
  - 仅在以下情况下使用
```
[NEEDS CLARIFICATION: specific question]
```
    标记：
    - 该选择会显著影响功能范围或用户体验。
    - 存在多种合理解释，且不同解释会产生不同影响。
    - 不存在合理的默认值。
  - 限制：
    [NEEDS CLARIFICATION]
    标记总数最多为 3 个。
  - 按影响程度确定澄清优先级：范围 > 安全/隐私 > 用户体验 > 技术细节。
4. 填写“用户场景与测试”章节。如果没有清晰的用户流程：ERROR
```
Cannot determine user scenarios
```
5. 生成功能需求。每项需求都必须可测试。对于未指定的细节采用合理默认值（在“假设”章节中记录假设）。
6. 定义成功标准。创建可衡量且与技术无关的结果。同时包括定量指标（时间、性能、容量）和定性衡量（用户满意度、任务完成情况）。每项标准都必须无需了解实现细节即可验证。
7. 识别关键实体（如果涉及数据）。
8. 返回：
```
SUCCESS (spec ready for planning)
```
  （规格已可进入规划阶段）。
使用模板结构将规格写入
```
SPEC_FILE
```
，用根据功能描述（参数）得出的具体内容替换占位符，同时保留章节顺序和标题。

规格质量验证：写入初始规格后，根据质量标准对其进行验证：

a. 创建规格质量检查清单：使用检查清单模板结构，在

SPECIFY_FEATURE_DIRECTORY/checklists/requirements.md

生成检查清单文件，并包含以下验证项：

markdown

# Specification Quality Checklist: [FEATURE NAME]

**Purpose**: Validate specification completeness and quality before proceeding to planning
**Created**: [DATE]
**Feature**: [Link to spec.md]

## Content Quality

- [ ] No implementation details (languages, frameworks, APIs)
- [ ] Focused on user value and business needs
- [ ] Written for non-technical stakeholders
- [ ] All mandatory sections completed

## Requirement Completeness

- [ ] No [NEEDS CLARIFICATION] markers remain
- [ ] Requirements are testable and unambiguous
- [ ] Success criteria are measurable
- [ ] Success criteria are technology-agnostic (no implementation details)
- [ ] All acceptance scenarios are defined
- [ ] Edge cases are identified
- [ ] Scope is clearly bounded
- [ ] Dependencies and assumptions identified

## Feature Readiness

- [ ] All functional requirements have clear acceptance criteria
- [ ] User scenarios cover primary flows
- [ ] Feature meets measurable outcomes defined in Success Criteria
- [ ] No implementation details leak into specification

## Notes

- Items marked incomplete require spec updates before `__SPECKIT_COMMAND_CLARIFY__` or `__SPECKIT_COMMAND_PLAN__`

b. 运行验证检查：根据每项检查清单条目审查规格：

对每项内容判断通过或失败。
记录发现的具体问题（引用相关规格章节）。

c. 处理验证结果：

如果所有条目均通过：将检查清单标记为已完成，并继续执行“强制执行后置 Hook”部分。
如果条目失败（不包括
[NEEDS CLARIFICATION]
）：
1. 列出失败条目及具体问题。
2. 更新规格以解决每个问题。
3. 重新运行验证，直至所有条目均通过（最多 3 次迭代）。
4. 如果 3 次迭代后仍有失败，将剩余问题记录在检查清单备注中并警告用户。
如果仍有
[NEEDS CLARIFICATION]
标记：
1. 从规格中提取所有
```
[NEEDS CLARIFICATION: ...]
```
  标记。
2. 限制检查：如果标记超过 3 个，仅保留其中最关键的 3 个（按范围、安全性和用户体验影响排序），其余内容作出合理推断。
3. 对于每个需要澄清的问题（最多 3 个），使用以下格式向用户提供选项：
  markdown
```
## Question [N]: [Topic]

**Context**: [Quote relevant spec section]

**What we need to know**: [Specific question from NEEDS CLARIFICATION marker]

**Suggested Answers**:

| Option | Answer | Implications |
|--------|--------|--------------|
| A      | [First suggested answer] | [What this means for the feature] |
| B      | [Second suggested answer] | [What this means for the feature] |
| C      | [Third suggested answer] | [What this means for the feature] |
| Custom | Provide your own answer | [Explain how to provide custom input] |

**Your choice**: _[Wait for user response]_
```
4. 关键要求——表格格式：确保 Markdown 表格格式正确：
  - 使用间距一致的竖线并保持列对齐。
  - 每个单元格的内容前后都应有空格，例如
```
| Content |
```
    ，而不是
```
|Content|
```
    。
  - 表头分隔行必须至少包含 3 个短横线，例如
```
|--------|
```
    。
  - 测试表格是否能在 Markdown 预览中正确呈现。
5. 按顺序对问题编号（Q1、Q2、Q3，总数最多为 3 个）。
6. 在等待用户回复前，一次性展示所有问题。
7. 等待用户回复所有问题的选择（例如
```
Q1: A, Q2: Custom - [details], Q3: B
```
  ）。
8. 使用用户选择或提供的答案替换规格中的每个
```
[NEEDS CLARIFICATION]
```
  标记。
9. 所有澄清问题解决后，重新运行验证。

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

Mandatory Post-Execution Hooks

强制执行后置 Hook

You MUST complete this section before reporting completion to the user.

Check if

.specify/extensions.yml

exists in the project root.

If it does not exist, or no hooks are registered under
```
hooks.after_specify
```
, skip to the Completion Report.
If it exists, read it and look for entries under the
```
hooks.after_specify
```
key.
If the YAML cannot be parsed or is invalid, do not skip silently: tell the user that
```
.specify/extensions.yml
```
could not be read (include the parser error) and that no hooks were checked, including any mandatory (
```
optional: false
```
) hooks registered there, then continue to the Completion Report.
Filter out hooks where
```
enabled
```
is explicitly
```
false
```
. Treat hooks without an
```
enabled
```
field as enabled by default.
For each remaining hook, do not attempt to interpret or evaluate hook
```
condition
```
expressions:
- If the hook has no
```
condition
```
  field, or it is null/empty, treat the hook as executable
- If the hook defines a non-empty
```
condition
```
  , skip the hook and leave condition evaluation to the HookExecutor implementation
For each executable hook, output the following based on its
```
optional
```
flag:
- Mandatory hook (
```
optional: false
```
  ) — You MUST emit
  EXECUTE_COMMAND:
  for each mandatory hook:
```
## Extension Hooks

**Automatic Hook**: {extension}
Executing: `/{command}`
EXECUTE_COMMAND: {command}
```
  After emitting the block above you MUST actually invoke the hook and wait for it to finish before continuing. Run it the same way you would run the command yourself in this agent/session (the invocation may differ from the literal
```
{command}
```
  id shown above, e.g. a skills-mode agent runs it as
```
/skill:speckit-...
```
  or
```
$speckit-...
```
  ). Emitting the block alone does not run the hook.
- Optional hook (
```
optional: true
```
  ):
```
## Extension Hooks

**Optional Hook**: {extension}
Command: `/{command}`
Description: {description}

Prompt: {prompt}
To execute: `/{command}`
```

您必须在向用户报告完成之前完成本节。

检查项目根目录中是否存在

.specify/extensions.yml

。

如果不存在，或
```
hooks.after_specify
```
下没有注册 Hook，则跳至“完成报告”。
如果存在，则读取该文件并查找
```
hooks.after_specify
```
键下的条目。
如果 YAML 无法解析或内容无效，不要静默跳过：告知用户
```
.specify/extensions.yml
```
无法读取（包含解析器错误），且未检查任何 Hook（包括其中注册的任何强制 Hook（
```
optional: false
```
）），然后继续执行“完成报告”。
过滤掉明确设置为
```
enabled: false
```
的 Hook。未设置
```
enabled
```
字段的 Hook 默认视为已启用。
对于每个剩余 Hook，不要尝试解释或求值 Hook 的
```
condition
```
表达式：
- 如果 Hook 没有
```
condition
```
  字段，或该字段为 null/空，则视为可执行。
- 如果 Hook 定义了非空的
```
condition
```
  ，则跳过该 Hook，并将条件求值留给 HookExecutor 实现处理。
对于每个可执行 Hook，根据其
```
optional
```
标志输出以下内容：
- 强制 Hook（
```
optional: false
```
  ）——必须为每个强制 Hook 输出
  EXECUTE_COMMAND:
  ：
```
## Extension Hooks

**Automatic Hook**: {extension}
Executing: `/{command}`
EXECUTE_COMMAND: {command}
```
  输出上述区块后，您必须实际调用该 Hook 并等待其完成，然后才能继续。调用方式应与您在此
```
agent/session
```
  中自行运行命令的方式相同（实际调用形式可能不同于字面量
```
{command}
```
  ID，例如 skills-mode
```
agent
```
  会将其运行为
```
/skill:speckit-...
```
  或
```
$speckit-...
```
  ）。仅输出该区块并不会运行 Hook。
- 可选 Hook（
```
optional: true
```
  ）：
```
## Extension Hooks

**Optional Hook**: {extension}
Command: `/{command}`
Description: {description}

Prompt: {prompt}
To execute: `/{command}`
```

Completion Report

完成报告

Report completion to the user with:

```
SPECIFY_FEATURE_DIRECTORY
```
— the feature directory path
```
SPEC_FILE
```
— the spec file path
Checklist results summary

Readiness for the next phase (

__SPECKIT_COMMAND_CLARIFY__

__SPECKIT_COMMAND_PLAN__

)

NOTE: Branch creation is handled by the

before_specify

hook (git extension). Spec directory and file creation are always handled by this core command.

向用户报告以下内容：

```
SPECIFY_FEATURE_DIRECTORY
```
——功能目录路径。
```
SPEC_FILE
```
——规格文件路径。
检查清单结果摘要。

下一阶段的准备状态（

__SPECKIT_COMMAND_CLARIFY__

或

__SPECKIT_COMMAND_PLAN__

）。

**注意：**分支创建由

before_specify

Hook（git 扩展）处理。规格目录和文件始终由此核心命令处理。

Quick Guidelines

快速指南

Focus on WHAT users need and WHY.
Avoid HOW to implement (no tech stack, APIs, code structure).
Written for business stakeholders, not developers.
DO NOT create any checklists that are embedded in the spec. That will be a separate command.

关注用户需要什么（WHAT）以及为什么需要（WHY）。
避免关注如何实现（不涉及技术栈、API、代码结构）。
面向业务利益相关者而非开发者编写。
不要在规格中嵌入任何检查清单；这将由单独命令处理。

Section Requirements

章节要求

Mandatory sections: Must be completed for every feature
Optional sections: Include only when relevant to the feature
When a section doesn't apply, remove it entirely (don't leave as "N/A")

必需章节：每个功能都必须完成。
可选章节：仅在功能相关时包含。
如果某个章节不适用，应将其完全删除（不要保留为“不适用”）。

For AI Generation

用于 AI 生成

When creating this spec from a user prompt:

Make informed guesses: Use context, industry standards, and common patterns to fill gaps
Document assumptions: Record reasonable defaults in the Assumptions section
Limit clarifications: Maximum 3 [NEEDS CLARIFICATION] markers - use only for critical decisions that:
- Significantly impact feature scope or user experience
- Have multiple reasonable interpretations with different implications
- Lack any reasonable default
Prioritize clarifications: scope > security/privacy > user experience > technical details
Think like a tester: Every vague requirement should fail the "testable and unambiguous" checklist item
Common areas needing clarification (only if no reasonable default exists):
- Feature scope and boundaries (include/exclude specific use cases)
- User types and permissions (if multiple conflicting interpretations possible)
- Security/compliance requirements (when legally/financially significant)

Examples of reasonable defaults (don't ask about these):

Data retention: Industry-standard practices for the domain
Performance targets: Standard web/mobile app expectations unless specified
Error handling: User-friendly messages with appropriate fallbacks
Authentication method: Standard session-based or OAuth2 for web apps
Integration patterns: Use project-appropriate patterns (REST/GraphQL for web services, function calls for libraries, CLI args for tools, etc.)

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

作出合理推断：使用上下文、行业标准和常见模式填补信息缺口。
记录假设：在“假设”章节中记录合理的默认值。
限制澄清：最多使用 3 个
```
[NEEDS CLARIFICATION]
```
标记，仅用于以下关键决策：
- 会显著影响功能范围或用户体验。
- 存在多种合理解释，且不同解释会产生不同影响。
- 不存在任何合理默认值。
确定澄清优先级：范围 > 安全/隐私 > 用户体验 > 技术细节。
像测试人员一样思考：每项含糊需求都应无法通过“可测试且无歧义”检查项。
通常需要澄清的领域（仅在不存在合理默认值时）：
- 功能范围和边界（是否包含或排除特定使用场景）。
- 用户类型和权限（如果存在多种可能且相互冲突的解释）。
- 安全/合规要求（当涉及法律或财务影响时）。

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

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

Success Criteria Guidelines

成功标准指南

Success criteria must be:

Measurable: Include specific metrics (time, percentage, count, rate)
Technology-agnostic: No mention of frameworks, languages, databases, or tools
User-focused: Describe outcomes from user/business perspective, not system internals
Verifiable: Can be tested/validated without knowing implementation details

Good examples:

"Users can complete checkout in under 3 minutes"
"System supports 10,000 concurrent users"
"95% of searches return results in under 1 second"
"Task completion rate improves by 40%"

Bad examples (implementation-focused):

"API response time is under 200ms" (too technical, use "Users see results instantly")
"Database can handle 1000 TPS" (implementation detail, use user-facing metric)
"React components render efficiently" (framework-specific)
"Redis cache hit rate above 80%" (technology-specific)

成功标准必须：

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

良好示例：

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

不良示例（侧重实现）：

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

Done When

完成条件

Specification written to
```
SPEC_FILE
```
and validated against quality checklist
Extension hooks dispatched or skipped according to the rules in Mandatory Post-Execution Hooks above
Completion reported to user with feature directory, spec file path, and checklist results

规格已写入
```
SPEC_FILE
```
，并通过质量检查清单验证。
已根据“强制执行后置 Hook”部分的规则分派或跳过扩展 Hook。
已向用户报告功能目录、规格文件路径和检查清单结果。