GitHub Spec Kit 中文使用说明

📖 工具简介

GitHub Spec Kit 是GitHub开源的规范驱动开发（Specification-Driven Development, SDD）工具包，它彻底颠覆了传统软件开发模式。在传统开发中，代码是王者，规范服务于代码；而Spec Kit实现了权力反转——规范成为主导，代码服务于规范。规范不再是指导实现的文档，而是能够直接生成实现的可执行文件。

该项目在过去30天内星标数量约20k，近期平均每天新增超1k星标，这反映出其高速增长趋势和社区的积极反馈。这种受欢迎度源于其易用性和强大的功能，帮助开发者高效处理标准化工作流。

🎯 核心理念：权力反转

传统模式：规范 → 指导 → 代码实现 SDD模式：规范 → 直接生成 → 代码实现

• 规范优先：规范成为开发的首要驱动力，而非辅助文档
• 可执行规范：规范足够精确和完整，能够直接生成工作系统
• 消除鸿沟：彻底消除规范与实现之间的转译差距
• AI协同增强：通过AI的理解能力让自然语言规范变为可执行代码
• 持续进化：生产反馈直接更新规范，驱动下一轮生成

🚀 安装方法

1. 环境要求

必需软件：

• Linux/macOS (Windows需要WSL2或原生PowerShell支持)
• AI编码助手：Claude Code、GitHub Copilot、Gemini CLI或Cursor
• Python 3.11+：https://www.python.org/downloads/
• uv包管理器：https://docs.astral.sh/uv/
• Git：https://git-scm.com/downloads

2. 快速安装

创建新项目

uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>

在当前目录初始化

uvx --from git+https://github.com/github/spec-kit.git specify init --here

3. 指定AI助手

支持多种AI编程助手：

# Claude Code（推荐）
uvx --from git+https://github.com/github/spec-kit.git specify init my-project --ai claude

# GitHub Copilot
uvx --from git+https://github.com/github/spec-kit.git specify init my-project --ai copilot

# Gemini CLI
uvx --from git+https://github.com/github/spec-kit.git specify init my-project --ai gemini

# Cursor
uvx --from git+https://github.com/github/spec-kit.git specify init my-project --ai cursor

4. 脚本类型选择

支持Bash和PowerShell两种脚本：

# 使用Bash脚本（Linux/macOS默认）
uvx --from git+https://github.com/github/spec-kit.git specify init my-project --script sh

# 使用PowerShell脚本（Windows默认/跨平台）
uvx --from git+https://github.com/github/spec-kit.git specify init my-project --script ps

5. 安装选项

跳过TLS校验（不推荐，仅排查故障）

uvx --from git+https://github.com/github/spec-kit.git specify init my-project --skip-tls

# 跳过AI工具检查
uvx --from git+https://github.com/github/spec-kit.git specify init my-project --ignore-agent-tools

# 跳过Git初始化
uvx --from git+https://github.com/github/spec-kit.git specify init my-project --no-git

# 启用调试模式
uvx --from git+https://github.com/github/spec-kit.git specify init my-project --debug

# 系统环境检查
uvx --from git+https://github.com/github/spec-kit.git specify check

🛠️ 项目结构与基本使用

标准项目结构

安装完成后，项目中会自动生成以下结构：

📝 目录结构更新说明：从 v0.0.34 版本开始，Spec Kit 将配置文件和脚本统一放在 .specify/ 隐藏目录中，以避免与用户项目文件冲突并提供更清晰的项目结构。

your-project/
├── .specify/                   # Spec Kit 配置目录（v0.0.34+）
│   ├── memory/                 # 项目知识库
│   │   ├── constitution.md     # 项目宪法（九大架构原则）
│   │   └── constitution_update_checklist.md
│   ├── scripts/                # 自动化脚本
│   │   └── powershell/         # PowerShell脚本版本
│   │       ├── create-new-feature.ps1
│   │       ├── setup-plan.ps1
│   │       ├── check-task-prerequisites.ps1
│   │       ├── common.ps1
│   │       ├── get-feature-paths.ps1
│   │       └── update-agent-context.ps1
│   └── templates/              # 模板文件
│       ├── spec-template.md    # 规范模板
│       ├── plan-template.md    # 计划模板
│       ├── tasks-template.md   # 任务模板
│       └── agent-file-template.md # AI助手配置模板
├── specs/                      # 功能规范目录（用户创建的规范）
│   └── 001-feature-name/       # 自动编号的功能目录
│       ├── spec.md             # 功能规范
│       ├── plan.md             # 实现计划
│       ├── research.md         # 技术研究
│       ├── data-model.md       # 数据模型
│       ├── contracts/          # API契约
│       ├── quickstart.md       # 快速验证指南
│       └── tasks.md            # 任务列表
└── CLAUDE.md                   # AI助手配置（自动生成）

三步SDD工作流

Spec Kit的核心是结构化的三步工作流，每一步都有明确的输入、处理和输出：

