GitHub Spec Kit 中文使用说明

Ne0inhk

23 Mar 2026 — 35 min read

📖 工具简介

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的核心是结构化的三步工作流，每一步都有明确的输入、处理和输出：

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

📋 三大核心命令详解

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

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

执行机制：

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

使用方法：

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

重要约束：

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

自动生成内容：

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

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

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

执行机制：

读取和分析功能规范中的需求、用户故事和验收标准
读取项目宪法确保架构合规性
执行计划模板的9个阶段流程
在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` 命令 - 任务列表生成

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

执行机制：

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

使用方法：

/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集成和自动化验证
规模化管理：多项目工作区和模式重用
合规性：企业级约束和安全要求

🤝 贡献和支持

参与开源贡献

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

代码贡献

Fork仓库：在GitHub上Fork spec-kit
创建功能分支：git checkout -b feature/your-contribution
遵循SDD原则：使用Spec Kit自身来规范新功能
提交代码：git commit -m "Add: 描述你的贡献"
创建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理解你的业务需求，通过可执行规范直接生成高质量代码！这就是规范驱动开发的强大威力！

📖 工具简介

🎯 核心理念：权力反转

🚀 安装方法

1. 环境要求

2. 快速安装

创建新项目

在当前目录初始化

3. 指定AI助手

4. 脚本类型选择

5. 安装选项

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

🛠️ 项目结构与基本使用

标准项目结构

三步SDD工作流

📋 三大核心命令详解

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

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

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

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

📜 宪法核心条款

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

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

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

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

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

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

🛡️ 宪法执行机制

门控检查（Phase Gates）

复杂度追踪

🔄 宪法演进

⚙️ 模板驱动的质量保证

🎯 模板约束机制

1. 防止过早实现细节

2. 强制不确定性标记

3. 结构化检查清单

4. 层次化信息管理

📋 模板系统结构

规范模板（spec-template.md）

计划模板（plan-template.md）

任务模板（tasks-template.md）

⚙️ 配置选项

自定义宪法配置

模板自定义

自定义规范模板

自定义计划模板

💡 实际使用示例

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

Step 1: 功能规范创建

Step 2: 技术实现计划

Step 3: 任务列表生成

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

Step 1: 详细功能规范

Step 2: 技术架构决策

Step 3: TDD任务分解

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

📈 SDD最佳实践

1. 规范编写的黄金原则

专注WHAT和WHY，避免HOW

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

编写可测试的验收标准

2. 分阶段开发策略

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

创意探索（并行实现）

迭代增强（棕地现代化）

3. 团队协作的SDD模式

规范审查流程

分支策略

并行开发协调

4. 质量保证的内建机制

宪法合规自动检查

规范完整性验证

持续的规范-代码一致性

5. 避免常见陷阱

过度详细的规范

跳过澄清阶段

忽视宪法原则

批量功能规范

🎯 适用场景

✅ 非常适合SDD的场景

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

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

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

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