Speckit 和 Claude 使用指南

Speckit 与 Claude：协同驱动 AI 全链路研发

一、Speckit 与 Claude 关系概述

Speckit 与 Claude Code 在企业内的 AI 全链路研发试点中紧密协作，形成以规范驱动的开发模式，提升开发效率、保障代码质量并促进产研协同。

1. 协作开发模式 ：二者结合，以 AI 为主、人作为辅助进行开发。
2. Git 分支管理 ：Speckit 运行中的 short - name 短名称即 git 分支名称。Claude 会依 git 初始化及分支命名情况操作，若 git 未初始化，自动初始化并切换出对应分支；若分支命名与短名称不一致，从当前分支切出新分支。
3. 用户故事共创 ：当无法确认需求能否作为独立用户故事时，可与 Claude 共创。共创完成后导出内容写入需求文档，用独立用户故事执行后续 Speckit 工作流。
4. 指令协作执行 ：Speckit 指令与 Claude Code 协作，Claude Code 依据 Speckit 生成的任务列表进行代码开发、测试等操作。
5. 功能互补 ：Speckit 负责需求分析、任务拆解、架构规约等流程性工作；Claude Code 辅助完成具体代码编写、测试和修复任务。

二、Speckit 和 Claude 使用指南

1. 工具下载与配置
   • 下载 ：提供 Mac 和 Windows 系统一键安装 Speckit 和 Claude Code 的脚本及操作步骤、脚本链接。
   • Claude Code 配置 ：安装 Node.js 18 或更新版本，通过 npm 包管理器全局安装，申请 API - Key 并配置环境变量。可在 ide 插件市场安装 Claude Code for vs code 插件，重启 ide 后在 terminal 中执行 claude 及 /ide 指令链接 ide。
   • Speckit 配置 ：安装前可在 Claude code 中提问解决安装问题。需确保安装 Python 3.11 + 和 Git，安装 uv 包管理器，使用 uv 工具安装 Spec Kit。
2. 项目初始化
   • 操作步骤 ：在 terminal 中切换到项目根目录，执行 specify init. 选择 claude 并按回车键；执行 claude，输入 /ide 选择代码编辑器，输入 /init 生成 CLAUDE.md 文件（已有则无需此步骤）。
   • 中文环境配置 ：在工程根目录下.claude/commands 文件夹中新增 speckit.lang.md 文件，在 CLAUDE.md 文件末尾追加内容 ，重启 claude 环境，执行 /speckit.lang zh - CN 切换到中文模式。
   • 自定义配置 ：可自定义配置 specs 生成目录及任务执行段，项目负责人配置完成后将相关文件 push 到远端，其他协作同学拉取配置。
3. 多人协作 Speckit 工作流
   • 需求定义 ：切换 claude 至 plan mode on 模式，产品与 claude code 共创用户故事，确认后写入本地 specifys.md 文件，执行 /speckit.specify 生成初版用户故事。
   • 需求澄清 ：执行 /speckit.clarify 做需求澄清，产品校验输出内容。
   • 交互原型产出 ：产品执行相关指令生成 web 端交互原型并完成内部评审。
   • 设计稿产出 ：UX/UI 同学依据原型设计和需求在 figma 上产出设计图，参考设计规范。
   • 需求评审 ：产品、研发、测试、设计进行评审，将需求按前端、app 端、后端拆分，认领需求，发现问题手动修改 md 文档。
   • 技术规划 ：研发执行 /speckit.plan，输入技术选型等信息，历史迭代需求参考现有选型并提供代码信息。
   • 任务拆分 ：研发执行 /speckit.task 生成任务拆分清单并二次确认。
   • 一致性评估 ：研发执行 /speckit.analyze 校验一致性。
   • 技术评审 ：服务端生成接口设计文档给 APP 端和前端，app 端和 web 端融入工作流保证接口和数据结构对齐。
   • 压缩上下文 ：主动压缩上下文避免对话中断。
   • 代码实现 ：APP 和前端同学先完成 UI 代码，再执行 /speckit.implement，带上新增页面代码路径等信息。
   • 代码检查 ：检查 task 对应代码是否实现、新增代码遗留 TODO 项目，完善单元测试用例代码，执行自动化单元测试，开发人员审核代码，提测。
4. Speckit 指令使用建议
   • speckit.specify ：遵循最小用户故事原则，功能需求对应单一用户故事，功能多的故事可二次拆分，任务量控制在 3 - 10 个 task。
   • speckit.plan ：新模块引入增加技术选型等决策；原功能迭代输入历史功能代码位置。
   • speckit.implement ：增加增强型约束条件和代码背景，正式开发前用 plan mode on 模式与 AI 确认需求，无误后切换到 accept edits on 模式。