1. /specify - 规范创建：将自然语言需求转化为结构化规范
2. /plan - 计划生成：基于规范生成技术实现计划
3. /tasks - 任务分解：将计划拆分为可执行的开发任务

📋 三大核心命令详解

1. /specify 命令 - 功能规范创建

核心作用：将自然语言功能描述转化为结构化技术规范

执行机制：

1. 自动扫描现有规范，确定下一个功能编号（如003）
2. 创建语义化分支名（如 003-user-management-system）
3. 基于规范模板生成结构化文档
4. 创建 specs/003-user-management-system/spec.md

使用方法：

/specify 构建一个实时聊天系统，支持消息历史记录和用户在线状态显示。用户可以创建聊天室，邀请其他用户，发送文本消息，查看消息历史，并实时看到其他用户的在线状态。系统需要支持多个并发聊天室，每个房间可以有无限数量的用户。

重要约束：

• ✅ 专注WHAT和WHY：描述用户需要什么功能以及为什么需要
• ❌ 避免HOW细节：不要涉及技术栈、API设计、代码结构
• 🎯 面向业务干系人：规范应该让业务人员能够理解和验证

自动生成内容：

• 用户场景和测试：基于描述生成的用户交互流程
• 功能需求：每个需求都必须可测试和明确
• 关键实体：如果涉及数据，识别核心数据实体
• 验收标准：明确的成功标准和完成定义

2. /plan 命令 - 实现计划生成

核心作用：读取功能规范，生成详细的技术实现计划

执行机制：

1. 读取和分析功能规范中的需求、用户故事和验收标准
2. 读取项目宪法确保架构合规性
3. 执行计划模板的9个阶段流程
4. 在specs目录生成多个设计文档

使用方法：

/plan 使用WebSocket实现实时消息传输，PostgreSQL存储消息历史，Redis管理用户在线状态和会话。后端使用FastAPI，前端使用React和Socket.IO客户端。实现RESTful API用于房间管理，WebSocket用于实时通信。

架构合规检查：

### 阶段-1：实现前门控
#### 简化门控（宪法第VII条）
- [ ] 使用≤3个项目？
- [ ] 无未来证明？

#### 反抽象门控（宪法第VIII条）
- [ ] 直接使用框架？
- [ ] 单一模型表示？

#### 集成优先门控（宪法第IX条）
- [ ] 契约已定义？
- [ ] 契约测试已编写？

自动生成的文档：

• plan.md - 详细实现计划和架构决策
• research.md - 技术选型研究和决策依据
• data-model.md - 完整的数据模型设计
• contracts/ - OpenAPI规范和事件定义
• quickstart.md - 关键验证场景和设置指南

3. /tasks 命令 - 任务列表生成

核心作用：分析设计文档，生成按依赖关系排序的可执行任务列表

执行机制：

1. 读取plan.md获取技术栈和库信息
2. 如果存在，读取data-model.md、contracts/、research.md
3. 根据可用文档生成相应任务
4. 创建依赖排序和并行执行指导

使用方法：

/tasks

任务生成规则：

• 每个契约文件 → 契约测试任务 [P]（可并行）
• 每个数据实体 → 模型创建任务 [P]（可并行）
• 每个API端点 → 实现任务（如果共享文件则串行）
• 每个用户故事 → 集成测试任务 [P]（可并行）

任务依赖顺序：

设置任务 → 测试任务 → 实现任务 → 集成任务 → 完善任务
    ↓         ↓          ↓          ↓          ↓
  T001      T002       T005       T008       T010
  T003      T004       T006       T009       T011
            T007                             T012

输出示例：

## 任务列表

### 设置阶段
- **T001**: 项目初始化和依赖安装
- **T002**: 代码检查和格式化配置

### 测试阶段（可并行执行）
- **T003 [P]**: WebSocket事件契约测试
- **T004 [P]**: REST API契约测试
- **T005 [P]**: 用户模型单元测试

### 实现阶段
- **T006**: 实现用户认证服务
- **T007**: 实现聊天室管理服务
- **T008**: 实现WebSocket消息处理

