Spec-Kit 是一款规范驱动开发的 CLI 工具包，通过可执行规格、宪法治理及多阶段校验将模糊需求转化为生产级代码。基于 v0.9.2 版本，详解环境搭建、核心流程实战、团队协作配置及问题排查。涵盖初始化项目与宪法定义、规格澄清歧义、技术规划任务分解、自动化实现验证、一致性分析迭代优化等步骤。支持团队统一模板与 CI/CD 集成，降低沟通成本，提升 AI 编码质量与预期一致性。
在 AI 编码工具普及的当下，'生成速度'已不再是瓶颈，'输出质量与预期一致性'才是开发者的核心痛点。GitHub 的 Spec-Kit 作为规范驱动开发的标杆工具包，通过'可执行规格 + 宪法治理 + 多阶段校验'的组合拳，将模糊需求转化为可预测的生产级代码。本文基于 Spec-Kit v0.9.2 版本，从环境搭建、核心流程实战、团队协作配置、问题排查四个维度，提供操作手册。
Spec-Kit 作为轻量 CLI 工具，支持全平台本地运行，无需云依赖，确保规格与代码隐私。以下是针对不同场景的安装指南：
前置依赖：
uv（推荐，Rust 编写的快装工具）或 pipx；Git 2.30+；AI 工具 CLI（如 claude 或 copilot-cli）安装步骤：
配置 AI 代理（以 Claude 为例）：
# 导出 Anthropic API 密钥
export ANTHROPIC_API_KEY="your-api-key"
# 测试 AI 连接
specify ai test --agent claude
验证安装：
specify --version # 应输出 v0.9.2
安装 Spec-Kit CLI：
uv tool install specify-cli --from git+https://github.com/github/[email protected]
安装 uv（若未安装）：
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows（PowerShell）
irm https://astral.sh/uv/install.ps1 | iex
对于团队协作，需统一规格模板、宪法规则和集成工具，避免'各用各的规范'：
配置团队级 AI 代理：
在项目根目录的 .specify/config.toml 中统一代理设置：
[ai]
default_agent = "claude"
timeout = 300 # 5 分钟超时
max_tokens = 4096
[validation]
required_checks = ["test_coverage", "lint", "security_scan"]
初始化项目时复用模板：
specify init my-project \
--ai claude \
--template https://github.com/your-org/team-spec-templates \
--constitution constitution-template.md
创建团队规格模板库：
在 GitHub 建立 team-spec-templates 仓库，包含通用模板：
team-spec-templates/
├── constitution-template.md # 团队通用宪法
├── spec-template.md # 规格文件模板
└── scripts/ # 共享校验脚本
Spec-Kit 的核心价值在于将'模糊需求'转化为'可执行、可验证的代码'，通过八阶段闭环实现全流程治理。以下以'电商购物车折扣功能'为例，完整演示全流程：
目标：创建项目结构，定义团队必须遵守的质量、安全与合规规则（宪法）。
验证宪法完整性：
specify constitution check # 检查是否包含必要条款
生成并编辑宪法文件（/.specify/constitution.md）：
运行 specify constitution generate 生成初稿，修改为：
# 电商项目宪法
## 质量门（强制）
- 测试覆盖率 ≥ 85%（单元测试 + 集成测试）
- 代码必须通过 ESLint 检查（规则：airbnb-base）
- API 响应时间 ≤ 300ms（95% 场景）
## 安全要求
- 所有用户输入必须经过验证（使用 Joi 库）
- 折扣计算逻辑必须包含日志审计
- 禁止硬编码敏感信息（使用环境变量）
## 技术栈规范
- 后端：Node.js + Express + TypeScript
- 数据库：PostgreSQL（使用 Prisma ORM）
- 测试：Jest + Supertest
初始化项目：
specify init ecommerce-cart --ai claude
cd ecommerce-cart
生成的核心目录结构：
ecommerce-cart/
├── .specify/ # Spec-Kit 核心目录
│ ├── constitution.md # 项目宪法
│ ├── config.toml # 配置文件
│ └── specs/ # 规格工件目录
└── specify.toml # 项目级配置
目标：将'购物车折扣功能'需求转化为结构化的 Gherkin 场景，通过 AI 澄清模糊点。
澄清歧义：
运行 specify clarify .specify/specs/cart-discount/spec.md，AI 会自动识别模糊点并提问：
AI 澄清：
1. 折扣是否有最低订单金额限制？
2. 折扣是否过期？若过期应如何处理？
补充回答后，AI 会自动更新 spec.md，确保需求无歧义。
编辑规格文件（spec.md），补充场景细节：
# 购物车折扣功能规格
## Requirement: Discount Application System MUST support percentage-based and fixed-amount discounts; only one discount per order.
### Scenario: Apply Percentage Discount
- GIVEN cart with total $100
- WHEN applying 10% discount
- THEN cart total becomes $90
- AND discount type is recorded as "percentage"
### Scenario: Apply Fixed Discount
- GIVEN cart with total $150
- WHEN applying $20 fixed discount
- THEN cart total becomes $130
- AND discount type is recorded as "fixed"
### Scenario: Reject Multiple Discounts
- GIVEN cart with active 10% discount
- WHEN applying $20 fixed discount
- THEN return error "Only one discount allowed"
生成规格初稿： 在项目根目录运行斜杠命令（支持集成到 VS Code 等编辑器）：
/speckit.specify 购物车折扣功能：支持百分比折扣和固定金额折扣，同一订单只能用一种折扣
Spec-Kit 会在 .specify/specs/cart-discount/ 生成 spec.md：
目标：将规格转化为技术实现方案（plan）和可执行的任务链（tasks）。
分解任务链：
运行 specify tasks generate .specify/specs/cart-discount/，生成 tasks.md：
# 折扣功能任务链
## 前置任务
- [P] 1. 更新 Prisma 模型（添加 Discount 表）
- [P] 2. 编写折扣计算工具函数（utils/discount.ts）
## 核心任务
- [ ] 3. 实现 Cart 服务的 addDiscount 方法
- [ ] 4. 编写折扣验证 middleware
- [ ] 5. 扩展 API 端点（POST /carts/:id/discount）
## 测试任务
- [ ] 6. 编写单元测试（覆盖 3 个场景）
- [ ] 7. 编写集成测试（API 层面）
## 备注
- [P] 标记的任务可并行执行
- 任务 6 依赖任务 2、3 完成
生成技术规划：
specify plan generate .specify/specs/cart-discount/spec.md
生成 plan.md，包含技术选型和架构设计：
# 购物车折扣功能技术规划
## 架构设计
- 新增 Discount 模型（Prisma）：id, type (enum), value, minOrderAmount?, expiry?
- 扩展 Cart 服务：addDiscount(discountId), removeDiscount()
- 新增 middleware 验证折扣有效性
## 技术栈细节
- 折扣计算：纯函数（utils/discount.ts），便于测试
- 验证逻辑：Joi schema（validation/discount.ts）
- 日志：winston 记录折扣应用记录
目标：按任务链生成代码，通过宪法定义的质量门自动验证。
prisma/schema.prisma）src/utils/discount.ts）src/services/cart.ts）处理验证失败： 若测试覆盖率仅 70%，Spec-Kit 会提示：
验证失败：测试覆盖率 70% < 要求的 85%
建议：为 discount.ts 添加边界测试（如折扣为 0、超过 100% 的情况）
运行 specify implement --fix，AI 会自动补充缺失的测试用例。
自动执行验证（基于宪法中的质量门）： 生成完成后，Spec-Kit 自动触发验证钩子：
# 自动运行的验证步骤
npm run lint # 检查代码风格（符合 airbnb-base）
npm test -- --coverage # 检查测试覆盖率（需 ≥85%）
specify security scan # 检查是否有硬编码敏感信息
执行代码生成：
specify implement .specify/specs/cart-discount/tasks.md
Spec-Kit 会调用 Claude 按任务顺序生成代码：
目标：确保规格、规划、代码的一致性，迭代优化工件。
/speckit.clarify 补充过期折扣场景，AI 自动更新 spec.md、tasks.md 并生成对应的代码和测试。specify archive .specify/specs/cart-discount/，将最终版本归档至 .specify/archives/，便于追溯。运行一致性分析：
specify analyze .specify/specs/cart-discount/
输出分析报告：
一致性检查结果：
- ✅ spec.md 与 plan.md 一致
- ✅ plan.md 中定义的 middleware 在代码中已实现
- ⚠️ spec.md 中的 "过期折扣" 场景未在测试中覆盖（补充测试）
Spec-Kit 不仅是个人工具，更是团队协作的'规范中枢'。通过统一规格模板、自动化校验和 CI/CD 集成，可大幅降低团队沟通成本。
spec.md 可直接作为需求评审文档，团队成员通过 PR 评论反馈，避免'需求文档与代码脱节'。评审钩子：配置 pre-commit 钩子，确保规格修改前通过团队评审：
# .git/hooks/pre-commit
#!/bin/sh
specify review check .specify/specs/ # 检查是否有未评审的规格变更
版本化管理：所有规格工件（spec.md/plan.md/tasks.md）纳入 Git 管理，每次修改生成变更记录：
specify log .specify/specs/cart-discount/ # 查看规格修改历史
将 Spec-Kit 验证步骤集成到 GitHub Actions，确保合并到主分支的代码符合宪法规范：
# .github/workflows/spec-kit.yml
name: Spec-Kit Validation
on:
pull_request:
jobs:
validate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: astral-sh/setup-uv@v2
- run: uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
- run: specify install-deps # 安装项目依赖
- run: specify constitution check # 检查宪法合规性
- run: specify analyze .specify/specs/ # 检查规格一致性
- run: specify test # 运行所有测试并验证覆盖率
大型项目可按角色分配规格职责：
spec.md（定义'做什么'）plan.md（定义'技术方案'）tasks.md 并生成代码specify test --update 更新测试用例协作流程：
spec.md PR → 团队评审通过spec.md 提交 plan.md PR → 技术评审通过tasks.md 生成代码 → 自动验证通过| 问题现象 | 可能原因 | 解决方案 |
|---|---|---|
| AI 生成代码不符合技术栈 | constitution.md 未明确技术栈，或 AI 未读取到 | 1. 在宪法中添加 ## 技术栈规范 章节2. 运行 specify constitution sync 强制同步 |
| 验证失败但原因模糊 | 宪法中的质量门定义不具体（如'性能良好'） | 1. 将模糊描述量化（如'API 响应 < 300ms'） 2. 运行 specify validation debug 查看详细日志 |
| 规格与代码不一致 | 手动修改代码后未更新规格 | 1. 运行 specify analyze --diff 生成规格更新建议2. 配置 post-commit 钩子自动检查一致性 |
| AI 生成任务遗漏依赖 | 场景描述未包含前置条件 | 1. 在 spec.md 中补充 Given 场景的前置依赖2. 运行 specify tasks repair 修复任务链 |
specify cache enable 缓存分析结果，减少重复计算。tasks.md 中标记 [P] 的任务会自动并行生成，缩短生成时间。specify implement --incremental 只更新变更相关代码。Scenario 只包含一个核心逻辑（如'应用折扣'与'拒绝多折扣'分拆），便于测试和生成。specify constitution update 迭代宪法（如新增 GDPR 合规条款），并运行 specify constitution audit 检查历史代码兼容性。从上述实战流程可见，Spec-Kit 真正的创新不是'生成代码更快'，而是通过宪法锁定治理规则、规格明确意图边界、任务分解实现路径、验证保障输出质量，将 AI 编码从'随机生成'转化为'可控流程'。对于个人开发者，它减少了 70% 的'生成 - 修改 - 再生成'循环；对于团队，它将需求与代码的对齐成本降低 80%。
随着 Spec-Kit 生态的完善（如与 GitHub Copilot 更深度的集成、企业级合规模块），规范驱动开发正在成为 AI 时代的主流开发范式——未来的开发，不再是'与 AI 猜需求'，而是'用规范指挥 AI 实现需求'。
附录：
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML转Markdown 互为补充。 在线工具，Markdown转HTML在线工具，online
将 HTML 片段转为 GitHub Flavored Markdown，支持标题、列表、链接、代码块与表格等；浏览器内处理，可链接预填。 在线工具，HTML转Markdown在线工具，online