Feature Specification: [FEATURE NAME]

Feature Branch: [###-feature-name] Created: [DATE] Status: Draft Input: User description: "$ARGUMENTS"

其中 `Feature Branch` 记录关联分支（由可选的 git 扩展创建），`Input` 保留触发命令的原始参数，保证规格来源可追溯。下游的 `plan` 和 `tasks` 命令依赖这些元信息以及 `.specify/feature.json` 中持久化的 `feature_directory` 路径来定位功能目录——这一点在 [specify 命令定义](https://gitcode.com/GitHub_Trending/sp/spec-kit/blob/9f19be9cad6e83d8b293041d8dbb1b7787c3ed54/templates/commands/specify.md?utm_source=gitcode_repo_files) 中有明确约定：写入 feature.json 的是实际解析出的目录路径（例如 `specs/003-user-auth`），而不是字面占位符。

## 用户场景与测试：以用户旅程为优先级的骨架

模板的第一个强制区块是 `User Scenarios & Testing *(mandatory)*`。模板内嵌的 HTML 注释给出了三条硬性约束：

1. **用户故事必须按重要性排序**（P1、P2、P3……），代表优先级递降的用户旅程；
2. **每个故事必须可独立测试**——单独实现其中任意一个，都应得到一个能交付价值的可运行 MVP；
3. 每个故事应能独立开发、独立测试、独立部署、独立向用户演示。

单个用户故事的完整结构如下：

```markdown
### User Story 1 - [Brief Title] (Priority: P1)

[Describe this user journey in plain language]

**Why this priority**: [Explain the value and why it has this priority level]

**Independent Test**: [Describe how this can be tested independently - e.g., "Can be fully tested by [specific action] and delivers [specific value]"]

**Acceptance Scenarios**:

1. **Given** [initial state], **When** [action], **Then** [expected outcome]
2. **Given** [initial state], **When** [action], **Then** [expected outcome]

四个字段各司其职：标题行内嵌优先级；Why this priority 迫使作者论证价值排序而非随意编号；Independent Test 给出可操作的独立验证路径（例如"可以通过执行 X 动作完整测试，并交付 Y 价值"）；验收场景采用 Given/When/Then 三段式，让每条验收标准都能被直接翻译为测试用例。模板预置了三个故事占位（P1/P2/P3），末尾注明"按需追加更多故事，每个都要分配优先级"。

故事区块之后是 Edge Cases 小节，模板用两条占位问题提示作者思考边界：

• What happens when [boundary condition]?
• How does system handle [error scenario]?

这两个问题对应两类最高频的规格遗漏：边界条件（空数据、极限值、并发冲突）与错误场景（依赖失败、权限不足、超时）。

需求区块：FR 编号与澄清标记机制

Requirements *(mandatory)* 区块承载功能需求，模板展示了标准的编号与书写范式：

- **FR-001**: System MUST [specific capability, e.g., "allow users to create accounts"]
- **FR-002**: System MUST [specific capability, e.g., "validate email addresses"]
- **FR-003**: Users MUST be able to [key interaction, e.g., "reset their password"]
- **FR-004**: System MUST [data requirement, e.g., "persist user preferences"]
- **FR-005**: System MUST [behavior, e.g., "log all security events"]

从示例的措辞可以看出模板对需求类型的覆盖设计：能力类（FR-001/002）、用户交互类（FR-003）、数据持久类（FR-004）、行为/合规类（FR-005）。所有需求都以 "MUST" 关键词约束，避免 "should/may" 带来的验收歧义。

当需求确实无法确定时，模板给出了显式的澄清标记写法：

- **FR-006**: System MUST authenticate users via [NEEDS CLARIFICATION: auth method not specified - email/password, SSO, OAuth?]
- **FR-007**: System MUST retain user data for [NEEDS CLARIFICATION: retention period not specified]

这个标记不是随意的注释，而是工作流的协议：specify 命令 规定了最多保留 3 个 [NEEDS CLARIFICATION] 标记，按"范围 > 安全/隐私 > 用户体验 > 技术细节"的优先级筛选，并以带选项表格的形式一次性向用户提问，得到答复后必须替换标记并重新跑校验。因此模板中 "标记不明确需求" 的示例写法，正是后续自动澄清环节的触发器。

若功能涉及数据，需求区块还包含 Key Entities 子节：

- **[Entity 1]**: [What it represents, key attributes without implementation]
- **[Entity 2]**: [What it represents, relationships to other entities]

注意约束是 "without implementation"——只描述实体语义、关键属性与实体间关系，禁止出现表结构、ORM 之类的实现细节。

成功标准：可度量且与技术无关

Success Criteria *(mandatory)* 区块要求结果同时满足"可度量"和"技术无关"，模板预置了四类指标占位：

- **SC-001**: [Measurable metric, e.g., "Users can complete account creation in under 2 minutes"]
- **SC-002**: [Measurable metric, e.g., "System handles 1000 concurrent users without degradation"]
- **SC-003**: [User satisfaction metric, e.g., "90% of users successfully complete primary task on first attempt"]
- **SC-004**: [Business metric, e.g., "Reduce support tickets related to [X] by 50%"]

四条示例分别覆盖时长、容量、用户满意度和业务影响，确保成功标准不是单一维度的性能数字。specify 命令 进一步给出了好坏示例的对照：好的标准如 "Users can complete checkout in under 3 minutes"、"95% of searches return results in under 1 second"；反例如 "API response time is under 200ms"（过于技术化）、"Redis cache hit rate above 80%"（绑定具体技术栈）。这条判据会进入规格质量检查单，未通过则触发最多 3 轮的规格修订。

假设区块：把"合理的默认值"显式化

模板最后一节 Assumptions 要求记录那些"需求未指明、但采用了合理默认值"的决策：

- [Assumption about target users, e.g., "Users have stable internet connectivity"]
- [Assumption about scope boundaries, e.g., "Mobile support is out of scope for v1"]
- [Assumption about data/environment, e.g., "Existing authentication system will be reused"]
- [Dependency on existing system/service, e.g., "Requires access to the existing user profile API"]