GitHub Spec Kit 中文使用指南

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）

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

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

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

许可证

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

🎯 总结

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

🚀 效率革命

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

🏛️ 质量保证

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

🤝 团队协作

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

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