### 并行执行示例
```bash
# 可以同时运行的任务组
Group 1: T003, T004, T005
Group 2: T010, T011, T012

## 🏛️ 九大架构原则（项目宪法）

Spec Kit的核心是内置的项目宪法（.specify/memory/constitution.md），这是一套不可变的架构原则，确保所有生成的代码都遵循一致的质量标准和设计哲学。

📜 宪法核心条款

第I条：库优先原则（Library-First Principle）

每个功能必须首先作为独立库实现。
不允许直接在应用代码中实现功能，必须先抽象为可重用的库组件。

约束效果：强制模块化设计，确保代码可重用和可测试。

第II条：CLI接口要求（CLI Interface Mandate）

所有CLI接口必须：
- 接受文本输入（通过stdin、参数或文件）
- 产生文本输出（通过stdout）
- 支持JSON格式的结构化数据交换

约束效果：确保所有功能都可观察、可测试、可自动化。

第III条：测试优先要求（Test-First Imperative）- 不可协商

这是不可协商的：所有实现必须遵循严格的测试驱动开发。
在编写实现代码前必须：
1. 编写单元测试
2. 测试经用户验证和批准
3. 确认测试失败（红色阶段）

约束效果：彻底颠覆传统AI代码生成，强制"测试先行"的开发模式。

第VII条：简化原则（Simplicity Principle）

第7.3节：最小项目结构
- 初始实现最多3个项目
- 额外项目需要文档化理由

约束效果：对抗过度工程化，确保简单性优于复杂性。

第VIII条：反抽象原则（Anti-Abstraction Principle）

第8.1节：框架信任
- 直接使用框架特性而非包装它们
- 避免创建不必要的抽象层

约束效果：防止AI创建过度抽象的代码架构。

第IX条：集成优先测试（Integration-First Testing）

测试必须使用真实环境：
- 优先使用真实数据库而非模拟
- 使用实际服务实例而非桩
- 实现前必须有契约测试

约束效果：确保生成的代码在真实环境中可用，而非仅在理论上可行。

🛡️ 宪法执行机制

门控检查（Phase Gates）

每个实现计划都必须通过以下门控：

### 阶段-1：实现前门控

#### 简化门控（第VII条）
- [ ] 使用≤3个项目？
- [ ] 无未来证明？

#### 反抽象门控（第VIII条）
- [ ] 直接使用框架？
- [ ] 单一模型表示？

#### 集成优先门控（第IX条）
- [ ] 契约已定义？
- [ ] 契约测试已编写？

复杂度追踪

如果违反原则，必须在"复杂度追踪"部分记录理由：

### 复杂度追踪
**违反第VII条**：使用了4个项目
**理由**：微服务架构需要独立的认证服务
**批准者**：架构师审核通过
**审核日期**：2024-01-15

🔄 宪法演进

虽然核心原则不可变，但应用方式可以演进：

第4.2节：修订程序
对本宪法的修改需要：
- 明确记录变更理由
- 项目维护者审查批准
- 向后兼容性评估

这确保了方法论能够学习和改进，同时保持稳定性。

⚙️ 模板驱动的质量保证

Spec Kit通过精心设计的模板来约束AI行为，确保生成高质量的规范和代码。这些模板不仅是文档结构，更是智能的行为引导系统。

🎯 模板约束机制

1. 防止过早实现细节

规范模板明确指示：
- ✅ 专注于用户需要什么和为什么
- ❌ 避免如何实现（无技术栈、API、代码结构）

效果：强制AI维持适当的抽象层次，确保规范稳定性。

2. 强制不确定性标记

创建规范时：
1. 标记所有模糊性：使用[需要澄清：具体问题]
2. 不要猜测：如果提示没有指定某些内容，标记它

效果：防止AI做出可能错误的假设，确保规范的准确性。

3. 结构化检查清单

### 需求完整性检查
- [ ] 没有[需要澄清]标记
- [ ] 需求可测试且明确
- [ ] 成功标准可衡量
- [ ] 所有用户故事有验收标准

效果：为AI提供自检框架，确保输出质量。

4. 层次化信息管理

重要：实现计划应保持高层次和可读性。
任何代码示例、详细算法或扩展技术规范
必须放在相应的implementation-details/文件中

效果：防止文档变成不可读的代码转储，保持清晰的信息架构。

📋 模板系统结构

规范模板（spec-template.md）

• 执行流程：8步规范生成流程
• 质量门控：内置错误检查和警告机制
• 指导原则：明确的做什么/不做什么指令

计划模板（plan-template.md）

• 九阶段流程：从需求分析到任务分解的完整流程
• 宪法合规：强制架构原则检查
• 文档生成：自动创建多个设计文档

任务模板（tasks-template.md）

• 依赖分析：智能任务排序算法
• 并行识别：自动标记可并行执行的任务
• TDD强制：确保测试先于实现的任务顺序

⚙️ 配置选项

自定义宪法配置

位于 .specify/memory/constitution.md，可以在标准九大原则基础上添加项目特定原则：

# 项目宪法

## 标准原则（来自Spec Kit）
[自动包含九大架构原则]

## 项目特定原则

### X. 数据隐私优先
所有用户数据处理必须：
- 遵循GDPR/CCPA合规要求
- 实现数据最小化原则
- 提供明确的用户同意机制

### XI. 性能标准
- API响应时间 < 500ms (P95)
- 数据库查询 < 2s
- 支持100并发用户
- 内存使用 < 2GB

### XII. 安全要求
- 所有API端点必须认证
- 敏感数据必须加密
- 定期安全扫描

模板自定义

可以修改 .specify/templates/目录下的模板文件来适应团队需求：

自定义规范模板

<!-- .specify/templates/custom-spec-template.md -->
# 功能规范：[功能名称]

## 业务背景
[BUSINESS_CONTEXT] - 为什么需要这个功能

## 用户画像
[USER_PERSONAS] - 目标用户群体

## 核心价值
[CORE_VALUE] - 这个功能为用户带来什么价值

## 功能需求
[FUNCTIONAL_REQUIREMENTS]

## 验收标准
[ACCEPTANCE_CRITERIA]

## [需要澄清]项目
- [需要澄清：认证方式 - OAuth、SAML还是简单密码？]
- [需要澄清：数据保留政策 - 保存多长时间？]

自定义计划模板

可以修改 .specify/templates/plan-template.md来适应特定的技术栈或架构模式：

### 技术上下文（自定义部分）
- 强制使用公司标准技术栈
- 必须符合企业安全政策
- 集成现有的监控和日志系统
- 遵循公司API设计规范

💡 实际使用示例

示例1：照片管理应用（来自官方README）

这是Spec Kit官方文档中的完整示例，展示了从需求到实现的完整流程：

Step 1: 功能规范创建

/specify 构建一个照片管理应用，帮助我将照片整理到单独的相册中。相册按日期分组，可以在主页面上通过拖拽重新排序。相册永远不会嵌套在其他相册中。在每个相册内，照片以磁贴界面预览。

自动执行的操作：

• 创建分支：001-photo-management-app
• 生成规范：specs/001-photo-management-app/spec.md
• 包含用户故事、验收标准、关键实体

Step 2: 技术实现计划

/plan 应用使用Vite构建，尽量减少库的使用。尽可能使用原生HTML、CSS和JavaScript。图片不上传到任何地方，元数据存储在本地SQLite数据库中。

自动生成的文档：

• plan.md - 详细实现计划
• research.md - Vite和SQLite技术研究
• data-model.md - 相册和照片数据模型
• contracts/api-spec.json - 本地API接口定义
• quickstart.md - 本地开发环境设置

Step 3: 任务列表生成

/tasks

生成的任务列表：

### 设置阶段
- T001: 初始化Vite项目和SQLite数据库
- T002: 配置开发环境和构建工具

### 测试阶段（可并行执行）
- T003 [P]: 相册管理API契约测试
- T004 [P]: 照片元数据API契约测试
- T005 [P]: 拖拽功能集成测试

### 实现阶段
- T006: 实现SQLite数据库模型
- T007: 实现相册管理功能
- T008: 实现照片导入和预览
- T009: 实现拖拽排序功能

示例2：团队协作平台（Taskify）

这是一个更复杂的企业级应用示例：

Step 1: 详细功能规范

/specify 开发Taskify，一个团队生产力平台。允许用户创建项目，添加团队成员，分配任务，评论并在看板风格的板块间移动任务。在这个初始阶段，我们要有多个用户但用户是预定义的。我需要5个用户分为两个类别，一个产品经理和四个工程师。让我们创建三个不同的示例项目。我们要有标准的看板列，如"待办"、"进行中"、"审查中"和"完成"。应用没有登录功能，这只是第一个测试版本。

规范特点：

• 明确的用户角色定义
• 具体的数据量要求（5个用户，3个项目）
• 清晰的功能边界（无登录系统）
• 详细的交互模式（看板拖拽）

Step 2: 技术架构决策

/plan 使用.NET Aspire生成，使用Postgres作为数据库。前端应使用Blazor服务器，具有拖放任务板和实时更新。应创建REST API，包括项目API、任务API和通知API。

架构合规检查：

#### 简化门控（第VII条）
- [x] 使用≤3个项目？（Web应用 + API + 数据库）
- [x] 无未来证明？（仅实现当前需求）

#### 反抽象门控（第VIII条）
- [x] 直接使用框架？（直接使用Blazor和.NET Aspire）
- [x] 单一模型表示？（统一的任务和项目模型）

Step 3: TDD任务分解

/tasks

强制TDD流程：

### 测试优先阶段
- T001: 编写项目管理API契约测试
- T002: 编写任务CRUD操作契约测试
- T003: 编写看板拖拽行为集成测试
- T004: 获得用户对测试场景的确认
- T005: 验证所有测试均失败（红色阶段）

### 实现阶段（仅在测试通过后）
- T006: 实现项目管理服务使T001通过
- T007: 实现任务服务使T002通过
- T008: 实现前端拖拽使T003通过

示例3：15分钟vs12小时对比

传统开发方式（12小时文档工作）：

1. 编写PRD文档（2-3小时）
2. 创建设计文档（2-3小时）
3. 手动设置项目结构（30分钟）
4. 编写技术规范（3-4小时）
5. 创建测试计划（2小时）
总计：约12小时的文档工作

SDD方式（15分钟）：

# 5分钟：创建功能规范
/specify 实时聊天系统，支持消息历史和用户在线状态

# 5分钟：生成实现计划
/plan WebSocket实时消息，PostgreSQL历史，Redis在线状态

# 5分钟：生成可执行任务
/tasks

# 结果：完整的项目规范、技术计划、API契约、数据模型、任务列表

质量对比：

• ✅ 完整性：模板确保没有遗漏关键方面
• ✅ 一致性：所有项目遵循统一的架构原则
• ✅ 可追溯性：每个技术决策都能追溯到具体需求
• ✅ 可执行性：生成的任务可以直接开始实现

📈 SDD最佳实践

1. 规范编写的黄金原则

专注WHAT和WHY，避免HOW

✅ 好的规范：
"用户需要能够在断网情况下继续浏览已下载的内容，确保用户体验不受网络状况影响"

❌ 错误的规范：
"实现Service Worker缓存策略，使用IndexedDB存储离线数据，配置Webpack离线插件"

使用[需要澄清]标记代替猜测

✅ 正确做法：
"用户可以邀请其他用户加入聊天室 [需要澄清：邀请方式 - 邮件链接、用户名搜索还是邀请码？]"

❌ 错误做法：
"用户通过邮件链接邀请其他用户加入聊天室"（除非明确指定）

编写可测试的验收标准

✅ 可测试：
"当用户拖拽任务卡片到'完成'列时，系统应在2秒内更新状态并向项目成员发送通知"

❌ 不可测试：
"任务完成后系统会合理地通知相关人员"

2. 分阶段开发策略

0-to-1开发（从零开始）

# 阶段1：核心MVP
/specify 用户认证和基本任务管理

# 阶段2：协作功能
/specify 任务评论和团队通知

# 阶段3：高级功能
/specify 项目分析和报告功能

创意探索（并行实现）

同一规范生成多种实现方案：
- 方案A：性能优化（Redis缓存 + CDN）
- 方案B：成本优化（SQLite + 静态部署）
- 方案C：可扩展性优化（微服务 + Kubernetes）

迭代增强（棕地现代化）

现有系统的逐步改进：
- 第1轮：添加新功能到现有架构
- 第2轮：部分模块现代化重构
- 第3轮：渐进式架构演进

3. 团队协作的SDD模式

规范审查流程

1. 业务分析师 → 使用/specify创建初始规范
2. 技术负责人 → 审查技术可行性，添加约束
3. 产品经理 → 验证业务逻辑，确认优先级
4. 架构师 → 确保宪法合规性
5. 全体确认 → 解决所有[需要澄清]项目

分支策略

# 功能分支命名自动化
/specify → 自动创建 003-user-management-system

# 合并策略
git checkout main
git merge 003-user-management-system  # 包含完整规范和计划

并行开发协调

### 可并行执行的功能
- 001-user-authentication [开发团队A]
- 002-product-catalog [开发团队B]
- 003-order-processing [开发团队C]

### 依赖关系
- 003依赖001（订单需要用户认证）
- 共享的数据模型需要协调

4. 质量保证的内建机制

宪法合规自动检查

每个/plan命令都会自动检查：
- [ ] 是否违反简化原则？（>3个项目）
- [ ] 是否创建了不必要的抽象？
- [ ] 是否跳过了契约测试？
- [ ] 是否遵循了TDD要求？

规范完整性验证

# 自动检查规范质量
- 所有[需要澄清]标记已解决
- 每个功能需求都有对应的验收标准
- 用户故事格式正确（作为...我希望...以便...）
- 成功标准可量化测量

持续的规范-代码一致性

传统问题：规范与代码逐渐偏离
SDD解决方案：规范是代码生成的唯一来源

变更流程：
需求变化 → 更新规范 → 重新生成计划 → 更新任务 → 重新实现

5. 避免常见陷阱

过度详细的规范

❌ 错误：在规范中描述数据库表结构、API端点、类名
✅ 正确：描述用户需要什么数据、什么操作、什么体验

跳过澄清阶段

❌ 错误：假设"用户登录"就是邮箱密码认证
✅ 正确：标记[需要澄清：认证方式]并与干系人确认

忽视宪法原则

❌ 错误：为了"更好的架构"创建复杂的抽象层
✅ 正确：遵循简化和反抽象原则，直接使用框架

批量功能规范

❌ 错误：一次性规范整个系统
✅ 正确：每个功能一个独立规范，逐步迭代

🎯 适用场景

✅ 非常适合SDD的场景

1. 0-to-1产品开发（绿地项目）

• 新产品/新功能：从零开始构建的项目
• 创业MVP：需要快速验证想法但要保证质量
• 企业新业务线：需要严格的架构规范
• 技术栈迁移：重新设计现有系统的架构

2. 团队协作项目

• 多团队开发：需要统一的开发标准和流程
• 跨地区团队：通过规范确保一致的理解
• 外包项目：清晰的规范减少沟通成本
• 新成员快速上手：完整的文档体系

3. 企业级和合规项目

• 金融/医疗系统：需要严格的质量和安全标准
• 政府项目：要求完整的文档和可追溯性
• 长期维护系统：需要持续演进的架构
• API开放平台：需要精确的契约定义

4. 创意探索阶段

• 技术选型对比：同一规范生成多种实现方案
• 架构实验：快速验证不同架构模式
• 性能优化：为不同优化目标生成方案
• 成本控制：生成适应不同预算的方案

⚠️ 需要谨慎考虑的场景

1. 超高速迭代项目

特征：每日多次部署，需求变化极快
建议：可以使用简化的SDD流程，专注/specify阶段

2. 纯研究/实验项目

特征：目标不明确，大量试错
建议：等研究结果稳定后再应用SDD

3. 简单工具脚本

特征：<100行代码，单一功能
建议：直接编码比规范编写更高效

❌ 不适合SDD的场景

• 紧急修复（Hotfix）：生产问题需要立即解决
• 一次性数据处理脚本：用完即弃的工具
• 个人学习项目：学习过程重于结果
• 完全确定性的简单任务：如静态网站、简单CRUD

🔧 故障排除

环境和安装问题

1. uv工具未安装

症状：uvx命令不存在 解决方案：

# Linux/macOS
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# 验证安装
uv --version

2. Python版本不兼容

症状：安装时提示Python版本要求 解决方案：

# 检查Python版本
python --version  # 需要 >= 3.11

# 使用pyenv管理Python版本
pyenv install 3.11.0
pyenv global 3.11.0

3. AI助手不识别命令

症状：/specify、/plan、/tasks命令无效 解决方案：

# 检查CLAUDE.md是否正确生成
ls -la CLAUDE.md

# 重新初始化项目
uvx --from git+https://github.com/github/spec-kit.git specify init --here --ai claude

# 确认AI助手配置
cat CLAUDE.md | grep -A 5 "specify\|plan\|tasks"

工作流程问题

4. 规范生成质量不佳

症状：生成的规范过于简单、缺少关键信息或偏离需求 根本原因分析：

• 输入描述过于模糊或技术化
• 缺少业务上下文和用户价值说明
• AI没有足够信息进行高质量生成

解决方案：

# ✅ 改进输入描述示例
/specify 构建一个团队任务管理系统。产品经理需要能够创建项目和分配任务给开发人员，开发人员需要能够更新任务状态并添加进度评论，团队负责人需要能够查看项目整体进度和团队工作负载。系统应该支持5-50人的团队规模，任务状态包括待办、进行中、审查中、已完成。用户界面应该直观易用，适合技术和非技术人员使用。

# ❌ 避免的输入方式
/specify 用React做个看板系统，有拖拽功能，用MongoDB存数据

5. 架构合规检查失败

症状：/plan命令生成的计划不符合宪法原则 解决方案：

# 检查并修复常见违规
#### 简化门控失败
问题：生成了超过3个项目
解决：合并相关项目，如将API网关和业务服务合并

#### 反抽象门控失败
问题：创建了过多的抽象层
解决：直接使用框架特性，移除中间包装层

#### 测试优先门控失败
问题：没有契约测试计划
解决：在contracts/目录添加API规范，生成对应测试

6. 任务依赖关系混乱

症状：/tasks生成的任务顺序不合理或依赖关系错误 解决方案：

# 检查输入文档质量
ls specs/001-feature-name/
# 确保存在：plan.md, data-model.md, contracts/

# 手动调整任务顺序
# 编辑 specs/001-feature-name/tasks.md
# 遵循：设置 → 测试 → 实现 → 集成 → 完善

性能和扩展性问题

7. 大型项目处理缓慢

症状：多个功能规范时工具响应慢 解决方案：

# 分模块处理
每个功能独立一个分支和规范目录
001-user-management/
002-product-catalog/
003-order-processing/

# 清理旧的规范文件
find specs/ -name "*.md" -mtime +30 -type f

8. Git集成问题

症状：分支创建失败或合并冲突 解决方案：

# 检查Git状态
git status
git branch -a

# 清理未完成的功能分支
git branch -D 001-incomplete-feature

# 重新开始功能开发
git checkout main
/specify [新的功能描述]

🌟 高级用法

1. 企业级CI/CD集成

GitHub Actions工作流

# .github/workflows/sdd-pipeline.yml
name: Spec-Driven Development Pipeline
on: [push, pull_request]

jobs:
  validate-specs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Install Spec Kit
        run: |
          pip install uv
          uvx --from git+https://github.com/github/spec-kit.git specify check

      - name: Validate Specification Quality
        run: |
          # 检查所有[需要澄清]是否已解决
          if grep -r "\[需要澄清" specs/; then
            echo "ERROR: Found unresolved clarification markers"
            exit 1
          fi

      - name: Constitutional Compliance Check
        run: |
          # 验证宪法合规性
          python scripts/check-constitution-compliance.py

      - name: Generate Implementation Report
        run: |
          # 基于规范生成实现报告
          uvx --from git+https://github.com/github/spec-kit.git specify generate-report

自动规范审查

# scripts/spec-review.sh
#!/bin/bash

echo "🔍 自动规范审查..."

# 检查规范完整性
for spec_file in specs/*/spec.md; do
    if ! grep -q "验收标准" "$spec_file"; then
        echo "❌ $spec_file 缺少验收标准"
        exit 1
    fi
done

echo "✅ 所有规范通过基本检查"

2. 多项目企业工作区

工作区结构

enterprise-workspace/
├── shared/
│   ├── constitution.md          # 企业统一宪法
│   ├── templates/               # 共享模板库
│   └── standards/               # 编码标准
├── frontend-app/                # 前端项目
├── backend-api/                 # 后端API
├── mobile-app/                  # 移动应用
└── data-pipeline/               # 数据管道

统一标准管理

# 创建企业工作区
mkdir enterprise-workspace
cd enterprise-workspace

# 设置共享资源
mkdir shared/{templates,standards}

# 初始化各个项目并链接共享资源
for project in frontend-app backend-api mobile-app data-pipeline; do
    uvx --from git+https://github.com/github/spec-kit.git specify init $project --ai claude
    ln -sf ../shared/constitution.md $project/memory/constitution.md
    ln -sf ../shared/templates/* $project/templates/
done

3. 规范库和模式重用

创建企业规范库

<!-- shared/templates/enterprise-api-spec.md -->
# 企业API规范模板

## 业务上下文
[BUSINESS_VALUE] - 这个API为业务带来什么价值

## 安全要求
- OAuth 2.0认证 (企业标准)
- 所有端点必须HTTPS
- 敏感数据字段加密

## 性能标准
- P95响应时间 < 500ms
- 支持1000 QPS
- 99.9%可用性

## 合规要求
- GDPR数据保护
- SOX审计跟踪
- PCI DSS安全标准 (如涉及支付)

模式库建设

# 创建可重用的架构模式
shared/patterns/
├── microservices-pattern.md     # 微服务架构模式
├── event-driven-pattern.md      # 事件驱动模式
├── auth-pattern.md              # 认证授权模式
└── data-consistency-pattern.md  # 数据一致性模式

4. 智能规范生成

基于历史数据的规范改进

# scripts/spec-analytics.py
"""
分析历史规范质量，提供改进建议
"""

def analyze_spec_quality(spec_path):
    """分析规范质量指标"""
    metrics = {
        'clarity_score': calculate_clarity(spec_path),
        'completeness_score': check_completeness(spec_path),
        'testability_score': assess_testability(spec_path),
        'compliance_score': verify_constitution(spec_path)
    }
    return metrics

def suggest_improvements(metrics):
    """基于指标提供改进建议"""
    suggestions = []
    if metrics['clarity_score'] < 0.8:
        suggestions.append("建议增加更多业务上下文和用户价值说明")
    if metrics['testability_score'] < 0.7:
        suggestions.append("验收标准需要更具体和可量化")
    return suggestions

规范模板自动优化

# 定期更新模板基于项目反馈
# scripts/template-optimization.sh

#!/bin/bash
echo "📊 分析规范质量数据..."

# 收集过去30天的规范数据
find specs/ -name "spec.md" -mtime -30 > recent_specs.txt

# 生成质量报告
python scripts/spec-analytics.py recent_specs.txt > quality_report.json

# 更新模板
python scripts/update-templates.py quality_report.json

echo "✨ 模板已根据质量数据优化"

5. 跨团队协作机制

规范审查工作流

# .github/workflows/spec-review.yml
name: Specification Review
on:
  pull_request:
    paths: ['specs/**']

jobs:
  auto-review:
    runs-on: ubuntu-latest
    steps:
      - name: Constitutional Compliance
        run: scripts/check-constitution.py

      - name: Business Logic Review
        run: scripts/business-review.py

      - name: Technical Feasibility
        run: scripts/tech-review.py

      - name: Request Human Review
        if: failure()
        run: |
          gh pr review --request-reviewer=architect-team
          gh pr comment --body "🚨 自动审查发现问题，需要人工审查"

跨项目依赖管理

# 检查跨项目API依赖
python scripts/check-api-dependencies.py \
  --consumer specs/frontend-app/contracts/ \
  --provider specs/backend-api/contracts/ \
  --report dependency-report.json

📚 学习资源

官方资源

• 官方仓库：https://github.com/github/spec-kit
• 完整方法论：spec-driven.md - 深入了解SDD理论基础
• 视频演示：https://www.youtube.com/watch?v=a9eR1xsfvHg - 15分钟快速了解Spec Kit
• 官方博客：https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/

社区交流

• GitHub Discussions：https://github.com/github/spec-kit/discussions - 技术讨论和经验分享
• GitHub Issues：https://github.com/github/spec-kit/issues - 问题反馈和功能请求

深度学习主题

规范驱动开发(SDD)理论

• 权力反转原理：理解规范主导代码的核心思想
• 可执行规范：学习如何编写能生成代码的规范
• 模板工程：掌握约束AI行为的模板设计
• 架构宪法：理解不可变原则如何确保代码质量

AI协作编程

• 自然语言到代码：提升与AI助手的协作技巧
• 提示工程：优化规范描述以获得更好的生成结果
• 质量控制：通过模板和检查点确保AI输出质量
• 迭代改进：基于反馈持续优化规范质量

企业级应用

• 团队协作：规范审查流程和分支策略
• 质量保证：CI/CD集成和自动化验证
• 规模化管理：多项目工作区和模式重用
• 合规性：企业级约束和安全要求

相关技术领域

• 测试驱动开发(TDD)：理解测试优先的开发模式
• 契约测试：API契约和集成测试策略
• 模块化架构：库优先和反抽象原则
• 持续集成：自动化规范验证和代码生成

🤝 贡献和支持

参与开源贡献

GitHub Spec Kit是开源项目，欢迎社区参与：

代码贡献

1. Fork仓库：在GitHub上Fork spec-kit
2. 创建功能分支：git checkout -b feature/your-contribution
3. 遵循SDD原则：使用Spec Kit自身来规范新功能
4. 提交代码：git commit -m "Add: 描述你的贡献"
5. 创建Pull Request：详细描述变更和测试情况

社区支持

• 问题报告：报告bug或使用问题
• 功能建议：提出新功能想法和改进建议
• 文档改进：完善使用指南和最佳实践
• 经验分享：在Discussions中分享SDD实践经验
• 模板贡献：分享有用的自定义模板

企业级支持

对于企业用户的特殊需求：

• 自定义培训：SDD方法论和最佳实践培训
• 模板定制：针对特定行业或技术栈的模板
• 工具集成：与现有开发工具链的集成支持
• 架构咨询：规范驱动开发的组织级实施

维护者

• Den Delimarsky (@localden) - 项目维护者
• John Lam (@jflam) - 核心贡献者和理论研究

许可证

本项目采用MIT开源许可证，详见LICENSE文件。

Claude Code镜像站尊享会员：一键“无障碍”连接的AI全方位助手
官方网站：https://www.aicodemirror.com/dashboard

Claude 4 Sonnet和4.1 Opus模型随便玩，稳定输出，随叫随到。Pro、max、ultra各种套餐都有，单日体验版、包周包月包季度。加微：‘qq515675779‘’’可享活动优惠。

【核心优势一览】
国内地域直连，操作简易：省去繁杂设置及“魔法”工具，即刻享受顺畅的应用体验。
完善教程，快速入门：附赠详尽的部署指南和技术支持，一站式教学，确保用户迅速掌握使用精髓。
正版体验，兼容性强：兼容Claude Code CLI，同时适配VSCode、Cursor等插件，完美还原官方丰富功能应用。
功能完备，性能卓越：涵盖Claude 4 Sonnet与Claude 4.1 Opus两大先进模型，实现代码自动生成、跨文件重构、Git自动化操作及多语言翻译等功能，效果与官方版别无二致。
性价比高，成本经济：引入积分制模式，积分每小时自动恢复并提供重置选项，按token计费，较官方订阅更为节省成本。
【适用人群】
编程开发者：自动进行代码调试与优化，支持200K大型项目重构，极大提升开发效率。
学生群体：快速生成多样化的改写方案，助力论文降重、文献综述撰写及作业难题解决。
职场精英：高效制作周报、PPT大纲，提供高情商邮件模板，简化办公流程。
创意人才：激发创作灵感，协助编写短视频脚本、小说大纲与广告文案。

立即行动：

Claude Code镜像站尊享会员：一键“无障碍”连接的AI全方位助手
官方网站：https://www.aicodemirror.com/dashboard

加入Claude Code，让AI成为您的编程伙伴，轻松开启高效创作之旅！

---

🎯 总结

GitHub Spec Kit 不仅仅是一个工具，它代表了软件开发模式的根本性变革。通过规范驱动开发(SDD)，我们从"规范指导代码"进化到"规范生成代码"，实现了：

🚀 效率革命

• 15分钟 vs 12小时：规范生成效率提升98%
• 自动化文档：消除规范与代码的不一致
• 并行开发：智能任务分解支持团队并行工作

🏛️ 质量保证

• 九大架构原则：内置的代码质量约束
• 模板驱动：AI行为约束确保输出质量
• 测试优先：强制TDD确保代码可靠性

🤝 团队协作

• 统一标准：所有项目遵循相同的架构原则
• 版本化规范：规范变更的完整追溯能力
• 跨项目一致性：企业级工作区和模板共享

🌟 拥抱未来：让AI理解你的业务需求，通过可执行规范直接生成高质量代码！这就是规范驱动开发的强大威力！