Spec Kit 项目实战手册：从立项到交付

Spec Kit 项目实战手册：从立项到交付 Spec Kit 项目实战手册：从立项到交付 Modified June 26 • 每个验收场景是否可测试。 • 异常路径是否包含权限、输入、网络、外部服务失败。 • 范围边界是否明确。 • 技术计划是否引用了 constitution 中的关键规则。 • 质量要求是否能转为测试任务。 checklist 提示词示例 Plain Text Copy $speckit checklist 请针对当前 spec 和 plan 生成需求质量检查清单。重点检查用户故事、验收标准、异常场景、权限边界、数据安全、测试覆盖和范围控制。 11. 阶段六：拆解 Tasks $speckit tasks 把 plan 拆成实现任务。好的 tasks 应该足够小，可以单独开发、测试和 review。 任务拆解建议遵循以下顺序： 1. 准备任务：依赖安装、配置、测试框架、目录结构。 2. 数据任务：模型、schema、类型定义、迁移脚本。 3. 核心逻辑任务：业务流程、命令处理、API 调用、状态转换。 4. 错误处理任务：权限错误、输入错误、网络错误、第三方失败。 5. 测试任务：单元测试、集成测试、回归测试、验收测试。 6. 文档任务：README、操作说明、变更记录、示例命令。 7. 验证任务：运行测试、人工验收、发布前检查。 tasks 提示词示例 Plain Text Copy $speckit tasks 请根据当前 plan 生成任务清单。每个任务必须可以独立完成，并标明依赖、涉及文件、测试要求和验收方式。优先把权限处理、失败恢复、文档写入和验证读取拆成单独任务。 任务质量标准： • 任务标题能直接说明要做什么。 • 任务描述包含输入、输出和完成条件。 • 每个核心任务都有测试要求。 • 任务之间的依赖关系清楚。 • 能按顺序交给 agent 实现。 12. 阶段七：一致性分析 $speckit analyze 用于检查 spec、plan、tasks 三者是否一致。完整项目中，建议在正式实现前运行。 重点检查： • spec 中的每个用户故事是否有对应任务。 • plan 中的每个技术决策是否有实现任务。 • tasks 中是否出现 spec 没有要求的扩展工作。 • 验收标准是否被测试任务覆盖。 • 权限、安全、日志、回滚等规则是否被遗漏。 analyze 提示词示例 Plain Text Copy $speckit analyze 请检查当前 spec、plan、tasks 的一致性。重点找出遗漏需求、过度扩展、验收标准未覆盖、测试缺口、安全规则缺口和任务依赖问题。 13. 阶段八：实现与验证 $speckit implement 进入代码实现阶段。实现时建议按任务顺序执行，每完成一组任务就运行对应测试，并记录结果。 实现阶段建议遵守： • 每次只处理一组相关任务。 • 修改共享模块前先阅读相关调用方。 • 优先使用项目已有模式和工具。 • 实现同时补测试，避免最后集中补。 • 遇到规格不清时回到 spec 或 clarify。 • 发现技术方案需要调整时更新 plan。 • 任务完成后更新 tasks 状态和验证结果。 implement 提示词示例 Plain Text Copy $speckit implement 请按 tasks.md 顺序实现。每完成一个任务，运行相关测试并记录结果。遇到任务与 spec 或 plan 冲突时先暂停实现，说明冲突点并给出建议调整。 完成定义： • 对应 tasks 全部完成。 • 测试通过，或失败原因已记录并得到处理方案。 • 用户可见行为满足验收标准。 • 文档和示例命令已更新。 • 遗留问题已经记录到下一轮任务。 14. 团队角色分工 完整项目使用 Spec Kit 时，建议明确角色，减少“所有人都能改规格，但没人负责维护”的问题。 • 产品负责人：负责用户目标、范围边界、验收标准。 • 技术负责人：负责 constitution、plan、架构决策、风险评估。 • 开发者：负责 tasks 实现、测试、代码 review 修复。 • 测试负责人：负责 checklist、验收场景、回归测试设计。 • AI 操作者：负责驱动 Codex 或其他 agent，维护 spec、plan、tasks 的同步。 • Reviewer：负责检查 agent 产物是否符合项目原则。 小团队可以一人承担多个角色，但每个产物仍应有明确负责人。 15. 推荐协作节奏 一个功能从提出到交付，可以使用下面的协作节奏。 1. 需求评审前：产品负责人提供背景、目标用户、业务目标。 2. 需求评审中：运行 $speckit specify 和 $speckit clarify，把模糊点记录下来。 3. 技术评审前：运行 $speckit plan，技术负责人补充架构和风险。 4. 开发前：运行 $speckit checklist、$speckit tasks、$speckit analyze。 5. 开发中：按 tasks 执行，每完成一组任务就运行测试。 6. 交付前：核对验收标准、测试结果、文档和变更记录。 7. 交付后：把遗留问题整理成下一轮 spec 或 tasks。 16. 完整项目示例：知识库发布助手 下面用“知识库发布助手”作为完整项目示例，展示如何串联 Spec Kit 全流程。 项目目标：用户输入主题、目标知识库和资料来源，系统自动生成飞书文档，并发布到指定知识库。 constitution 重点： • 所有飞书写操作默认使用 user 身份。 • 目标知识库必须由用户确认或精确匹配。 • 写入文档前必须确认标题、space id、node token。 • 失败时必须返回失败阶段和可重试建议。 • 禁止在日志中输出密钥和 accessToken。 spec 重点： • 用户可以输入主题、目标知识库、资料来源和风格要求。 • 系统生成结构化文档，至少包含摘要、背景、正文、结论、来源。 • 系统返回 wiki 链接、doc token、node token、写入状态。 • 权限不足时输出授权指引。 • 目标知识库匹配到多个候选时等待用户确认。 plan 重点： • 用 lark cli wiki +space list as user 查询知识库。 • 用 lark cli wiki +node create 创建 docx 节点。 • 用 lark cli docs +update api version v2 写入正文。 • 用 lark cli docs +fetch scope outline 验证目录。 • 权限错误根据 user 或 bot 身份分开处理。 tasks 示例： 1. 实现知识库名称解析和候选确认。 2. 实现 wiki 节点创建。 3. 实现长文档分段写入。 4. 实现目录验证和链接返回。 5. 实现权限不足提示。 6. 补充成功路径和失败路径测试。 17. 质量门禁 完整项目建议设置以下门禁。任何门禁失败，都应回到对应产物修正。 • 规格门禁：用户故事、范围、验收标准、异常路径完整。 • 技术门禁：技术方案遵守 constitution，核心风险有处理策略。 • 任务门禁：每个任务可执行、可测试、可 review。 • 安全门禁：权限、密钥、日志、敏感数据处理清楚。 • 测试门禁：测试覆盖主要成功路径和失败路径。 • 交付门禁：用户可见结果符合验收标准，文档和示例已更新。 18. 常见问题 18.1 什么时候需要完整流程？ 涉及多人协作、长期维护、权限安全、复杂外部接口、真实用户使用的功能，建议使用完整流程。一次性脚本可以采用轻量流程。 18.2 规格写得太长怎么办？ 先保持 spec 清晰，再把技术细节放进 plan，把执行细节放进 tasks。规格太长时，可以按 feature 拆成多个 spec。 18.3 agent 生成的 plan 不可靠怎么办？ 让技术负责人 review plan，并补充架构约束、现有代码路径、依赖限制和测试策略。必要时重新运行 $speckit plan。 18.4 tasks 太粗怎么办？ 要求 agent 按文件、模块、测试和依赖关系重新拆分。每个任务最好能在一个小范围内完成。 18.5 实现中发现需求变化怎么办？ 先更新 spec，再调整 plan 和 tasks。避免只改代码，让后续 agent 读取旧规格。 19. 完整项目检查清单 已安装 Spec Kit，并确认 specify version 可运行。 已选择 agent 集成，例如 Codex。 已完成 constitution.md，并写入团队核心规则。 每个重要功能都有独立 spec。 spec 中包含用户故事、功能要求、异常场景和验收标准。 已运行 clarify，并把答案写回规格。 plan 中包含技术栈、模块设计、接口、数据、安全和测试策略。 tasks 已拆到可独立实现和测试的粒度。 已运行 analyze，确认产物一致。 实现阶段按任务执行，并记录测试结果。 交付前完成文档、示例、变更记录和遗留问题整理。 20. 参考资料 • Spec Kit 官方文档 • Spec Kit Quick Start • Spec Kit Installation • GitHub Spec Kit 开源仓库 • GitHub 官方博客：Spec driven development with AI Spec Kit 官方文档 Spec Kit Quick Start Spec Kit Installation GitHub Spec Kit 开源仓库 GitHub 官方博客：Spec driven development with AI • 每个验收场景是否可测试。 • 异常路径是否包含权限、输入、网络、外部服务失败。 • 范围边界是否明确。 • 技术计划是否引用了 constitution 中的关键规则。 • 质量要求是否能转为测试任务。 11. 阶段六：拆解 Tasks $speckit tasks 把 plan 拆成实现任务。好的 tasks 应该足够小，可以单独开发、测试和 review。 任务拆解建议遵循以下顺序： 1. 准备任务：依赖安装、配置、测试框架、目录结构。 2. 数据任务：模型、schema、类型定义、迁移脚本。 3. 核心逻辑任务：业务流程、命令处理、API 调用、状态转换。 4. 错误处理任务：权限错误、输入错误、网络错误、第三方失败。 5. 测试任务：单元测试、集成测试、回归测试、验收测试。 6. 文档任务：README、操作说明、变更记录、示例命令。 7. 验证任务：运行测试、人工验收、发布前检查。 任务质量标准： • 任务标题能直接说明要做什么。 • 任务描述包含输入、输出和完成条件。 • 每个核心任务都有测试要求。 • 任务之间的依赖关系清楚。 • 能按顺序交给 agent 实现。 12. 阶段七：一致性分析 $speckit analyze 用于检查 spec、plan、tasks 三者是否一致。完整项目中，建议在正式实现前运行。 重点检查： • spec 中的每个用户故事是否有对应任务。 • plan 中的每个技术决策是否有实现任务。 • tasks 中是否出现 spec 没有要求的扩展工作。 • 验收标准是否被测试任务覆盖。 • 权限、安全、日志、回滚等规则是否被遗漏。 13. 阶段八：实现与验证 $speckit implement 进入代码实现阶段。实现时建议按任务顺序执行，每完成一组任务就运行对应测试，并记录结果。 实现阶段建议遵守： • 每次只处理一组相关任务。 • 修改共享模块前先阅读相关调用方。 • 优先使用项目已有模式和工具。 • 实现同时补测试，避免最后集中补。 • 遇到规格不清时回到 spec 或 clarify。 • 发现技术方案需要调整时更新 plan。 • 任务完成后更新 tasks 状态和验证结果。 完成定义： • 对应 tasks 全部完成。 • 测试通过，或失败原因已记录并得到处理方案。 • 用户可见行为满足验收标准。 • 文档和示例命令已更新。 • 遗留问题已经记录到下一轮任务。 14. 团队角色分工 完整项目使用 Spec Kit 时，建议明确角色，减少“所有人都能改规格，但没人负责维护”的问题。 • 产品负责人：负责用户目标、范围边界、验收标准。 • 技术负责人：负责 constitution、plan、架构决策、风险评估。 • 开发者：负责 tasks 实现、测试、代码 review 修复。 • 测试负责人：负责 checklist、验收场景、回归测试设计。 • AI 操作者：负责驱动 Codex 或其他 agent，维护 spec、plan、tasks 的同步。 • Reviewer：负责检查 agent 产物是否符合项目原则。 小团队可以一人承担多个角色，但每个产物仍应有明确负责人。 15. 推荐协作节奏 一个功能从提出到交付，可以使用下面的协作节奏。 1. 需求评审前：产品负责人提供背景、目标用户、业务目标。 2. 需求评审中：运行 $speckit specify 和 $speckit clarify，把模糊点记录下来。 3. 技术评审前：运行 $speckit plan，技术负责人补充架构和风险。 4. 开发前：运行 $speckit checklist、$speckit tasks、$speckit analyze。 5. 开发中：按 tasks 执行，每完成一组任务就运行测试。 6. 交付前：核对验收标准、测试结果、文档和变更记录。 7. 交付后：把遗留问题整理成下一轮 spec 或 tasks。 16. 完整项目示例：知识库发布助手 下面用“知识库发布助手”作为完整项目示例，展示如何串联 Spec Kit 全流程。 项目目标：用户输入主题、目标知识库和资料来源，系统自动生成飞书文档，并发布到指定知识库。 constitution 重点： • 所有飞书写操作默认使用 user 身份。 • 目标知识库必须由用户确认或精确匹配。 • 写入文档前必须确认标题、space id、node token。 • 失败时必须返回失败阶段和可重试建议。 • 禁止在日志中输出密钥和 accessToken。 spec 重点： • 用户可以输入主题、目标知识库、资料来源和风格要求。 • 系统生成结构化文档，至少包含摘要、背景、正文、结论、来源。 • 系统返回 wiki 链接、doc token、node token、写入状态。 • 权限不足时输出授权指引。 • 目标知识库匹配到多个候选时等待用户确认。 plan 重点： • 用 lark cli wiki +space list as user 查询知识库。 • 用 lark cli wiki +node create 创建 docx 节点。 • 用 lark cli docs +update api version v2 写入正文。 • 用 lark cli docs +fetch scope outline 验证目录。 • 权限错误根据 user 或 bot 身份分开处理。 tasks 示例： 1. 实现知识库名称解析和候选确认。 2. 实现 wiki 节点创建。 3. 实现长文档分段写入。 4. 实现目录验证和链接返回。 5. 实现权限不足提示。 6. 补充成功路径和失败路径测试。 17. 质量门禁 完整项目建议设置以下门禁。任何门禁失败，都应回到对应产物修正。 • 规格门禁：用户故事、范围、验收标准、异常路径完整。 • 技术门禁：技术方案遵守 constitution，核心风险有处理策略。 • 任务门禁：每个任务可执行、可测试、可 review。 • 安全门禁：权限、密钥、日志、敏感数据处理清楚。 • 测试门禁：测试覆盖主要成功路径和失败路径。 • 交付门禁：用户可见结果符合验收标准，文档和示例已更新。 18. 常见问题 18.1 什么时候需要完整流程？ 涉及多人协作、长期维护、权限安全、复杂外部接口、真实用户使用的功能，建议使用完整流程。一次性脚本可以采用轻量流程。 18.2 规格写得太长怎么办？ 先保持 spec 清晰，再把技术细节放进 plan，把执行细节放进 tasks。规格太长时，可以按 feature 拆成多个 spec。 18.3 agent 生成的 plan 不可靠怎么办？ 让技术负责人 review plan，并补充架构约束、现有代码路径、依赖限制和测试策略。必要时重新运行 $speckit plan。 18.4 tasks 太粗怎么办？ 要求 agent 按文件、模块、测试和依赖关系重新拆分。每个任务最好能在一个小范围内完成。 18.5 实现中发现需求变化怎么办？ 先更新 spec，再调整 plan 和 tasks。避免只改代码，让后续 agent 读取旧规格。 19. 完整项目检查清单 已安装 Spec Kit，并确认 specify version 可运行。 已选择 agent 集成，例如 Codex。 已完成 constitution.md，并写入团队核心规则。 每个重要功能都有独立 spec。 spec 中包含用户故事、功能要求、异常场景和验收标准。 已运行 clarify，并把答案写回规格。 plan 中包含技术栈、模块设计、接口、数据、安全和测试策略。 tasks 已拆到可独立实现和测试的粒度。 已运行 analyze，确认产物一致。 实现阶段按任务执行，并记录测试结果。 交付前完成文档、示例、变更记录和遗留问题整理。 20. 参考资料 • Spec Kit 官方文档 Spec Kit 官方文档 • Spec Kit Quick Start Spec Kit Quick Start • Spec Kit Installation Spec Kit Installation • GitHub Spec Kit 开源仓库 GitHub Spec Kit 开源仓库 • GitHub 官方博客：Spec driven development with AI GitHub 官方博客：Spec driven development with AI 版本基准：Spec Kit v0.11.8。整理日期：2026年6月26日。 这是一份面向完整项目的 Spec Kit 使用手册，适合产品负责人、工程负责人、开发者、测试同学和使用 AI 编码 agent 的项目成员共同参考。手册目标是让一个项目从立项、需求澄清、技术计划、任务拆解、实现、验证到交付，都有清晰的规格和产物链。 1. 手册定位 Spec Kit 的核心价值是把 AI 编码流程规格化。它先沉淀需求、原则和验收标准，再生成技术计划和任务清单，最后让 Codex、Claude Code、GitHub Copilot、Gemini CLI 等 agent 按任务实现。 完整项目使用 Spec Kit 时，要关注三件事： • 统一原则：先写 constitution，让团队知道什么规则必须遵守。 • 统一规格：用 spec 描述用户目标、业务规则、验收条件和边界。 • 统一执行：用 plan 和 tasks 把需求整理为可实现、可测试、可 review 的任务。 2. 完整项目的产物链 Spec Kit 项目会围绕以下产物展开。每个产物都承担不同职责，避免需求、方案和实现混在一起。 • constitution.md：项目原则，定义工程纪律、测试要求、安全约束、交付标准。 • spec.md：功能规格，描述用户故事、业务规则、验收场景、范围边界。 • plan.md：技术计划，描述技术栈、架构方案、数据模型、接口、风险。 • tasks.md：任务清单，把计划拆成可执行的小任务。 • checklist：规格质量检查，确认需求是否清晰、完整、一致。 • analyze 结果：一致性检查，确认 spec、plan、tasks 之间没有明显断裂。 • 实现代码与测试结果：最终交付内容，必须能回溯到任务和验收标准。 3. 标准项目阶段 1. 项目启动：安装 Spec Kit，初始化仓库，选择 agent 集成。 2. 原则制定：用 $speckit constitution 建立项目约束。 3. 功能规格：用 $speckit specify 写清楚要实现的能力。 4. 需求澄清：用 $speckit clarify 处理模糊点。 5. 技术计划：用 $speckit plan 生成技术方案。 6. 质量检查：用 $speckit checklist 检查规格质量。 7. 任务拆解：用 $speckit tasks 生成实现任务。 8. 一致性分析：用 $speckit analyze 检查产物是否对齐。 9. 实现与验证：用 $speckit implement 执行任务，并运行测试。 10. 交付复盘：记录变更、测试结果、遗留问题和下一轮规格。 4. 建议目录结构 初始化后，项目会拥有一组 Spec Kit 相关目录。完整项目建议保留这些产物，并纳入日常 review。 5. 项目启动：安装和初始化 完整项目建议使用固定版本安装，保证团队成员和 CI 环境能够复现。 新项目可以直接初始化；已有项目建议先确认当前目录是否有 AGENTS.md、.agents、.specify，再执行初始化。 初始化完成后，在 Codex 中使用 $speckit constitution、$speckit specify 等 skills。如果当前会话看不到这些 skills，重新打开当前目录的 Codex 会话。 6. 阶段一：建立项目 Constitution constitution.md 是完整项目的工程宪法。它应在第一天完成，并随着团队共识变化持续维护。它的作用是让所有 agent 和成员知道项目的基本规则。 推荐写入以下内容： • 产品原则：服务对象、核心价值、体验底线。 • 工程原则：代码结构、模块边界、命名规则、依赖选择。 • 测试原则：单元测试、集成测试、端到端测试、回归测试要求。 • 安全原则：权限、密钥、用户数据、日志脱敏、写操作确认。 • 交付原则：完成定义、文档要求、验收流程、发布记录。 • Agent 使用原则：agent 可自动处理的范围，需要人工确认的范围。 验收标准： • constitution 明确了项目服务对象和核心目标。 • constitution 写明了测试、权限、安全和交付要求。 • constitution 中的规则能被后续 spec、plan 和 tasks 引用。 • 团队成员知道哪些规则需要人工确认。 7. 阶段二：创建 Feature Spec $speckit specify 用于创建功能规格。完整项目中，每个重要功能都应拥有独立 spec。spec 阶段聚焦“要实现什么”和“用户如何验收”，技术方案留到 plan 阶段。 一个合格 spec 应包含： • 功能目标：这项功能解决什么问题。 • 目标用户：谁会使用，使用场景是什么。 • 用户故事：按用户动作和业务目标描述行为。 • 功能要求：系统必须支持的能力。 • 质量要求：性能、安全、可靠性、可观测性等要求。 • 边界范围：本轮包含什么，暂缓什么。 • 验收场景：用 Given、When、Then 或类似结构描述可测试行为。 写 spec 的要点： • 优先写用户行为，避免一开始写代码结构。 • 每条要求尽量可测试。 • 把异常场景写进规格，例如权限不足、目标不存在、网络失败、输入为空。 • 明确输出字段和用户能看到的结果。 • 明确本轮暂缓内容，减少 agent 扩展范围。 8. 阶段三：澄清需求 $speckit clarify 用于处理模糊需求。完整项目中，这一步能显著减少返工。建议在进入 plan 前执行一次。 常见澄清方向： • 身份与权限：使用 user 身份还是 bot 身份。 • 数据来源：用户输入、文件、数据库、第三方 API、已有文档。 • 输出格式：页面、接口、文档、表格、日志、消息通知。 • 失败策略：自动重试、回滚、保留草稿、等待人工确认。 • 性能边界：数据量、并发、响应时间、超时策略。 • 合规与隐私：敏感信息处理、日志脱敏、访问控制。 澄清结果处理方式： • 每个回答都应写回 spec 的 Clarifications 区域。 • 影响技术方案的回答，需要在 plan 中体现。 • 影响任务拆解的回答，需要在 tasks 中体现。 • 无法立即决定的问题，可以记录为风险或开放问题。 9. 阶段四：生成技术计划 $speckit plan 负责把 spec 转为可实现的技术方案。plan 阶段开始讨论技术栈、架构、数据结构、接口、迁移、测试和风险。 完整项目的 plan 建议包含： • 技术栈选择：语言、框架、数据库、外部服务、CLI 或 SDK。 • 系统结构：模块划分、边界、输入输出、依赖关系。 • 数据模型：核心实体、字段、状态、生命周期。 • 接口设计：命令参数、API 请求、返回结构、错误码。 • 安全策略：认证、授权、密钥、日志、数据保留。 • 测试策略：测试层级、测试数据、mock 策略、验收测试。 • 迁移策略：已有系统如何兼容，旧数据如何处理。 • 风险与替代方案：高风险点、备选路径、人工确认点。 技术计划验收标准： • 每个功能要求都有对应的技术处理方式。 • 外部依赖和权限要求清楚。 • 数据模型和接口字段可直接交给开发执行。 • 错误处理和测试策略完整覆盖主要风险。 10. 阶段五：生成 Checklist $speckit checklist 用于检查规格质量。完整项目中，checklist 可以作为需求评审入口。 推荐检查项： • 目标用户是否清楚。 • 主要用户路径是否完整。