Spec-Kit在Claude Code中的工作原理完整解析

本文档详细分析了Spec-Kit规范驱动开发工具包在Claude Code中的完整工作原理，包括项目结构、命令提示词、执行流程和生成产物。

一、项目结构

1.1 目录结构

project dir/
├── .specify/                              # Spec-Kit核心目录
│   ├── memory/                            # 项目记忆
│   │   └── constitution.md                # 项目原则和开发准则
│   ├── scripts/bash/                      # Bash脚本
│   │   ├── common.sh                      # 通用函数库
│   │   ├── create-new-feature.sh          # 创建新功能
│   │   ├── setup-plan.sh                  # 设置实施计划
│   │   ├── update-agent-context.sh        # 更新代理上下文
│   │   └── check-prerequisites.sh         # 检查先决条件
│   └── templates/                         # 模板文件
│       ├── spec-template.md               # 功能规范模板
│       ├── plan-template.md               # 实施计划模板
│       ├── tasks-template.md              # 任务分解模板
│       ├── constitution-template.md       # 宪法模板
│       └── checklist-template.md          # 检查清单模板
├── .claude/                                # Claude Code配置
│   ├── commands/                          # 斜杠命令定义
│   │   ├── speckit.constitution.md        # /speckit.constitution命令
│   │   ├── speckit.specify.md             # /speckit.specify命令
│   │   ├── speckit.clarify.md             # /speckit.clarify命令
│   │   ├── speckit.plan.md                # /speckit.plan命令
│   │   ├── speckit.tasks.md               # /speckit.tasks命令
│   │   ├── speckit.implement.md           # /speckit.implement命令
│   │   ├── speckit.analyze.md             # /speckit.analyze命令
│   │   ├── speckit.checklist.md           # /speckit.checklist命令
│   │   └── speckit.taskstoissues.md       # /speckit.taskstoissues命令
│   └── settings.local.json                # Claude Code本地设置
└── specs/                                 # 功能规范存储
    └── [###-feature-name]/                # 每个功能一个目录
        ├── spec.md                         # 功能规范
        ├── plan.md                         # 实施计划
        ├── tasks.md                        # 任务列表
        ├── research.md                     # 技术研究
        ├── data-model.md                   # 数据模型
        ├── quickstart.md                   # 快速入门
        ├── contracts/                      # API契约
        └── checklists/                     # 质量检查清单
            └── requirements.md             # 需求质量检查清单

1.2 环境变量

变量名	作用	示例
`SPECIFY_FEATURE`	覆盖功能检测，指定功能目录	`001-timestamp-converter`

二、核心概念

2.1 规范驱动开发 (Spec-Driven Development)

传统开发流程：需求 → 代码 → 文档（可选）

规范驱动开发流程：需求 → 规范 → 计划 → 任务 → 代码

核心理念：

意图驱动：规范定义"是什么"和"为什么"，而不是"怎么做"
可执行规范：规范可直接生成实现代码，而不仅仅是指导开发
多步精炼：通过多轮迭代完善规范，而非一次性代码生成
质量门禁：通过Constitution检查确保符合项目原则

2.2 用户故事优先级

优先级	含义	实施顺序
P1	MVP核心功能	第一批实施
P2	重要但非核心	第二批实施
P3	增强功能	第三批实施

2.3 任务标记系统

标记	含义	示例
`[P]`	可并行执行（不同文件，无依赖）	`- [ ] T005 [P] 创建用户模型`
`[US1]`	属于用户故事1	`- [ ] T012 [US1] 实现用户服务`
`[X]`	任务已完成	`- [X] T001 创建项目结构`

三、完整命令解析

3.1 speckit.constitution - 建立项目原则

文件位置：.claude/commands/speckit.constitution.md

提示词模板（中文版）：

---
description: 从交互式或提供的原则输入创建或更新项目宪法，确保所有依赖模板保持同步
handoffs:
  - label: 构建规范
    agent: speckit.specify
    prompt: 根据更新的宪法实现功能规范。我想构建...
---

## 用户输入
$ARGUMENTS

## 执行大纲
你正在更新位于 `.specify/memory/constitution.md` 的项目宪法。
该文件是一个**模板**，包含方括号中的占位符标记（如 `[PROJECT_NAME]`、`[PRINCIPLE_1_NAME]`）。
你的工作是：(a) 收集/推导具体值，(b) 精确填充模板，(c) 跨所有依赖产物传播更新。

**注意**：如果 `.specify/memory/constitution.md` 尚不存在，应该在项目设置期间从 `.specify/templates/constitution-template.md` 初始化。如果缺失，请先复制模板。

遵循此执行流程：

1. 加载位于 `.specify/memory/constitution.md` 的现有宪法。
   - 识别每个 `[全部大写标识符]` 格式的占位符标记。
   **重要**：用户可能需要比模板中使用的原则更少或更多的原则。如果指定了数字，请遵守 - 你将相应地更新文档。

2. 为占位符收集/推导值：
   - 如果用户输入（对话）提供了值，使用它。
   - 否则从现有仓库上下文（README、文档、先前的宪法版本（如嵌入））推断。
   - 对于治理日期：`RATIFICATION_DATE` 是原始采用日期（如未知则询问或标记TODO），`LAST_AMENDED_DATE` 是今天如果进行了更改，否则保留之前的。
   - `CONSTITUTION_VERSION` 必须根据语义版本控制规则递增：
     - MAJOR：向后不兼容的治理/原则删除或重新定义。
     - MINOR：新原则/部分添加或实质性扩展指导。
     - PATCH：澄清、措辞、拼写修复、非语义细化。
   - 如果版本递增类型不明确，在最终确定前提出推理。

3. 起草更新的宪法内容：
   - 用具体文本替换每个占位符（除项目选择不定义的有意保留的模板槽位外 - 明确证明任何留下的合理性）。
   - 保留标题层级和注释可以在替换后删除，除非它们仍然增加澄清性指导。
   - 确保每个原则部分：简洁的名称行，段落（或项目符号列表）捕获非协商规则，明显的理由（如不显而易见）。
   - 确保治理部分列出修正程序、版本控制策略和合规审查期望。

4. 一致性传播检查清单（将先前的检查清单转换为活动验证）：
   - 读取 `.specify/templates/plan-template.md` 并确保任何"宪法检查"或规则与更新的原则保持一致。
   - 读取 `.specify/templates/spec-template.md` 以进行范围/需求一致性 - 如果宪法添加/删除了强制性部分或约束，则更新。
   - 读取 `.specify/templates/tasks-template.md` 并确保任务分类反映新的或删除的原则驱动的任务类型（例如，可观测性、版本控制、测试纪律）。
   - 读取 `.specify/templates/commands/*.md` 中的每个命令文件（包括此文件）以验证没有过时的引用（如CLAUDE等特定代理名称）在需要通用指导时保留。
   - 读取任何运行时指导文档（例如 `README.md`、`docs/quickstart.md` 或如果存在的特定代理指导文件）。更新对已更改原则的引用。

5. 产生同步影响报告（在更新后作为HTML注释前置在宪法文件顶部）：
   - 版本更改：旧 → 新
   - 修改的原则列表（旧标题 → 新标题（如重命名））
   - 添加的部分
   - 删除的部分
   - 需要更新的模板（✅ 已更新 / ⚠ 待定）及文件路径
   - 如有意延迟的占位符，则为后续TODO

6. 最终输出前的验证：
   - 没有剩余未解释的括号标记。
   - 版本行与报告匹配。
   - 日期ISO格式 YYYY-MM-DD。
   - 原则是声明性的、可测试的，没有模糊语言（"应该" → 在适当的地方替换为MUST/SHOULD理由）。

7. 将完成的宪法写回 `.specify/memory/constitution.md`（覆盖）。

8. 向用户输出最终摘要，包含：
   - 新版本和递增理由。
   - 任何标记为手动后续的文件。
   - 建议的提交消息（例如 `docs: 修正宪法到vX.Y.Z（原则添加 + 治理更新）`）。

格式和样式要求：

- 使用Markdown标题完全按照模板（不要降级/升级级别）。
- 将长理由行换行以保持可读性（理想情况下<100个字符），但不要用尴尬的换行强制执行。
- 各部分之间保持单行空白。
- 避免尾随空格。

如果用户提供部分更新（例如，仅一个原则修正），仍然执行验证和版本决策步骤。

如果关键信息缺失（例如，批准日期真正未知），插入 `TODO(<字段名称>): 解释` 并在延迟项目下的同步影响报告中包含。

不要创建新模板；始终操作现有的 `.specify/memory/constitution.md` 文件。

执行流程：

用户输入 → 读取constitution.md → 识别占位符 → 填充内容 → 更新相关模板 → 生成报告

生成产物：

.specify/memory/constitution.md - 项目原则文档

Constitution示例结构：

# [项目名称] 宪法

## 核心原则
### 一、代码质量卓越
[非协商规则]
### 二、测试标准
[测试标准]
### 三、用户体验一致性
[UX要求]
...

## 治理
[治理规则]

**版本**: 1.0.0 | **批准**: 2026-03-09 | **最后修正**: 2026-03-09

3.2 speckit.specify - 创建功能规范

文件位置：.claude/commands/speckit.specify.md

提示词模板（中文版）：

---
description: 从自然语言功能描述创建或更新功能规范
handoffs:
  - label: 构建技术计划
    agent: speckit.plan
    prompt: 为规范创建计划。我正在用...构建
  - label: 澄清规范需求
    agent: speckit.clarify
    prompt: 澄清规范需求
    send: true
---

## 用户输入
$ARGUMENTS

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

## 执行大纲
用户在触发消息中在 `/speckit.specify` 之后输入的文本**就是**功能描述。
假设你在本次对话中始终可用它，即使 `$ARGUMENTS` 字面出现在下面。
除非用户提供空命令，否则不要要求用户重复它。

鉴于该功能描述，执行以下操作：

1. **为分支生成简洁的短名称**（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"

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目录：检查匹配 `specs/[0-9]+-<short-name>` 的目录

   c. 确定下一个可用编号：
      - 从所有三个来源提取所有编号
      - 找到最高编号N
      - 使用N+1作为新分支编号

   d. 运行脚本 `.specify/scripts/bash/create-new-feature.sh --json "$ARGUMENTS"` 及计算出的编号和短名称：
      - 传递 `--number N+1` 和 `--short-name "your-short-name"` 及功能描述
      - Bash示例：`.specify/scripts/bash/create-new-feature.sh --json "$ARGUMENTS" --json --number 5 --short-name "user-auth" "Add user authentication"`
      - PowerShell示例：`.specify/scripts/bash/create-new-feature.sh --json "$ARGUMENTS" -Json -Number 5 -ShortName "user-auth" "Add user authentication"`

   **重要**：
   - 检查所有三个来源（远程分支、本地分支、specs目录）以找到最高编号
   - 仅匹配具有确切短名称模式的分支/目录
   - 如果未找到具有此短名称的现有分支/目录，从编号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` 生成检查清单文件，包含这些验证项：

      ```markdown
      # 规范质量检查清单: [功能名称]

      **目的**：在继续规划之前验证规范的完整性和质量
      **创建**：[日期]
      **功能**：[链接到spec.md]

      ## 内容质量

      - [ ] 无实施细节（语言、框架、API）
      - [ ] 专注于用户价值和业务需求
      - [ ] 为非技术利益相关者编写
      - [ ] 所有强制性部分已完成

      ## 需求完整性

      - [ ] 无 [需要澄清] 标记剩余
      - [ ] 需求是可测试且无歧义的
      - [ ] 成功标准是可衡量的
      - [ ] 成功标准与技术无关（无实施细节）
      - [ ] 所有验收场景已定义
      - [ ] 边界情况已识别
      - [ ] 范围有明确界限
      - [ ] 依赖和假设已识别

      ## 功能准备就绪

      - [ ] 所有功能需求都有明确的验收标准
      - [ ] 用户场景覆盖主要流程
      - [ ] 功能满足成功标准中定义的可衡量结果
      - [ ] 规范中无实施细节泄漏

      ## 注意事项

      - 标记为不完整的项目需要在 `/speckit.clarify` 或 `/speckit.plan` 之前更新规范
      ```

   b. **运行验证检查**：根据每个检查清单项审查规范：
      - 对于每一项，确定它通过还是失败
      - 记录发现的具体问题（引用相关规范部分）

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

      - **如果所有项通过**：标记检查清单完成并继续到步骤6

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

      - **如果 [需要澄清] 标记保留**：
        1. 从规范中提取所有 [需要澄清: ...] 标记
        2. **限制检查**：如果存在超过3个标记，仅保留3个最关键的（按范围/安全/UX影响）并为其余部分做出明智猜测
        3. 对于每个需要的澄清（最多3个），以此格式向用户展示选项：

           ```markdown
           ## 问题 [N]: [主题]

           **上下文**：[引用相关规范部分]

           **我们需要知道的内容**：[来自需要澄清标记的具体问题]

           **建议答案**：

           | 选项 | 答案 | 影响 |
           |--------|--------|--------------|
           | A      | [第一个建议答案] | [这对功能意味着什么] |
           | B      | [第二个建议答案] | [这对功能意味着什么] |
           | C      | [第三个建议答案] | [这对功能意味着什么] |
           | 自定义 | 提供你自己的答案 | [解释如何提供自定义输入] |

           **你的选择**：_[等待用户响应]_
           ```

        4. **关键 - 表格格式化**：确保markdown表格正确格式化：
           - 使用对齐管道的一致间距：`| 内容 |` 而不是 `|内容|`
           - 标题分隔符必须至少有3个破折号：`|--------|`
           - 测试表格在markdown预览中正确渲染
        5. 顺序编号问题（Q1, Q2, Q3 - 最多3个总计）
        6. 在等待响应之前一起展示所有问题
        7. 等待用户响应所有问题的选择（例如，"Q1: A, Q2: 自定义 - [详情], Q3: B"）
        8. 通过用用户选择或提供的答案替换每个 [需要澄清] 标记来更新规范
        9. 在所有澄清解决后重新运行验证

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

7. 报告完成，包含分支名称、规范文件路径、检查清单结果以及下一阶段（`/speckit.clarify` 或 `/speckit.plan`）的准备就绪。

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

## 通用指南

## 快速指南

- 专注于用户需要**什么**和**为什么**。
- 避免如何实施（无技术栈、API、代码结构）。
- 为业务利益相关者编写，而不是开发者。
- 不要创建嵌入在规范中的检查清单。那将是一个单独的命令。

### 部分要求

- **强制性部分**：必须为每个功能完成
- **可选部分**：仅在与功能相关时包括
- 当部分不适用时，完全删除它（不要保留为"不适用"）

### 用于AI生成

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

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

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

- 数据保留：行业的标准做法用于该领域
- 性能目标：除非指定，否则为标准Web/移动应用期望
- 错误处理：带有适当回退的用户友好消息
- 认证方法：标准基于会话或用于Web应用的OAuth2
- 集成模式：使用适合项目的模式（用于Web服务的REST/GraphQL、用于库的函数调用、用于工具的CLI参数等）

### 成功标准指南

成功标准必须是：

1. **可衡量的**：包括具体指标（时间、百分比、计数、速率）
2. **与技术无关的**：无框架、语言、数据库或工具的提及
3. **以用户为中心的**：从用户/业务角度描述结果，而不是系统内部
4. **可验证的**：可以在不了解实施细节的情况下测试/验证

**好的示例**：

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

**坏的示例**（实施聚焦）：

- "API响应时间低于200ms"（太技术化，使用"用户即时看到结果"）
- "数据库可以处理1000 TPS"（实施细节，使用面向用户的指标）
- "React组件高效渲染"（框架特定）
- "Redis缓存命中率高于80%"（技术特定）

执行流程：

用户输入功能描述
    ↓
生成分支短名称（2-4词）
    ↓
检查现有分支（remote/local/specs）获取最大编号
    ↓
调用 create-new-feature.sh 脚本
    ├─ 获取下一个功能编号
    ├─ 创建分支：###-short-name
    ├─ 创建目录：specs/###-short-name/
    └─ 复制模板到 spec.md
    ↓
Claude Code填充spec.md：
    ├─ 用户场景和测试（用户故事+优先级）
    ├─ 需求（功能需求FR-001, FR-002...）
    ├─ 成功标准（可衡量标准SC-001, SC-002...）
    └─ 关键实体（数据实体）
    ↓
创建质量检查清单：checklists/requirements.md
    ↓
验证规范质量
    ├─ 如有[需要澄清]：向用户提问（最多3个）
    └─ 更新规范
    ↓
完成：分支名、spec路径、检查清单结果

生成产物：

新分支：###-feature-name
specs/###-feature-name/spec.md - 功能规范
specs/###-feature-name/checklists/requirements.md - 质量检查清单

3.3 speckit.clarify - 澄清规范细节

文件位置：.claude/commands/speckit.clarify.md

提示词模板（中文版）：

---
description: 通过提出最多5个高度针对性的澄清问题来识别当前功能规范中规范不足的区域，并将答案直接编码回规范
handoffs:
  - label: 构建技术计划
    agent: speckit.plan
    prompt: 为规范创建计划。我正在用...构建
---

## 用户输入
$ARGUMENTS

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

## 执行大纲

目标：检测和减少活动功能规范中的模糊性或缺失决策点，并将澄清直接记录在规范文件中。

注意：此澄清工作流程预期在调用 `/speckit.plan` **之前**运行（并完成）。
如果用户明确声明他们正在跳过澄清（例如，探索性spike），你可以继续，但必须警告下游返工风险增加。

执行步骤：

1. 从仓库根目录运行 `.specify/scripts/bash/check-prerequisites.sh --json --paths-only` **一次**（组合 `--json --paths-only` 模式 / `-Json -PathsOnly`）。解析最小JSON负载字段：
   - `FEATURE_DIR`
   - `FEATURE_SPEC`
   - （可选捕获 `IMPL_PLAN`, `TASKS` 用于未来的链式流程）
   - 如果JSON解析失败，中止并指示用户重新运行 `/speckit.specify` 或验证功能分支环境。
   - 对于单引号参数如 "I'm Groot"，使用转义语法：例如 'I'\''m Groot'（或尽可能使用双引号："I'm Groot"）。

2. 加载当前规范文件。使用此分类法执行结构化模糊度和覆盖扫描。对于每个类别，标记状态：清晰 / 部分 / 缺失。产生内部覆盖图用于优先级排序（不输出原始地图，除非不会问问题）。

   功能范围与行为：
   - 核心用户目标和成功标准
   - 明确的排除范围声明
   - 用户角色/人物角色区分

   领域与数据模型：
   - 实体、属性、关系
   - 身份和唯一性规则
   - 生命周期/状态转换
   - 数据量/规模假设

   交互与UX流程：
   - 关键用户旅程/序列
   - 错误/空/加载状态
   - 无障碍或本地化说明

   非功能质量属性：
   - 性能（延迟、吞吐量目标）
   - 可扩展性（水平/垂直、限制）
   - 可靠性和可用性（正常运行时间、恢复期望）
   - 可观测性（日志、指标、跟踪信号）
   - 安全和隐私（认证N/Z、数据保护、威胁假设）
   - 合规/监管约束（如果任何）

   集成与外部依赖：
   - 外部服务/API及其失败模式
   - 数据导入/导出格式
   - 协议/版本假设

   边界情况与失败处理：
   - 负面场景
   - 速率限制/节流
   - 冲突解决（例如，并发编辑）

   约束与权衡：
   - 技术约束（语言、存储、托管）
   - 明确的权衡或被拒绝的替代方案

   术语与一致性：
   - 规范词汇表术语
   - 避免的同义词/弃用术语

   完成信号：
   - 验收标准可测试性
   - 可衡量的完成定义风格指示器

   其他/占位符：
   - TODO标记/未解决决策
   - 模糊形容词（"健壮"、"直观"）缺乏量化

   对于每个具有部分或缺失状态的类别，添加候选问题机会，除非：
   - 澄清不会实质性地改变实施或验证策略
   - 信息更适合推迟到规划阶段（内部记录）

3. （内部）生成优先排序的候选澄清问题队列（最多5个）。不要一次全部输出。应用这些约束：
    - 整个会话最多5个问题。
    - 每个问题必须可以用以下任一回答：
       - 短多选选择（2-5个不同、互斥的选项），或
       - 一个单词/短短语答案（明确约束："在<=5个词内回答"）。
    - 仅包括其答案实质性地影响架构、数据建模、任务分解、测试设计、UX行为、运营准备就绪或合规验证的问题。
    - 确保类别覆盖平衡：尝试首先覆盖最高影响的未解决类别；避免在单个高影响区域（例如，安全姿态）未解决时问两个低影响问题。
    - 排除已回答的问题、琐碎的风格偏好或规划级别的执行细节（除非阻塞正确性）。
    - 有利于减少下游返工风险或防止错位验收测试的澄清。
    - 如果超过5个类别仍未解决，按（影响 × 不确定性）启发式选择前5个。

4. 顺序提问循环（交互式）：
    - 一次只提出**一个问题**。
    - 对于多选问题：
       - **分析所有选项**并根据以下确定**最合适的选项**：
          - 项目类型的最佳实践
          - 类似实现中的通用模式
          - 风险降低（安全、性能、可维护性）
          - 与规范中可见的任何明确项目目标或约束保持一致
       - 在顶部突出显示你的**推荐选项**及清晰推理（1-2句话解释为什么这是最佳选择）。
       - 格式为：`**推荐：** 选项 [X] - <推理>`
       - 然后将所有选项渲染为Markdown表格：

       | 选项 | 描述 |
       |--------|-------------|
       | A | <选项A描述> |
       | B | <选项B描述> |
       | C | <选项C描述>（根据需要添加D/E，最多5个） |
       | 简短 | 提供不同的简短答案（<=5个词）（仅在适当的自由形式替代方案时包括） |

       - 在表格之后，添加：`你可以回复选项字母（例如，"A"），通过说"是"或"推荐"接受推荐，或提供你自己的简短答案。`
    - 对于简答样式（没有有意义的离散选项）：
       - 基于最佳实践和上下文提供你的**建议答案**。
       - 格式为：`**建议：** <你的提议答案> - <简要推理>`
       - 然后输出：`格式：简短答案（<=5个词）。你可以通过说"是"或"建议"接受建议，或提供你自己的答案。`
    - 用户回答后：
       - 如果用户回复"是"、"推荐"或"建议"，使用你之前陈述的推荐/建议作为答案。
       - 否则，验证答案映射到一个选项或符合<=5个词约束。
       - 如果不明确，要求快速消除歧义（计数仍属于同一问题；不要前进）。
       - 一旦满意，将其记录在工作内存中（尚未写入磁盘）并移动到下一个排队的问题。
    - 当以下情况时停止进一步提问：
       - 所有关键模糊性早期解决（剩余排队项目变得不必要），或
       - 用户发出完成信号（"完成"、"好"、"不再"），或
       - 你达到5个已问问题。
    - 永远不要提前揭示未来的排队问题。
    - 如果在开始时没有有效问题，立即报告没有关键模糊性。

5. 每次接受答案后的集成（增量更新方法）：
    - 维护规范的内存表示（在开始时加载一次）加上原始文件内容。
    - 对于此会话中的第一个集成答案：
       - 确保 `## 澄清` 部分存在（如果缺失，在规范模板中的最高级别上下文/概述部分之后创建它）。
       - 在其下，为今天创建 `### 会话 YYYY-MM-DD` 子标题（如果尚未存在）。
    - 在接受后立即追加项目符号行：`- 问: <问题> → 答: <最终答案>`。
    - 然后立即将澄清应用到最适当的部分：
       - 功能模糊性 → 更新或在功能需求中添加项目符号
       - 用户交互/行为者区分 → 使用澄清的角色、约束或场景更新用户故事或行为者小节（如果存在）
       - 数据形状/实体 → 更新数据模型（添加字段、类型、关系）保留排序；简洁地记录添加的约束
       - 非功能约束 → 在非功能/质量属性部分添加/修改可衡量标准（将模糊形容词转换为指标或明确目标）
       - 边界情况/负面流程 → 在边界情况/错误处理下添加新项目符号（或创建此类小节，如果模板为其提供占位符）
       - 术语冲突 → 在整个规范中规范化术语；仅在必要时通过添加 `(以前称为"X")` 一次来保留原始
    - 如果澄清使较早的模糊语句无效，则替换该语句而不是重复；不要留下任何过时的矛盾文本。
    - 在每次集成后保存规范文件以最大限度地减少上下文丢失风险（原子覆盖）。
    - 保留格式：不要重新排序不相关的部分；保持标题层次完整。
    - 保持每个插入的澄清最小化和可测试（避免叙述漂移）。

6. 验证（在每次写入加上最终通过后执行）：
   - 澄清会话包含每个接受答案的确切一个项目符号（无重复）。
   - 总共询问（接受）的问题 ≤ 5。
   - 更新的部分没有残留的模糊占位符，新答案旨在解决它们。
   - 没有残留的较早矛盾语句（扫描现在无效的替代选择，已删除）。
   - Markdown结构有效；仅允许的新标题：`## 澄清`, `### 会话 YYYY-MM-DD`。
   - 术语一致性：在所有更新的部分中使用相同的规范术语。

7. 将更新的规范写回 `FEATURE_SPEC`。

8. 报告完成（在提问循环结束或提前终止后）：
   - 询问和回答的问题数。
   - 更新规范的路径。
   - 触及的部分（列出名称）。
   - 覆盖摘要表，列出每个分类类别及状态：已解决（曾是部分/缺失并已处理）、推迟（超出问题配额或更适合规划）、清晰（已充分）、突出（仍是部分/缺失但低影响）。
   - 如果任何突出或推迟保留，推荐是继续到 `/speckit.plan` 还是在规划后再次运行 `/speckit.clarify`。
   - 建议的下一个命令。

行为规则：

- 如果没有发现有意义的模糊性（或所有潜在问题将是低影响的），响应："未检测到值得正式澄清的关键模糊性。"并建议继续。
- 如果规范文件缺失，指示用户首先运行 `/speckit.specify`（不要在这里创建新规范）。
- 永远不要超过总共5个已问问题（单个问题的澄清重试不计为新问题）。
- 除非缺失阻止功能清晰度，否则避免推测性技术栈问题。
- 尊重用户早期终止信号（"停止"、"完成"、"继续"）。
- 如果由于完整覆盖而没有问问题，输出紧凑的覆盖摘要（所有类别清晰）然后建议前进。
- 如果在仍有高影响类别未解决时达到配额，在推迟下明确标记它们及理由。

用于优先级排序的上下文：$ARGUMENTS

执行流程：

运行 check-prerequisites.sh 获取路径
    ↓
加载spec.md
    ↓
执行结构化模糊度扫描（10大分类）
    ↓
生成候选问题队列（最多5个）
    ↓
顺序提问循环：
    ├─ 一次只问一个问题
    ├─ 多选题：呈现推荐选项 + 表格
    ├─ 短答题：呈现建议答案
    └─ 用户回答后立即集成到spec
    ↓
验证：无矛盾、Markdown有效、术语一致
    ↓
保存spec.md
    ↓
报告：问题数、触及的章节、覆盖度摘要

3.4 speckit.plan - 生成技术计划

文件位置：.claude/commands/speckit.plan.md

提示词模板（中文版）：

---
description: 使用计划模板执行实施规划工作流程以生成设计产物
handoffs:
  - label: 创建任务
    agent: speckit.tasks
    prompt: 将计划分解为任务
  - label: 创建检查清单
    agent: speckit.checklist
    prompt: 为以下领域创建检查清单
---

## 用户输入
$ARGUMENTS

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

## 执行大纲

1. 从仓库根目录运行 `.specify/scripts/bash/setup-plan.sh --json` 并为 FEATURE_SPEC、IMPL_PLAN、SPECS_DIR、BRANCH 解析JSON。对于单引号参数如 "I'm Groot"，使用转义语法：例如 'I'\''m Groot'（或尽可能使用双引号："I'm Groot"）。

2. 加载上下文：读取 FEATURE_SPEC 和 `.specify/memory/constitution.md`。加载 IMPL_PLAN 模板（已复制）。

3. 执行计划工作流程：遵循 IMPL_PLAN 模板中的结构来：
   - 填充技术上下文（将未知标记为"需要澄清"）
   - 从宪法填充宪法检查部分
   - 评估门（错误如果违规未得到证明）
   - 阶段0：生成 research.md（解决所有需要澄清）
   - 阶段1：生成 data-model.md、contracts/、quickstart.md
   - 阶段1：通过运行代理脚本更新代理上下文
   - 设计后重新评估宪法检查

4. 停止并报告：命令在阶段2规划后结束。报告分支、IMPL_PLAN路径和生成的产物。

## 阶段

### 阶段0：大纲与研究

1. **从上述技术上下文中提取未知数**：
   - 对于每个需要澄清 → 研究任务
   - 对于每个依赖 → 最佳实践任务
   - 对于每个集成 → 模式任务

2. **生成和派发研究代理**：

   ```text
   对于技术上下文中的每个未知：
     任务："研究{未知}用于{功能上下文}"
   对于每个技术选择：
     任务："找到{技术}在{领域}中的最佳实践"
   

3. **使用以下格式整合研究中的发现** → `research.md`：
   - 决策：[选择了什么]
   - 理由：[为什么选择]
   - 考虑的替代方案：[评估了什么其他]

**输出**：research.md 所有的需要澄清已解决

### 阶段1：设计与契约

**先决条件**：`research.md` 完成

1. **从功能规范提取实体** → `data-model.md`：
   - 实体名称、字段、关系
   - 来自需求的验证规则
   - 状态转换（如果适用）

2. **定义接口契约**（如果项目有外部接口）→ `/contracts/`：
   - 识别项目向用户或其他系统暴露的接口
   - 记录适合项目类型的契约格式
   - 示例：库的公共API、CLI工具的命令模式、Web服务的端点、解析器的语法、应用程序的UI契约
   - 如果项目纯粹是内部的（构建脚本、一次性工具等），则跳过

3. **代理上下文更新**：
   - 运行 `.specify/scripts/bash/update-agent-context.sh claude`
   - 这些脚本检测正在使用哪个AI代理
   - 更新适当的代理特定上下文文件
   - 仅添加来自当前计划的新技术
   - 在标记之间保留手动添加

**输出**：data-model.md、/contracts/*、quickstart.md、代理特定文件

## 关键规则

- 使用绝对路径
- 门失败或未解决澄清的错误

执行流程：

运行 setup-plan.sh --json
    ↓
加载 spec.md 和 constitution.md
    ↓
填充 plan.md 模板：
    ├─ 摘要（功能摘要）
    ├─ 技术上下文
    │   ├─ 语言/版本
    │   ├─ 主要依赖
    │   ├─ 存储
    │   ├─ 测试
    │   ├─ 目标平台
    │   ├─ 项目类型
    │   ├─ 性能目标
    │   ├─ 约束
    │   └─ 规模/范围
    ├─ 宪法检查（质量门禁）
    └─ 项目结构
    ↓
阶段0: 研究阶段
    ├─ 提取技术上下文中的需要澄清
    ├─ 为每个未知项生成研究任务
    ├─ 派发并行研究代理
    └─ 整合发现 → research.md
    ↓
阶段1: 设计阶段
    ├─ 提取实体 → data-model.md
    ├─ 定义接口契约 → contracts/
    ├─ 生成快速入门 → quickstart.md
    └─ 运行 update-agent-context.sh
    ↓
重新评估宪法检查
    ↓
报告：分支名、产物路径

生成产物：

文件	内容
plan.md	技术实施计划
research.md	技术研究和决策记录
data-model.md	数据实体和关系
contracts/	API接口规范
quickstart.md	开发者快速入门

3.5 speckit.tasks - 生成任务列表

文件位置：.claude/commands/speckit.tasks.md

提示词模板（中文版）：

---
description: 根据可用的设计产物为功能生成可操作的、依赖有序的tasks.md
handoffs:
  - label: 分析一致性
    agent: speckit.analyze
    prompt: 运行项目分析以检查一致性
    send: true
  - label: 实施项目
    agent: speckit.implement
    prompt: 开始分阶段实施
    send: true
---

## 用户输入
$ARGUMENTS

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

## 执行大纲

1. **设置**：从仓库根目录运行 `.specify/scripts/bash/check-prerequisites.sh --json` 并为 FEATURE_DIR 和 AVAILABLE_DOCS 列表解析JSON。所有路径必须是绝对的。对于单引号参数如 "I'm Groot"，使用转义语法：例如 'I'\''m Groot'（或尽可能使用双引号："I'm Groot"）。

2. **加载设计文档**：从 FEATURE_DIR 读取：
   - **必需**：plan.md（技术栈、库、结构）、spec.md（带有优先级的用户故事）
   - **可选**：data-model.md（实体）、contracts/（接口契约）、research.md（决策）、quickstart.md（测试场景）
   - 注意：并非所有项目都有所有文档。基于可用的内容生成任务。

3. **执行任务生成工作流程**：
   - 加载 plan.md 并提取技术栈、库、项目结构
   - 加载 spec.md 并提取带有其优先级（P1、P2、P3等）的用户故事
   - 如果 data-model.md 存在：提取实体并映射到用户故事
   - 如果 contracts/ 存在：将接口契约映射到用户故事
   - 如果 research.md 存在：提取设置任务的决策
   - 生成按用户故事组织的任务（见下面的任务生成规则）
   - 生成显示用户故事完成顺序的依赖关系图
   - 每个用户故事创建并行执行示例
   - 验证任务完整性（每个用户故事具有所有所需任务，独立可测试）

4. **生成 tasks.md**：使用 `.specify/templates/tasks-template.md` 作为结构，填充：
   - 来自 plan.md 的正确功能名称
   - 阶段1：设置任务（项目初始化）
   - 阶段2：基础任务（所有用户故事的阻塞先决条件）
   - 阶段3+：每个用户故事一个阶段（按 spec.md 中的优先级顺序）
   - 每个阶段包括：故事目标、独立测试标准、测试（如果请求）、实施任务
   - 最终阶段：完善和跨故事关注点
   - 所有任务必须遵循严格检查清单格式（见下面的任务生成规则）
   - 每个任务的清晰文件路径
   - 显示故事完成顺序的依赖关系部分
   - 每个故事的并行执行示例
   - 实施策略部分（MVP优先、增量交付）

5. **报告**：输出生成的 tasks.md 的路径和摘要：
   - 总任务数
   - 每个用户故事的任务数
   - 识别的并行机会
   - 每个故事的独立测试标准
   - 建议的MVP范围（通常只是用户故事1）
   - 格式验证：确认所有任务遵循检查清单格式（复选框、ID、标签、文件路径）

用于任务生成的上下文：$ARGUMENTS

tasks.md 应该是立即可执行的 - 每个任务必须足够具体，以便LLM可以在没有额外上下文的情况下完成它。

## 任务生成规则

**关键**：任务必须按用户故事组织，以实现独立实施和测试。

**测试是可选的**：仅当功能规范中明确请求或用户请求TDD方法时才生成测试任务。

### 检查清单格式（必需）

每个任务必须严格遵循此格式：

```text
- [ ] [任务ID] [P?] [故事?] 带有文件路径的描述

**格式组件**：

1. **复选框**：始终以 `- [ ]` 开头（markdown复选框）
2. **任务ID**：顺序编号（T001、T002、T003...）按执行顺序
3. **[P]标记**：仅当任务可并行化时包括（不同文件、对未完成任务无依赖）
4. **[故事]标签**：仅用户故事阶段任务必需
   - 格式：[US1]、[US2]、[US3]等（映射到来自 spec.md 的用户故事）
   - 设置阶段：无故事标签
   - 基础阶段：无故事标签
   - 用户故事阶段：必须有故事标签
   - 完善阶段：无故事标签
5. **描述**：带有确切文件路径的清晰操作

**示例**：

- ✅ 正确：`- [ ] T001 根据实施计划创建项目结构`
- ✅ 正确：`- [ ] T005 [P] 在 src/middleware/auth.py 中实现认证中间件`
- ✅ 正确：`- [ ] T012 [P] [US1] 在 src/models/user.py 中创建用户模型`
- ✅ 正确：`- [ ] T014 [US1] 在 src/services/user_service.py 中实现用户服务`
- ❌ 错误：`- [ ] 创建用户模型`（缺少ID和故事标签）
- ❌ 错误：`T001 [US1] 创建模型`（缺少复选框）
- ❌ 错误：`- [ ] [US1] 创建用户模型`（缺少任务ID）
- ❌ 错误：`- [ ] T001 [US1] 创建模型`（缺少文件路径）

### 任务组织

1. **来自用户故事（spec.md）** - 主要组织：
   - 每个用户故事（P1、P2、P3...）获得自己的阶段
   - 将所有相关组件映射到它们的故事：
     - 该故事所需的模型
     - 该故事所需的服务
     - 该故事所需的接口/UI
     - 如果请求测试：特定于该故事的测试
   - 标记故事依赖（大多数故事应该是独立的）

2. **来自契约**：
   - 将每个接口契约映射到它服务的用户故事
   - 如果请求测试：每个接口契约 → 在该故事阶段的契约测试任务 [P] 在实施之前

3. **来自数据模型**：
   - 将每个实体映射到需要它的用户故事
   - 如果实体服务于多个故事：放在最早的故事或设置阶段
   - 关系 → 适当故事阶段中的服务层任务

4. **来自设置/基础设施**：
   - 共享基础设施 → 设置阶段（阶段1）
   - 基础/阻塞任务 → 基础阶段（阶段2）
   - 故事特定设置 → 在该故事阶段内

### 阶段结构

- **阶段1**：设置（项目初始化）
- **阶段2**：基础（阻塞先决条件 - 必须在用户故事之前完成）
- **阶段3+**：按优先级的用户故事（P1、P2、P3...）
  - 在每个故事内：测试（如果请求）→ 模型 → 服务 → 端点 → 集成
  - 每个阶段应该是一个完整的、独立可测试的增量
- **最终阶段**：完善和跨故事关注点

执行流程：

运行 check-prerequisites.sh --json
    ↓
加载设计文档：
    ├─ plan.md: 技术栈、库、项目结构
    ├─ spec.md: 用户故事+优先级
    ├─ data-model.md: 实体（可选）
    ├─ contracts/: 接口契约（可选）
    ├─ research.md: 决策（可选）
    └─ quickstart.md: 测试场景（可选）
    ↓
执行任务生成工作流：
    ├─ 提取技术栈、库、项目结构
    ├─ 提取用户故事+优先级（P1, P2, P3）
    ├─ 映射实体到用户故事
    ├─ 映射接口契约到用户故事
    ├─ 为设置阶段提取决策
    └─ 生成按用户故事组织的任务
    ↓
生成依赖关系图
    ↓
创建并行执行示例
    ↓
验证任务完整性
    ↓
使用 tasks-template.md 生成 tasks.md
    ↓
报告：任务总数、每个用户故事的任务数、并行机会、MVP范围

3.6 speckit.implement - 执行实施

文件位置：.claude/commands/speckit.implement.md

提示词模板（中文版）：

---
description: 通过处理和执行tasks.md中定义的所有任务来执行实施计划
---

## 用户输入
$ARGUMENTS

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

## 执行大纲

1. 从仓库根目录运行 `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` 并为 FEATURE_DIR 和 AVAILABLE_DOCS 列表解析JSON。所有路径必须是绝对的。对于单引号参数如 "I'm Groot"，使用转义语法：例如 'I'\''m Groot'（或尽可能使用双引号："I'm Groot"）。

2. **检查检查清单状态**（如果 FEATURE_DIR/checklists/ 存在）：
   - 扫描 checklists/ 目录中的所有检查清单文件
   - 对于每个检查清单，计算：
     - 总项目：所有匹配 `- [ ]` 或 `- [X]` 或 `- [x]` 的行
     - 完成项目：匹配 `- [X]` 或 `- [x]` 的行
     - 未完成项目：匹配 `- [ ]` 的行
   - 创建状态表：

     ```text
     | 检查清单 | 总计 | 完成 | 未完成 | 状态 |
     |-----------|-------|-----------|------------|--------|
     | ux.md     | 12    | 12        | 0          | ✓ 通过 |
     | test.md   | 8     | 5         | 3          | ✗ 失败 |
     | security.md | 6   | 6         | 0          | ✓ 通过 |
     ```

   - 计算总体状态：
     - **通过**：所有检查清单有0个未完成项目
     - **失败**：一个或多个检查清单有未完成项目

   - **如果任何检查清单未完成**：
     - 显示带有未完成项目数的表
     - **停止**并询问："某些检查清单未完成。你是否仍要继续实施？（是/否）"
     - 在继续之前等待用户响应
     - 如果用户说"不"或"等待"或"停止"，停止执行
     - 如果用户说"是"或"继续"或"继续"，继续到步骤3

   - **如果所有检查清单完成**：
     - 显示显示所有检查清单通过的表
     - 自动继续到步骤3

3. 加载和分析实施上下文：
   - **必需**：读取 tasks.md 以获取完整任务列表和执行计划
   - **必需**：读取 plan.md 以获取技术栈、架构和文件结构
   - **如果存在**：读取 data-model.md 以获取实体和关系
   - **如果存在**：读取 contracts/ 以获取API规范和测试需求
   - **如果存在**：读取 research.md 以获取技术决策和约束
   - **如果存在**：读取 quickstart.md 以获取集成场景

4. **项目设置验证**：
   - **必需**：根据实际项目设置创建/验证忽略文件：

   **检测与创建逻辑**：
   - 检查以下命令是否成功以确定仓库是否为git仓库（如果是则创建/验证.gitignore）：

     ```sh
     git rev-parse --git-dir 2>/dev/null
     ```

   - 检查 Dockerfile* 是否存在或 plan.md 中有Docker → 创建/验证 .dockerignore
   - 检查 .eslintrc* 是否存在 → 创建/验证 .eslintignore
   - 检查 eslint.config.* 是否存在 → 确保配置的 `ignores` 条目覆盖所需模式
   - 检查 .prettierrc* 是否存在 → 创建/验证 .prettierignore
   - 检查 .npmrc 或 package.json 是否存在 → 创建/验证 .npmignore（如果发布）
   - 检查是否存在terraform文件（*.tf） → 创建/验证 .terraformignore
   - 检查是否需要 .helmignore（存在helm charts） → 创建/验证 .helmignore

   **如果忽略文件已存在**：验证它包含基本模式，仅追加缺失的关键模式
   **如果忽略文件缺失**：为检测到的技术创建完整模式集

   **来自 plan.md 技术栈的按技术通用模式**：
   - **Node.js/JavaScript/TypeScript**：`node_modules/`、`dist/`、`build/`、`*.log`、`.env*`
   - **Python**：`__pycache__/`、`*.pyc`、`.venv/`、`venv/`、`dist/`、`*.egg-info/`
   - **Java**：`target/`、`*.class`、`*.jar`、`.gradle/`、`build/`
   - **C#/.NET**：`bin/`、`obj/`、`*.user`、`*.suo`、`packages/`
   - **Go**：`*.exe`、`*.test`、`vendor/`、`*.out`
   - **Ruby**：`.bundle/`、`log/`、`tmp/`、`*.gem`、`vendor/bundle/`
   - **PHP**：`vendor/`、`*.log`、`*.cache`、`*.env`
   - **Rust**：`target/`、`debug/`、`release/`、`*.rs.bk`、`*.rlib`、`*.prof*`、`.idea/`、`*.log`、`.env*`
   - **Kotlin**：`build/`、`out/`、`.gradle/`、`.idea/`、`*.class`、`*.jar`、`*.iml`、`*.log`、`.env*`
   - **C++**：`build/`、`bin/`、`obj/`、`out/`、`*.o`、`*.so`、`*.a`、`*.exe`、`*.dll`、`.idea/`、`*.log`、`.env*`
   - **C**：`build/`、`bin/`、`obj/`、`out/`、`*.o`、`*.a`、`*.so`、`*.exe`、`autom4te.cache/`、`config.status`、`config.log`、`.idea/`、`*.log`、`.env*`
   - **Swift**：`.build/`、`DerivedData/`、`*.swiftpm/`、`Packages/`
   - **R**：`.Rproj.user/`、`.Rhistory`、`.RData`、`.Ruserdata`、`*.Rproj`、`packrat/`、`renv/`
   - **通用**：`.DS_Store`、`Thumbs.db`、`*.tmp`、`*.swp`、`.vscode/`、`.idea/`

   **工具特定模式**：
   - **Docker**：`node_modules/`、`.git/`、`Dockerfile*`、`.dockerignore`、`*.log*`、`.env*`、`coverage/`
   - **ESLint**：`node_modules/`、`dist/`、`build/`、`coverage/`、`*.min.js`
   - **Prettier**：`node_modules/`、`dist/`、`build/`、`coverage/`、`package-lock.json`、`yarn.lock`、`pnpm-lock.yaml`
   - **Terraform**：`.terraform/`、`*.tfstate*`、`*.tfvars`、`.terraform.lock.hcl`
   - **Kubernetes/k8s**：`*.secret.yaml`、`secrets/`、`.kube/`、`kubeconfig*`、`*.key`、`*.crt`

5. 解析 tasks.md 结构并提取：
   - **任务阶段**：设置、测试、核心、集成、完善
   - **任务依赖**：顺序与并行执行规则
   - **任务详情**：ID、描述、文件路径、并行标记 [P]
   - **执行流程**：顺序和依赖需求

6. 按照任务计划执行实施：
   - **逐阶段执行**：在移动到下一个之前完成每个阶段
   - **尊重依赖**：按顺序运行顺序任务，并行任务 [P] 可以一起运行
   - **遵循TDD方法**：在相应的实施任务之前执行测试任务
   - **基于文件的协调**：影响相同文件的任务必须顺序运行
   - **验证检查点**：在继续之前验证每个阶段完成

7. 实施执行规则：
   - **设置优先**：初始化项目结构、依赖、配置
   - **测试优先**：如果你需要为契约、实体和集成场景编写测试
   - **核心开发**：实施模型、服务、CLI命令、端点
   - **集成工作**：数据库连接、中间件、日志、外部服务
   - **完善和验证**：单元测试、性能优化、文档

8. 进度跟踪和错误处理：
   - 在每个完成的任务后报告进度
   - 如果任何非并行任务失败，则停止执行
   - 对于并行任务 [P]，继续成功的任务，报告失败的任务
   - 提供带有调试上下文的清晰错误消息
   - 如果实施无法继续，建议下一步
   - **重要**：对于已完成的任务，确保在任务文件中将任务标记为 [X]。

9. 完成验证：
   - 验证所有必需任务已完成
   - 检查实施的功能与原始规范匹配
   - 验证测试通过且覆盖满足需求
   - 确认实施遵循技术计划
   - 报告最终状态及已完成工作的摘要

注意：此命令假设 tasks.md 中存在完整的任务分解。如果任务不完整或缺失，建议首先运行 `/speckit.tasks` 以重新生成任务列表。

执行流程：

运行 check-prerequisites.sh --json --require-tasks --include-tasks
    ↓
检查checklists状态
    ├─ 扫描checklists/目录
    ├─ 统计完成/未完成项
    ├─ 创建状态表
    └─ 如有未完成项：询问用户是否继续
    ↓
加载实施上下文：
    ├─ tasks.md（必需）
    ├─ plan.md（必需）
    ├─ data-model.md（可选）
    ├─ contracts/（可选）
    ├─ research.md（可选）
    └─ quickstart.md（可选）
    ↓
项目设置验证：
    ├─ 检测Git仓库 → 创建/验证 .gitignore
    ├─ 检测Docker → 创建/验证 .dockerignore
    ├─ 检测ESLint → 创建/验证 .eslintignore
    ├─ 检测Prettier → 创建/验证 .prettierignore
    └─ 检测其他工具 → 创建相应ignore文件
    ↓
解析tasks.md结构
    ├─ 任务阶段
    ├─ 任务依赖
    ├─ 任务详情
    └─ 执行流程
    ↓
按阶段执行实施：
    ├─ 阶段1: 设置（项目初始化）
    ├─ 阶段2: 基础（基础设施）
    ├─ 阶段3+: 用户故事（按优先级）
    └─ 最终阶段: 完善（跨故事改进）
    ↓
进度跟踪和错误处理
    ├─ 每个任务完成后报告
    ├─ 非并行任务失败时停止
    ├─ 并行任务：继续成功的，报告失败的
    └─ 在tasks.md中标记已完成任务为[X]
    ↓
完成验证
    ├─ 验证所有必需任务已完成
    ├─ 检查实现与原始规范匹配
    ├─ 验证测试通过
    └─ 确认实施遵循技术计划

3.7 speckit.analyze - 跨文档一致性分析

文件位置：.claude/commands/speckit.analyze.md

提示词模板（中文版）：

---
description: 在任务生成后对spec.md、plan.md和tasks.md执行非破坏性的跨工件一致性和质量分析
---

## 目标
在实施之前识别三个核心工件（`spec.md`、`plan.md`、`tasks.md`）中的不一致、重复、模糊性和规范不足的项目。此命令**必须**仅在 `/speckit.tasks` 成功产生完整的 `tasks.md` 后运行。

## 操作约束

**严格只读**：**不要**修改任何文件。输出结构化分析报告。提供可选的补救计划（用户必须在任何手动编辑命令被调用之前明确批准）。

**宪法权威**：项目宪法（`.specify/memory/constitution.md`）在此分析范围内是**不可协商的**。宪法冲突自动为关键，需要调整规范、计划或任务 - 而不是稀释、重新解释或默默忽略原则。如果原则本身需要更改，那必须在 `/speckit.analyze` 之外的单独、明确的宪法更新中进行。

## 执行步骤

### 1. 初始化分析上下文

从仓库根目录运行一次 `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` 并为 FEATURE_DIR 和 AVAILABLE_DOCS 解析JSON。推导绝对路径：

- SPEC = FEATURE_DIR/spec.md
- PLAN = FEATURE_DIR/plan.md
- TASKS = FEATURE_DIR/tasks.md

如果任何必需文件缺失，则中止并显示错误消息（指示用户运行缺失的先决命令）。
对于单引号参数如 "I'm Groot"，使用转义语法：例如 'I'\''m Groot'（或尽可能使用双引号："I'm Groot"）。

### 2. 加载工件（渐进式披露）

仅从每个工件加载最小的必要上下文：

**从 spec.md**：

- 概览/上下文
- 功能需求
- 非功能需求
- 用户故事
- 边界情况（如果存在）

**从 plan.md**：

- 架构/技术栈选择
- 数据模型引用
- 阶段
- 技术约束

**从 tasks.md**：

- 任务ID
- 描述
- 阶段分组
- 并行标记 [P]
- 引用的文件路径

**从宪法**：

- 加载 `.specify/memory/constitution.md` 以进行原则验证

### 3. 构建语义模型

创建内部表示（不要在输出中包含原始工件）：

- **需求清单**：每个功能+非功能需求，具有稳定键（基于祈使短语推导slugg；例如，"用户可以上传文件" → `user-can-upload-file`）
- **用户故事/操作清单**：具有验收标准的离散用户操作
- **任务覆盖映射**：将每个任务映射到一个或多个需求或故事（通过关键字/显式引用模式如ID或关键短语推断）
- **宪法规则集**：提取原则名称和MUST/SHOULD规范性语句

### 4. 检测通过（令牌高效分析）

专注于高信号发现。限制总共50个发现；在溢出摘要中聚合其余部分。

#### A. 重复检测

- 识别近似重复需求
- 标记低质量措辞以进行合并

#### B. 模糊度检测

- 标记模糊形容词（快速、可扩展、安全、直观、健壮）缺乏可衡量标准
- 标记未解决的占位符（TODO、TKTK、???、`<placeholder>`等）

#### C. 规范不足

- 有动词但缺少对象或可衡量结果的需求
- 缺少验收标准对齐的用户故事
- 引用规范/计划中未定义的文件或组件的任务

#### D. 宪法对齐

- 任何与MUST原则冲突的需求或计划元素
- 来自宪法的缺失强制性部分或质量门

#### E. 覆盖空白

- 具有零关联任务的需求
- 没有映射需求/故事的任务
- 未在任务中反映的非功能需求（例如，性能、安全）

#### F. 不一致性

- 术语漂移（相同概念在不同文件中命名不同）
- 在计划中引用但在规范中缺失的数据实体（或反之）
- 任务排序矛盾（例如，集成任务在没有依赖注释的基础设置任务之前）
- 冲突需求（例如，一个要求Next.js而另一个指定Vue）

### 5. 严重性分配

使用此启发式方法确定发现的优先级：

- **关键**：违反宪法MUST、缺失核心规范工件或零覆盖阻塞基线功能的需求
- **高**：重复或冲突需求、模糊安全/性能属性、不可测试的验收标准
- **中**：术语漂移、缺失非功能任务覆盖、规范不足的边界情况
- **低**：样式/措辞改进、不影响执行顺序的轻微冗余

### 6. 生成紧凑分析报告

输出Markdown报告（无文件写入），具有以下结构：

## 规范分析报告

| ID | 类别 | 严重性 | 位置 | 摘要 | 建议 |
|----|----------|----------|-------------|---------|----------------|
| A1 | 重复 | 高 | spec.md:L120-134 | 两个类似需求 ... | 合并措辞；保留更清晰的版本 |

（为每个发现添加一行；生成稳定的前缀按类别字母的ID）

**覆盖摘要表**：

| 需求键 | 有任务？ | 任务ID | 注释 |
|-----------------|-----------|----------|-------|

**宪法对齐问题**：（如果任何）

**未映射任务**：（如果任何）

**指标**：

- 总需求数
- 总任务数
- 覆盖 %（具有>=1个任务的需求）
- 模糊度计数
- 重复计数
- 关键问题计数

### 7. 提供下一步操作

在报告末尾，输出简洁的下一步操作块：

- 如果存在关键问题：推荐在 `/speckit.implement` 之前解决
- 如果仅低/中：用户可以继续，但提供改进建议
- 提供明确的命令建议：例如，"运行 /speckit.specify 进行细化"，"运行 /speckit.plan 调整架构"，"手动编辑 tasks.md 以添加'performance-metrics'的覆盖"

### 8. 提供补救

询问用户："你希望我为前N个问题建议具体的补救编辑吗？"（不要自动应用它们）。

## 操作原则

### 上下文效率

- **最小高信号令牌**：专注于可操作的发现，而不是详尽的文档
- **渐进式披露**：增量加载工件；不要将所有内容转储到分析中
- **令牌高效输出**：限制发现表到50行；汇总溢出
- **确定性的结果**：在没有更改的情况下重新运行应该产生一致的ID和计数

### 分析指南

- **永不修改文件**（这是只读分析）
- **永不幻觉缺失的部分**（如果缺失，准确报告）
- **优先考虑宪法违规**（这些始终是关键的）
- **使用示例而不是详尽规则**（引用具体实例，而不是通用模式）
- **优雅地报告零问题**（发出具有覆盖统计的成功报告）

## 上下文
$ARGUMENTS

执行流程：

运行 check-prerequisites.sh --json --require-tasks --include-tasks
    ↓
加载工件（渐进式披露）：
    ├─ spec.md: 概览、需求、用户故事、边界情况
    ├─ plan.md: 架构/技术栈选择、数据模型、阶段、约束
    ├─ tasks.md: 任务ID、描述、阶段分组、并行标记、文件路径
    └─ constitution.md: 原则和MUST/SHOULD语句
    ↓
构建语义模型：
    ├─ 需求清单：每个功能+非功能需求
    ├─ 用户故事/操作清单
    ├─ 任务覆盖映射：任务→需求/故事
    └─ 宪法规则集
    ↓
检测通过（最多50个发现）：
    ├─ A. 重复检测
    ├─ B. 模糊度检测
    ├─ C. 规范不足
    ├─ D. 宪法对齐
    ├─ E. 覆盖空白
    └─ F. 不一致性
    ↓
严重性分配：
    ├─ 关键：违反宪法MUST
    ├─ 高：重复/冲突需求
    ├─ 中：术语漂移
    └─ 低：样式/措辞改进
    ↓
生成紧凑分析报告
    ↓
提供下一步操作
    ↓
提供补救（可选）

3.8 speckit.checklist - 生成质量检查清单

文件位置：.claude/commands/speckit.checklist.md

核心概念："需求的单元测试"

提示词模板（中文版）：

---
description: 根据用户需求为当前功能生成自定义检查清单
---

## 检查清单目的："需求的单元测试"

**关键概念**：检查清单是**需求的单元测试** - 它们验证给定领域中需求的质量、清晰度和完整性。

**不用于验证/测试**：

- ❌ 不是"验证按钮点击正确"
- ❌ 不是"测试错误处理工作"
- ❌ 不是"确认API返回200"
- ❌ 不检查代码/实施是否与规范匹配

**用于需求质量验证**：

- ✅ "是否为所有卡片类型定义了视觉层次需求？"（完整性）
- ✅ "是否用特定的尺寸/定位量化了'突出显示'？"（清晰度）
- ✅ "是否在所有交互元素间一致地定义了悬停状态需求？"（一致性）
- ✅ "是否为键盘导航定义了无障碍需求？"（覆盖）
- ✅ "规范是否定义了徽标图像加载失败时发生什么？"（边界情况）

**隐喻**：如果你的规范是用英语编写的代码，检查清单就是它的单元测试套件。你正在测试需求是否写得很好、完整、无歧义且准备好实施 - 而不是实施是否有效。

## 用户输入
$ARGUMENTS

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

## 执行步骤

1. **设置**：从仓库根目录运行 `.specify/scripts/bash/check-prerequisites.sh --json` 并为 FEATURE_DIR 和 AVAILABLE_DOCS 列表解析JSON。
   - 所有文件路径必须是绝对的。
   - 对于单引号参数如 "I'm Groot"，使用转义语法：例如 'I'\''m Groot'（或尽可能使用双引号："I'm Groot"）。

2. **澄清意图（动态）**：推导最多三个初始上下文澄清问题（无预编目录）。它们必须：
   - 从用户措辞+从spec/plan/tasks提取的信号生成
   - 仅询问显著改变检查清单内容的信息
   - 如在 `$ARGUMENTS` 中已经不明确则跳过个别问题
   - 优先考虑精度而不是广度

   生成算法：
   1. 提取信号：功能域关键字（例如，auth、延迟、UX、API）、风险指标（"关键"、"必须"、"合规"）、利益相关者提示（"QA"、"审查"、"安全团队"）和明确的交付物（"a11y"、"回滚"、"契约"）。
   2. 将信号聚类为候选关注区域（最多4个）按相关性排名。
   3. 如果不明确，识别可能的受众和时机（作者、审查者、QA、发布）。
   4. 检测缺失维度：范围广度、深度/严格性、风险强调、排除边界、可衡量验收标准。
   5. 从这些原型制定问题：
      - 范围细化（例如，"这应该包括与X和Y的集成接触点还是局限于本地模块正确性？"）
      - 风险优先级（例如，"这些潜在风险区域中哪些应该接收强制性门控检查？"）
      - 深度校准（例如，"这是一个轻量级预提交理智列表还是正式发布门？"）
      - 受众框架（例如，"这将由仅作者使用还是在PR审查期间由同行使用？"）
      - 边界排除（例如，"我们是否应该明确排除此轮的性能调整项目？"）
      - 场景类差距（例如，"未检测到恢复流程——回滚/部分失败路径在范围内吗？"）

   问题格式化规则：
   - 如果呈现选项，生成带有列的紧凑表：选项 | 候选 | 为什么重要
   - 选项限制为A-E最多；如果自由形式答案更清晰，则省略表
   - 永远不要要求用户重述他们已经说过的内容
   - 避免推测性类别（无幻觉）。如果不明确，明确询问："确认X是否属于范围。"

   交互不可能时的默认值：
   - 深度：标准
   - 受众：审查者（PR）如果与代码相关；否则作者
   - 焦点：前2个相关性集群

   输出问题（标记Q1/Q2/Q3）。答案后：如果≥2个场景类（交替/异常/恢复/非功能域）仍然不清楚，你可能会问最多两个额外的定向后续（Q4/Q5），每个有一行理由（例如，"未解决的恢复路径风险"）。如果用户明确拒绝更多，则不要超过五个总问题。如果用户明确拒绝更多，则跳过升级。

3. **理解用户请求**：结合 `$ARGUMENTS` + 澄清答案：
   - 推导检查清单主题（例如，安全、审查、部署、ux）
   - 合并用户提到的明确必需项目
   - 将焦点选择映射到类别脚手架
   - 从spec/plan/tasks推断任何缺失上下文（不要幻觉）

4. **加载功能上下文**：从 FEATURE_DIR 读取：
   - spec.md：功能需求和范围
   - plan.md（如果存在）：技术细节、依赖
   - tasks.md（如果存在）：实施任务

   **上下文加载策略**：
   - 仅加载与活动焦点区域相关的必要部分（避免完整文件转储）
   - 优先将长章节总结为简洁的场景/需求项目符号
   - 使用渐进式披露：仅在检测到间隙时添加后续检索
   - 如果源文档很大，生成中间摘要项目而不是嵌入原始文本

5. **生成检查清单** - 创建"需求的单元测试"：
   - 如果不存在则创建 `FEATURE_DIR/checklists/` 目录
   - 生成唯一检查清单文件名：
     - 使用基于域的简短、描述性名称（例如，`ux.md`、`api.md`、`security.md`）
     - 格式：`[域].md`
   - 文件处理行为：
     - 如果文件不存在：创建新文件，从CHK001开始编号项目
     - 如果文件存在：将新项目追加到现有文件，从最后一个CHK ID继续（例如，如果最后一项是CHK015，从CHK016开始新项目）
   - 永不删除或替换现有检查清单内容 - 始终保留并追加

   **核心原则 - 测试需求，而非实施**：
   每个检查清单项目必须针对**需求本身**评估：
   - **完整性**：是否记录了所有必要需求？
   - **清晰度**：需求是否明确且具体？
   - **一致性**：需求是否彼此一致？
   - **可衡量性**：需求是否可以客观验证？
   - **覆盖**：是否处理了所有场景/边界情况？

   **类别结构** - 按需求质量维度分组项目：
   - **需求完整性**（是否记录了所有必要需求？）
   - **需求清晰度**（需求是否明确且无歧义？）
   - **需求一致性**（需求是否一致无冲突？）
   - **验收标准质量**（成功标准是否可衡量？）
   - **场景覆盖**（是否处理了所有流程/案例？）
   - **边界情况覆盖**（是否定义了边界条件？）
   - **非功能需求**（性能、安全、无障碍等 - 是否指定？）
   - **依赖与假设**（是否记录和验证了？）
   - **模糊与冲突**（需要澄清什么？）

   **如何编写检查清单项目 - "需求的单元测试"**：

   ❌ **错误**（测试实施）：
   - "验证落地页显示3个剧集卡片"
   - "测试桌面上的悬停状态工作"
   - "确认徽标点击导航到主页"

   ✅ **正确**（测试需求质量）：
   - "是否确切指定了特色剧集的数量和布局？" [完整性]
   - "是否用特定的尺寸/定位量化了'突出显示'？" [清晰度]
   - "是否在所有交互元素间一致地定义了悬停状态需求？" [一致性]
   - "是否为所有交互UI定义了键盘导航需求？" [覆盖]
   - "是否指定了徽标图像加载失败时的回退行为？" [边界情况]
   - "是否为异步剧集数据定义了加载状态？" [完整性]
   - "是否为竞争UI元素定义了视觉层次需求？" [清晰度]

   **项目结构**：
   每个项目应遵循此模式：
   - 询问需求质量的问题格式
   - 专注于规范中写的内容（或未写的内容）
   - 在括号中包括质量维度 [完整性/清晰度/一致性等]
   - 检查现有需求时引用规范章节 `[规范 §X.Y]`
   - 对缺失需求使用 `[间隙]` 标记

   **按质量维度的示例**：

   完整性：
   - "是否为所有API失败模式定义了错误处理需求？[间隙]"
   - "是否为所有交互元素指定了无障碍需求？[完整性]"
   - "是否为响应式布局定义了移动断点需求？[间隙]"

   清晰度：
   - "是否用特定的时间阈值量化了'快速加载'？[清晰度，规范 §NFR-2]"
   - "是否明确定义了'相关剧集'的选择标准？[清晰度，规范 §FR-5]"
   - "是否用可测量的视觉属性定义了'突出'？[模糊性，规范 §FR-4]"

   一致性：
   - "所有页面的导航需求是否一致？[一致性，规范 §FR-10]"
   - "落地和详情页面之间的卡片组件需求是否一致？[一致性]"

   覆盖：
   - "是否为零状态场景（无剧集）定义了需求？[覆盖，边界情况]"
   - "是否解决了并发用户交互场景？[覆盖，间隙]"
   - "是否为部分数据加载失败指定了需求？[覆盖，异常流程]"

   可衡量性：
   - "视觉层次需求是否可衡量/可测试？[验收标准，规范 §FR-1]"
   - "'平衡视觉权重'是否可以客观验证？[可衡量性，规范 §FR-2]"

   **场景分类与覆盖**（需求质量焦点）：
   - 检查是否存在需求：主要、交替、异常/错误、恢复、非功能场景
   - 对于每个场景类，问："[场景类型]需求是否完整、清晰且一致？"
   - 如果场景类缺失："是[场景类型]需求有意排除还是缺失？[间隙]"
   - 当状态变异发生时包括弹性/回滚："是否为迁移失败定义了回滚需求？[间隙]"

   **可追溯性需求**：
   - 最低：≥80%的项目必须包括至少一个可追溯性引用
   - 每个项目应该引用：规范章节 `[规范 §X.Y]`，或使用标记：`[间隙]`、`[模糊性]`、`[冲突]`、`[假设]`
   - 如果不存在ID系统："是否建立了需求和验收标准ID方案？[可追溯性]"

   **解决并发布问题**（需求质量问题）：
   询问关于需求本身的问题：
   - 模糊性："是否用特定指标量化了术语'快速'？[模糊性，规范 §NFR-1]"
   - 冲突："§FR-10和§FR-10a之间的导航需求是否冲突？[冲突]"
   - 假设："是否验证了'总是可用的播客API'的假设？[假设]"
   - 依赖："是否记录了外部播客API需求？[依赖，间隙]"
   - 缺失定义："是否用可衡量标准定义了'视觉层次'？[间隙]"

   **内容整合**：
   - 软上限：如果原始候选项目> 40，按风险/影响优先
   - 合并近重复，检查相同需求方面
   - 如果>5个低影响边界情况，创建一个项目："边界情况X、Y、Z的需求是否在需求中处理？[覆盖]"

   **🚫 绝对禁止** - 这些使其成为实施测试，而不是需求测试：
   - ❌ 任何以"验证"、"测试"、"确认"、"检查" + 实施行为开始的项目
   - ❌ 对代码执行、用户操作、系统行为的引用
   - ❌ "正确显示"、"正常工作"、"按预期运行"
   - ❌ "点击"、"导航"、"渲染"、"加载"、"执行"
   - ❌ 测试用例、测试计划、QA程序
   - ❌ 实施细节（框架、API、算法）

   **✅ 所需模式** - 这些测试需求质量：
   - ✅ "是否为[场景]定义/指定/记录了[需求类型]？"
   - ✅ "是否用特定标准量化/澄清了[模糊术语]？"
   - ✅ "[章节A]和[章节B]之间的需求是否一致？"
   - ✅ "是否可以客观地衡量/验证[需求]？"
   - ✅ "是否在需求中处理了[边界情况/场景]？"
   - ✅ "规范是否定义[缺失方面]？"

6. **结构参考**：遵循 `.specify/templates/checklist-template.md` 中的规范模板以获取标题、元部分、类别标题和ID格式。如果模板不可用，使用：H1标题、目的/创建元行、`##`类别部分包含 `- [ ] CHK### <需求项目>` 行，从CHK001开始的全局递增ID。

7. **报告**：输出检查清单文件的完整路径、项目数，并总结运行是创建了新文件还是追加到现有文件。总结：
   - 选择的焦点区域
   - 深度级别
   - 行为者/时机
   - 融合的任何明确用户指定的必需项目

**重要**：每次 `/speckit.checklist` 命令调用使用简短、描述性的检查清单文件名，并创建新文件或追加到现有文件。这允许：

- 多个不同类型的检查清单（例如，`ux.md`、`test.md`、`security.md`）
- 简单、可记忆的文件名，指示检查清单目的
- 在 `checklists/` 文件夹中轻松识别和导航

为了避免混乱，使用描述性类型并在完成后清理过时的检查清单。

## 示例检查清单类型和示例项目

**UX需求质量**：`ux.md`

示例项目（测试需求，而非实施）：

- "是否为所有卡片类型定义了视觉层次需求？[清晰度，规范 §FR-1]"
- "是否明确指定了UI元素的数量和定位？[完整性，规范 §FR-1]"
- "是否一致地定义了交互状态需求（悬停、焦点、活动）？[一致性]"
- "是否为所有交互元素指定了无障碍需求？[覆盖，间隙]"
- "是否定义了图像加载失败时的回退行为？[边界情况，间隙]"
- "是否可以客观衡量'突出显示'？[可衡量性，规范 §FR-4]"

**API需求质量**：`api.md`

示例项目：

- "是否为所有失败场景指定了错误响应格式？[完整性]"
- "是否用特定阈值量化了速率限制需求？[清晰度]"
- "是否在所有端点间一致地定义了认证需求？[一致性]"
- "是否为外部依赖定义了重试/超时需求？[覆盖，间隙]"
- "是否在需求中记录了版本控制策略？[间隙]"

**性能需求质量**：`performance.md`

示例项目：

- "是否用特定指标量化了性能需求？[清晰度]"
- "是否为所有关键用户旅程定义了性能目标？[覆盖]"
- "是否指定了不同负载条件下的性能需求？[完整性]"
- "是否可以客观衡量性能需求？[可衡量性]"
- "是否为高负载场景定义了降级需求？[边界情况，间隙]"

**安全需求质量**：`security.md`

示例项目：

- "是否为所有受保护资源指定了认证需求？[覆盖]"
- "是否为敏感信息定义了数据保护需求？[完整性]"
- "是否记录了威胁模型且需求与之对齐？[可追溯性]"
- "需求是否与合规义务一致？[一致性]"
- "是否定义了安全失败/违规响应需求？[间隙，异常流程]"

## 反例：不要做什么

**❌ 错误 - 这些测试实施，而非需求**：

```markdown
- [ ] CHK001 - 验证落地页显示3个剧集卡片 [规范 §FR-001]
- [ ] CHK002 - 测试桌面上的悬停状态正确工作 [规范 §FR-003]
- [ ] CHK003 - 确认徽标点击导航到主页 [规范 §FR-010]
- [ ] CHK004 - 检查相关剧集部分显示3-5个项目 [规范 §FR-005]

**✅ 正确 - 这些测试需求质量**：

```markdown
- [ ] CHK001 - 是否明确指定了特色剧集的数量和布局？[完整性，规范 §FR-001]
- [ ] CHK002 - 是否在所有交互元素间一致地定义了悬停状态需求？[一致性，规范 §FR-003]
- [ ] CHK003 - 所有可点击品牌元素的导航需求是否清晰？[清晰度，规范 §FR-010]
- [ ] CHK004 - 是否记录了相关剧集的选择标准？[间隙，规范 §FR-005]
- [ ] CHK005 - 是否为异步剧集数据定义了加载状态？[间隙]
- [ ] CHK006 - 是否可以客观衡量"视觉层次"需求？[可衡量性，规范 §FR-001]

**关键区别**：

- 错误：测试系统是否正确工作
- 正确：测试需求是否写得正确
- 错误：行为验证
- 正确：需求质量验证
- 错误："它做X吗？"
- 正确："是否清晰指定了X？"

执行流程：

运行 check-prerequisites.sh --json
    ↓
澄清意图（动态）- 最多3个上下文问题
    ├─ 从用户措辞+spec/plan/tasks提取信号
    ├─ 生成最多4个候选关注区域
    ├─ 识别可能的受众和时机
    └─ 检测缺失维度
    ↓
理解用户请求
    ├─ 推导清单主题
    ├─ 合并明确的必需项
    ├─ 映射焦点选择到类别脚手架
    └─ 从spec/plan/tasks推断缺失上下文
    ↓
加载功能上下文（渐进式披露）
    ├─ 仅加载与活动焦点区域相关的部分
    ├─ 优先总结长章节
    └─ 使用渐进式披露
    ↓
生成检查清单：
    ├─ 创建 FEATURE_DIR/checklists/ 目录
    ├─ 生成唯一文件名（domain.md）
    ├─ 文件不存在：创建新文件，从CHK001开始
    ├─ 文件存在：追加到现有文件
    └─ 永不删除或替换现有内容
    ↓
报告：文件路径、项目数、焦点区域

3.9 speckit.taskstoissues - 转换为GitHub Issues

文件位置：.claude/commands/speckit.taskstoissues.md

使用时机：在 /speckit.tasks 之后、/speckit.implement 之前使用

重要：必须在实施之前创建 Issues，否则任务完成后创建 Issues 就没有意义了。

使用场景：

✅ 团队协作：将任务分配给不同的团队成员
✅ 项目管理：在GitHub Projects/Kanban Board中管理任务
✅ 进度跟踪：利用GitHub的Issue状态、标签、里程碑等功能
✅ CI/CD集成：工作流与GitHub Issues集成（如关闭PR时自动关闭相关Issues）

不适用场景：

❌ 个人项目：直接使用 /speckit.implement 执行即可
❌ 不使用GitHub：此命令仅支持GitHub
❌ 任务已在其他工具管理：如Jira、Trello、Notion等
❌ 快速原型开发：直接实施更高效

提示词模板（中文版）：

---
description: 根据可用的设计产物将现有任务转换为可操作的、依赖有序的GitHub问题
tools: ['github/github-mcp-server/issue_write']
---

## 用户输入
$ARGUMENTS

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

## 执行大纲

1. 从仓库根目录运行 `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` 并为 FEATURE_DIR 和 AVAILABLE_DOCS 列表解析JSON。所有路径必须是绝对的。对于单引号参数如 "I'm Groot"，使用转义语法：例如 'I'\''m Groot'（或尽可能使用双引号："I'm Groot"）。
2. 从执行的脚本中，提取**任务**的路径。
3. 通过运行获取Git远程：

```bash
git config --get remote.origin.url

[!注意]
只有在远程是GitHub URL时才继续到下一步

对于列表中的每个任务，使用GitHub MCP服务器在代表Git远程的仓库中创建新问题。

[!注意]
绝不在与远程URL不匹配的仓库中创建问题

执行流程：

运行 check-prerequisites.sh --json --require-tasks --include-tasks
    ↓
获取Git远程URL：
    git config --get remote.origin.url
    ↓
验证是GitHub URL
    ├─ 如果是GitHub URL：继续
    └─ 如果不是：停止并警告
    ↓
为每个任务创建GitHub Issue
    ├─ 使用GitHub MCP服务器
    ├─ 仅在匹配的远程仓库创建
    └─ 永不在其他仓库创建

四、辅助脚本

4.1 `common.sh` - 通用函数库

文件位置：.specify/scripts/bash/common.sh

核心函数：

函数	功能	返回值
`get_repo_root()`	获取仓库根目录	仓库根目录绝对路径
`get_current_branch()`	获取当前分支	分支名称
`has_git()`	检查是否有Git	true/false
`check_feature_branch()`	验证功能分支格式	0=通过, 1=失败
`get_feature_dir()`	获取功能目录	specs目录路径
`find_feature_dir_by_prefix()`	按前缀查找功能目录	功能目录路径
`get_feature_paths()`	获取所有功能路径	JSON格式的路径变量

4.2 `create-new-feature.sh` - 创建新功能

文件位置：.specify/scripts/bash/create-new-feature.sh

参数：

create-new-feature.sh [选项] <功能描述>

选项:
  --json              输出JSON格式
  --short-name <名称> 提供自定义短名称（2-4词）
  --number N          手动指定分支编号
  --help, -h          显示帮助信息

4.3 `setup-plan.sh` - 设置实施计划

文件位置：.specify/scripts/bash/setup-plan.sh

参数：

setup-plan.sh [选项]

选项:
  --json    输出JSON格式
  --help    显示帮助信息

4.4 `check-prerequisites.sh` - 检查先决条件

文件位置：.specify/scripts/bash/check-prerequisites.sh

参数：

check-prerequisites.sh [选项]

选项:
  --json                  输出JSON格式
  --paths-only            仅输出路径信息
  --require-tasks         要求tasks.md存在
  --include-tasks         在输出中包含tasks路径
  --help                  显示帮助信息

五、工作流程图

5.1 完整开发流程

┌─────────────────────────────────────────────────────────────────────────┐
│                         Spec-Kit 完整开发流程                            │
└─────────────────────────────────────────────────────────────────────────┘

1. 项目初始化（一次性）
   ┌─────────────────────────────────────┐
   │ specify init . --ai claude          │
   └──────────────┬──────────────────────┘
                  ↓
   创建 .specify/ 目录结构和模板文件

2. 建立项目原则（可选，推荐首次进行）
   ┌─────────────────────────────────────┐
   │ /speckit.constitution               │
   └──────────────┬──────────────────────┘
                  ↓
   生成/更新 .specify/memory/constitution.md

3. 创建功能规范
   ┌─────────────────────────────────────┐
   │ /speckit.specify                    │
   └──────────────┬──────────────────────┘
                  ↓
   调用 create-new-feature.sh → 创建分支和目录
                  ↓
   Claude Code 填充 spec.md
                  ↓
   创建质量检查清单：checklists/requirements.md

4. 澄清规范细节（可选，推荐）
   ┌─────────────────────────────────────┐
   │ /speckit.clarify                    │
   └──────────────┬──────────────────────┘
                  ↓
   结构化模糊度扫描 → 顺序提问 → 集成到spec

5. 生成技术计划
   ┌─────────────────────────────────────┐
   │ /speckit.plan                       │
   └──────────────┬──────────────────────┘
                  ↓
   填充 plan.md → 阶段0研究 → 阶段1设计

6. 生成任务列表
   ┌─────────────────────────────────────┐
   │ /speckit.tasks                      │
   └──────────────┬──────────────────────┘
                  ↓
   加载设计文档 → 生成按用户故事组织的任务

7. 一致性分析（可选，推荐）
   ┌─────────────────────────────────────┐
   │ /speckit.analyze                    │
   └──────────────┬──────────────────────┘
                  ↓
   构建语义模型 → 检测通过 → 生成分析报告

8. 生成质量检查清单（可选）
   ┌─────────────────────────────────────┐
   │ /speckit.checklist "主题"            │
   └──────────────┬──────────────────────┘
                  ↓
   生成"需求的单元测试"检查清单

9. 转换为GitHub Issues（可选，团队协作）
   ┌─────────────────────────────────────┐
   │ /speckit.taskstoissues              │
   └──────────────┬──────────────────────┘
                  ↓
   为每个任务创建GitHub Issue
   ↓
   [团队协作模式] 分配Issues给团队成员 → 团队成员认领并实施
   [个人开发模式] 跳过此步骤，直接进入下一步

10. 执行实施
    ┌─────────────────────────────────────┐
    │ /speckit.implement                  │
    └──────────────┬──────────────────────┘
                   ↓
    按阶段执行：Setup → Foundational → User Stories → Polish

六、最佳实践

6.1 命令使用顺序

推荐顺序（完整流程 - 团队协作）：

1. /speckit.constitution（首次）
2. /speckit.specify
3. /speckit.clarify（可选但推荐）
4. /speckit.plan
5. /speckit.tasks
6. /speckit.analyze（推荐）
7. /speckit.checklist（可选）
8. /speckit.taskstoissues（可选，团队协作时使用）
   ↓ [分配Issues给团队成员]
9. /speckit.implement（或团队成员手动实施）

快速流程（个人开发 - 跳过可选步骤）：

1. /speckit.specify
2. /speckit.plan
3. /speckit.tasks
4. /speckit.implement（直接执行，无需创建Issues）

重要说明：

/speckit.taskstoissues 必须在 /speckit.implement 之前使用
如果任务已经完成，再创建 Issues 就没有意义了
个人开发可以跳过 taskstoissues，直接执行 implement

6.2 两种工作模式对比

模式1：团队协作模式（使用 taskstoissues）

适用场景：多人团队、需要任务分配和进度跟踪

# ========== 规划阶段（由技术负责人执行） ==========
/speckit.specify
/speckit.plan
/speckit.tasks
/speckit.taskstoissues  # ← 关键：创建 Issues
    ↓
GitHub Issues 创建完成（T001-T042）
    ↓
# ========== 任务分配阶段 ==========
在 GitHub 上为团队成员分配 Issues：
- 开发者A: Issue #1-#10 (T001-T010)
- 开发者B: Issue #11-#20 (T011-T020)
- 开发者C: Issue #21-#30 (T021-T030)
    ↓
# ========== 实施阶段 ==========
团队成员认领 Issues 后可以选择：
方式1: 手动实施（推荐）
  - 根据 Issue 描述手动实施
  - 完成后关闭 Issue

方式2: 使用 /speckit.implement
  - 每个开发者对自己负责的 Issues 运行 /speckit.implement
  - 实施完成后 Issues 自动关闭

优势：

✅ 任务可视化：所有任务在 GitHub Issues 中一目了然
✅ 责任明确：每个 Issue 都有明确的负责人
✅ 进度可跟踪：通过 Issue 状态了解整体进度
✅ 协作无障碍：团队成员可以讨论、评论、审核代码

模式2：个人开发模式（不使用 taskstoissues）

适用场景：个人项目、快速原型、不使用 GitHub 项目管理

# ========== 完整开发流程（单人执行） ==========
/speckit.specify
/speckit.plan
/speckit.tasks
# 跳过 taskstoissues
/speckit.implement  # ← 直接执行所有任务

优势：

✅ 流程简洁：一步到位，无需中间环节
✅ 快速迭代：适合探索性开发和原型验证
✅ 无额外开销：不需要维护 Issues

6.3 taskstoissues 使用时机决策图

                    是否需要团队协作？
                         │
            ┌────────────┴────────────┐
            │                         │
           是                         否
            │                         │
    是否使用 GitHub？            直接使用 /speckit.implement
            │                         │
       ┌────┴────┐                     │
       │         │                     │
      是        否                    │
       │         │                     │
使用 taskstoissues    ┌───────────┘   │
       │         │                   │
       ↓         ↓                   │
  创建 Issues    使用其他   ←───────────┘
  分配给团队    项目管理工具

6.4 taskstoissues 常见问题

问题	答案
Q: 可以在 implement 之后使用吗？	❌ 不可以。任务完成后创建 Issues 没有意义
Q: 可以重复创建 Issues 吗？	⚠️ 可以，但会创建重复的 Issues，需要手动清理
Q: 如何避免重复创建？	检查 GitHub 仓库是否已有对应 Issues
Q: Issue 包含哪些信息？	任务ID、描述、文件路径、依赖关系
Q: 可以只创建部分任务的 Issues 吗？	✅ 可以，手动编辑 tasks.md 只保留需要创建的任务

6.5 规范编写原则

DO（推荐）：

✅ 关注用户价值和业务需求
✅ 使用可衡量的成功标准
✅ 编写独立的用户故事
✅ 定义明确的验收标准
✅ 识别边界情况

DON'T（避免）：

❌ 包含实现细节（语言、框架、API）
❌ 使用技术术语
❌ 描述"如何做"
❌ 编写模糊的需求
❌ 忽略非功能需求

6.6 任务编写原则（补充）

格式要求：

严格遵循：- [ ] T### [P?] [US?] 带文件路径的描述
包含完整文件路径
标记并行机会 [P]
按用户故事组织

组织原则：

Setup → Foundational → User Stories → Polish
每个用户故事独立可测试
测试任务在实现任务之前（TDD）
清晰的依赖关系

七、重要注意事项

7.1 实施前建议清除上下文

问题：在 /speckit.implement 之前上下文占用往往超过50%，导致AI处理能力下降。

建议操作：

# ========== 规划阶段 ==========
/speckit.specify "功能描述"
/speckit.plan
/speckit.tasks

# ========== 清除上下文 ==========
/clear

# ========== 实施阶段 ==========
/speckit.implement

理由：

规划阶段完成后，所有信息已写入文档
清除上下文后，AI从文档中重新读取信息
降低上下文占用（70% → 20-30%），提高实施质量

7.2 Constitution在实施阶段未被明确加载

Constitution.md 的使用阶段

阶段	是否使用	主要作用
`/speckit.constitution`	✅ 直接读取	创建/更新项目原则和开发准则
`/speckit.plan`	✅ 直接读取	Constitution Check - 验证计划是否符合项目原则
`/speckit.tasks`	⚠️ 间接引用	通过 plan.md 的 Constitution Check 结果引用
`/speckit.implement`	❌ 未明确加载	提示词中未列出 constitution.md

问题分析

根本原因：.claude/commands/speckit.implement.md 的提示词"加载实施上下文"部分未包含 constitution.md：

潜在影响

如果AI模型直接基于 tasks.md 和 plan.md 实施，而未加载，可能会忽略部分constitution.md中描述的项目原则。

八、附录

A. 文件路径速查

文件	路径
Constitution	`.specify/memory/constitution.md`
Spec模板	`.specify/templates/spec-template.md`
Plan模板	`.specify/templates/plan-template.md`
Tasks模板	`.specify/templates/tasks-template.md`
命令定义	`.claude/commands/speckit.*.md`
通用脚本	`.specify/scripts/bash/common.sh`
功能规范	`specs/###-feature/spec.md`
实施计划	`specs/###-feature/plan.md`
任务列表	`specs/###-feature/tasks.md`
检查清单	`specs/###-feature/checklists/*.md`

B. 命令速查

命令	用途	输入	输出
`/speckit.constitution`	创建项目原则	原则描述	constitution.md
`/speckit.specify`	创建功能规范	功能描述	spec.md + 新分支
`/speckit.clarify`	澄清规范细节	[自动]	spec.md更新
`/speckit.plan`	生成技术计划	技术栈描述	plan.md + 研究文档
`/speckit.tasks`	分解任务列表	[自动]	tasks.md
`/speckit.analyze`	一致性分析	[自动]	分析报告
`/speckit.checklist`	生成检查清单	主题	checklists/[theme].md
`/speckit.implement`	执行实施	[自动]	完整代码
`/speckit.taskstoissues`	转为Issues	[自动]	GitHub Issues

C. 环境变量速查

变量	作用	示例
`SPECIFY_FEATURE`	指定功能目录	`001-timestamp-converter`

九、文档版本信息

文档版本: 1.1.0
创建日期: 2026-03-09
最后更新: 2026-03-09
适用Spec-Kit版本: 最新
适用Claude Code版本: 最新