speckit中文说明书

[大白鲨吃沙]

Spec Kit 中文学习指南

目录

1. 简介

2. 核心概念

3. 完整工作流程

4. 命令详解

5. 实战示例

6. 最佳实践

7. 常见问题

---

简介

什么是 Spec Kit？

Spec Kit 是 GitHub 官方开源的规范驱动开发（Spec-Driven Development, SDD）工具包。它通过"规范→计划→任务→实现"的结构化流程，将 AI 从"代码生成工具"转变为"产品开发伙伴"。

核心理念

传统开发流程：

需求 → 代码 → 文档（经常缺失）

Spec Kit 流程：

规范 → 计划 → 任务 → 实现

关键区别：

• 规范先行：在写任何代码之前，先明确要构建什么

• 技术无关：规范阶段专注于"什么"和"为什么"，而不是"如何实现"

• 可追溯性：从用户需求到代码实现的完整追溯链

• 增量交付：每个用户故事都是独立可测试的

为什么使用 Spec Kit？

1. 提高质量：通过规范驱动减少返工

2. 加速开发：AI 理解需求更准确，生成代码更精准

3. 降低风险：早期发现需求不明确的地方

4. 团队协作：规范成为团队的共同语言

5. 知识沉淀：所有决策都有文档记录

---

核心概念

1. 规范驱动开发（SDD）

规范驱动开发是一种软件开发方法论，它将规范文档作为开发的核心驱动力，而不是代码。

传统开发的问题：

• 需求不明确就开始编码

• 频繁返工和修改

• 文档经常缺失或过时

• AI 生成代码时理解不准确

SDD 的优势：

• 先明确"做什么"，再考虑"怎么做"

• 规范成为可执行文档

• 减少沟通成本

• AI 能更准确地理解需求

2. 项目原则（Constitution）

项目原则是整个项目的最高指导文件，它定义了：

• 核心开发原则

• 技术约束

• 质量标准

• 开发流程

• 治理规则

作用：

• 指导所有后续开发决策

• 确保团队一致性

• 作为代码审查的依据

• 新成员快速理解项目

3. 功能规范（Specification）

功能规范详细描述要构建的功能，包括：

• 用户场景和故事

• 功能需求

• 成功标准

• 关键实体

• 边界和约束

关键特点：

• 技术无关：不涉及具体实现

• 用户导向：从用户视角描述

• 可测试：每个需求都可验证

• 可测量：成功标准可量化

4. 技术计划（Implementation Plan）

技术计划将功能规范转化为技术设计，包括：

• 技术栈选择

• 项目结构

• 架构决策

• 数据模型

• 接口契约

关键特点：

• 基于规范的技术设计

• 考虑项目原则约束

• 解决技术不确定性

• 为任务分解做准备

5. 任务列表（Tasks）

任务列表将技术计划分解为可执行的任务，包括：

• 按用户故事组织

• 依赖关系图

• 并行执行机会

• 独立测试标准

关键特点：

• 每个任务都可独立完成

• 支持并行开发

• 清晰的执行顺序

• 可追踪进度

---

完整工作流程

阶段概览

┌─────────────────────────────────────────────────────────────┐
│  1. /speckit.constitution - 建立项目原则              │
└─────────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────────┐
│  2. /speckit.specify - 创建功能规范                  │
└─────────────────────────────────────────────────────────────┘
                           ↓
              ┌──────────────┴──────────────┐
              │  可选：/speckit.clarify   │
              │  澄清需求                │
              └──────────────┬──────────────┘
                           ↓
┌─────────────────────────────────────────────────────────────┐
│  3. /speckit.plan - 创建技术计划                    │
└─────────────────────────────────────────────────────────────┘
                           ↓
              ┌──────────────┴──────────────┐
              │  可选：/speckit.checklist │
              │  质量检查清单            │
              └──────────────┬──────────────┘
                           ↓
┌─────────────────────────────────────────────────────────────┐
│  4. /speckit.tasks - 分解为任务                     │
└─────────────────────────────────────────────────────────────┘
                           ↓
              ┌──────────────┴──────────────┐
              │  可选：/speckit.analyze    │
              │  一致性分析              │
              └──────────────┬──────────────┘
                           ↓
┌─────────────────────────────────────────────────────────────┐
│  5. /speckit.implement - 执行实现                   │
└─────────────────────────────────────────────────────────────┘

详细步骤

步骤 1：建立项目原则

命令：/speckit.constitution

目的：创建项目的核心原则和开发准则

输入：项目原则的描述

输出：.specify/memory/constitution.md

示例：

/speckit.constitution 创建一个注重代码质量、测试标准、
用户体验一致性和性能要求的项目原则

生成的文档包含：

• 核心原则（如：测试优先、代码质量、性能标准）

• 技术约束

• 开发流程

• 治理规则

为什么重要：

• 指导所有后续开发决策

• 确保团队一致性

• 作为代码审查的依据

---

步骤 2：创建功能规范

命令：/speckit.specify <功能描述>

目的：用自然语言描述要构建的功能

关键原则：

• 专注于"什么"和"为什么"

• 不要涉及"如何实现"

• 从用户视角描述

• 确保可测试和可测量

输入：功能描述

输出：

• 新的功能分支

• specs/[###-feature-name]/spec.md

示例：

/speckit.specify 构建一个待办事项应用，用户可以添加、编辑、
删除和标记完成待办事项。待办事项应该按优先级分类（高、中、低）。
应用需要支持本地存储，数据不会上传到服务器。
界面简洁易用，支持移动端访问。

生成的规范包含：

• 用户场景和故事（按优先级排序）

• 功能需求

• 成功标准（可测量）

• 关键实体

• 边界和约束

用户故事的特点：

• 独立可测试：每个故事都可以独立开发和测试

• 按优先级排序：P1、P2、P3 等

• 用户导向：描述用户旅程

• 可交付：每个故事都是可用的功能增量

---

步骤 2.5（可选）：澄清需求

命令：/speckit.clarify

目的：在规划之前提出结构化问题，降低模糊领域的风险

何时使用：

• 规范中有不明确的地方

• 需要做出重要决策

• 有多个合理的解释

输出：结构化的问题和选项

示例：

## 问题 1：数据存储方式

**上下文**：应用需要支持本地存储

**需要知道**：使用哪种本地存储方式？

**建议答案**：

| 选项 | 答案 | 影响 |
|------|------|------|
| A | localStorage | 简单易用，但容量有限（5-10MB） |
| B | IndexedDB | 容量大，但 API 复杂 |
| C | SQLite | 功能强大，但需要额外库 |

**您的选择**：_

---

步骤 3：创建技术计划

命令：/speckit.plan <技术栈描述>

目的：提供技术栈和架构选择，将功能规范转化为技术设计

输入：技术栈和架构选择

输出：

• specs/[###-feature-name]/plan.md

• specs/[###-feature-name]/research.md

• specs/[###-feature-name]/data-model.md

• specs/[###-feature-name]/quickstart.md

• specs/[###-feature-name]/contracts/

示例：

/speckit.plan 应用使用原生 HTML、CSS 和 JavaScript，
不依赖任何框架。使用 localStorage 进行数据持久化。
采用响应式设计，支持移动端和桌面端。
遵循渐进增强原则，确保基本功能在所有浏览器中可用。

生成的计划包含：

1. 技术上下文：

   • 语言/版本

   • 主要依赖

   • 存储方式

   • 测试框架

   • 目标平台

   • 性能目标

   • 约束条件

   • 规模/范围

2. 项目结构：

   • 文档结构

   • 源代码结构

   • 测试结构

3. 宪法检查：

   • 验证是否符合项目原则

   • 识别违规（如果有）

   • 提供简化替代方案

4. 研究文档：

   • 技术决策

   • 决策理由

   • 考虑的替代方案

5. 数据模型：

   • 实体定义

   • 字段和关系

   • 验证规则

6. 接口契约：

   • API 规范

   • 命令模式

   • UI 契约

7. 快速开始：

   • 集成场景

   • 测试步骤

---

步骤 3.5（可选）：质量检查清单

命令：/speckit.checklist

目的：生成质量检查清单以验证需求的完整性、清晰度和一致性

何时使用：

• 在 /speckit.plan 之后

• 在 /speckit.tasks 之前

输出：specs/[###-feature-name]/checklists/

检查清单类型：

• UX 检查清单

• 安全检查清单

• 性能检查清单

• 测试检查清单

---

步骤 4：分解为任务

命令：/speckit.tasks

目的：将技术计划分解为具体的、可执行的任务列表

输入：自动读取规范和计划文档

输出：specs/[###-feature-name]/tasks.md

任务组织原则：

• 按用户故事组织：每个用户故事都有独立的任务组

• 独立可测试：每个任务都可以独立完成和测试

• 依赖关系清晰：明确任务的执行顺序

• 支持并行：标记可以并行执行的任务

任务格式：

- [ ] T001 创建项目结构
- [ ] T002 [P] 实现认证中间件
- [ ] T003 [US1] 创建用户模型

格式说明：

• - [ ]：复选框

• T001：任务 ID（按执行顺序）

• [P]：可并行执行（可选）

• [US1]：用户故事标签（用户故事阶段必需）

• 描述：清晰的行动和文件路径

阶段结构：

1. 阶段 1：设置（项目初始化）

2. 阶段 2：基础（阻塞前提条件）

3. 阶段 3+：用户故事（按优先级）

4. 最终阶段：完善和跨领域关注点

---

步骤 4.5（可选）：一致性分析

命令：/speckit.analyze

目的：跨工件一致性和对齐报告

何时使用：

• 在 /speckit.tasks 之后

• 在 /speckit.implement 之前

输出：一致性分析报告

分析内容：

• 规范与计划的一致性

• 计划与任务的一致性

• 跨工件对齐检查

• 潜在问题识别

---

步骤 5：执行实现

命令：/speckit.implement

目的：按照任务列表执行所有任务，构建功能

输入：自动读取任务列表和相关文档

执行规则：

• 按阶段执行：完成每个阶段后再进入下一个

• 尊重依赖：按顺序执行顺序任务，并行任务可以一起执行

• TDD 方法：如果需要，先执行测试任务

• 基于文件的协调：影响同一文件的任务必须按顺序执行

• 验证检查点：在继续之前验证每个阶段的完成

实现规则：

1. 设置优先：初始化项目结构、依赖、配置

2. 测试先行：如果需要，先编写测试

3. 核心开发：实现模型、服务、命令、端点

4. 集成工作：数据库连接、中间件、日志、外部服务

5. 完善和验证：单元测试、性能优化、文档

进度跟踪：

• 每个完成的任务后报告进度

• 如果任何非并行任务失败，则停止执行

• 对于并行任务 [P]，继续成功的任务，报告失败的任务

• 提供清晰的错误消息和调试上下文

• 重要：对于已完成的任务，确保在任务文件中将其标记为 [X]

完成验证：

• 验证所有必需任务已完成

• 检查实现的功能是否与原始规范匹配

• 验证测试通过且覆盖率满足要求

• 确认实现遵循技术计划

• 报告最终状态和已完成工作的摘要

---

命令详解

/speckit.constitution

描述：创建或更新项目原则

语法：

/speckit.constitution [原则描述]

参数：

• 原则描述（可选）：项目原则的描述

输出：

• 更新 .specify/memory/constitution.md

工作流程：

1. 加载现有原则（如果存在）

2. 收集/推导占位符的值

3. 起草更新的原则内容

4. 一致性传播检查清单

5. 生成同步影响报告

6. 验证最终输出

7. 写回原则文件

8. 输出最终摘要

示例：

/speckit.constitution 创建一个注重代码质量、测试标准、
用户体验一致性和性能要求的项目原则

---

/speckit.specify

描述：从自然语言功能描述创建或更新功能规范

语法：

/speckit.specify <功能描述>

参数：

• 功能描述（必需）：要构建的功能的自然语言描述

输出：

• 新的功能分支

• specs/[###-feature-name]/spec.md

• specs/[###-feature-name]/checklists/requirements.md

工作流程：

1. 生成简洁的短名称（2-4 个词）

2. 创建功能分支

3. 加载规范模板

4. 执行规范工作流程

5. 写入规范文件

6. 规范质量验证

7. 报告完成情况

示例：

/speckit.specify 构建一个待办事项应用，用户可以添加、编辑、
删除和标记完成待办事项。待办事项应该按优先级分类（高、中、低）。

关键原则：

• 专注于"什么"和"为什么"

• 不要涉及"如何实现"

• 从用户视角描述

• 确保可测试和可测量

---

/speckit.clarify

描述：通过结构化问题澄清规范需求

语法：

/speckit.clarify

输出：结构化的问题和选项

何时使用：

• 规范中有不明确的地方

• 需要做出重要决策

• 有多个合理的解释

示例输出：

## 问题 1：数据存储方式

**上下文**：应用需要支持本地存储

**需要知道**：使用哪种本地存储方式？

**建议答案**：

| 选项 | 答案 | 影响 |
|------|------|------|
| A | localStorage | 简单易用，但容量有限 |
| B | IndexedDB | 容量大，但 API 复杂 |
| C | SQLite | 功能强大，但需要额外库 |

**您的选择**：_

---

/speckit.plan

描述：执行实现计划工作流程，使用计划模板生成设计工件

语法：

/speckit.plan [技术栈描述]

参数：

• 技术栈描述（可选）：技术栈和架构选择的描述

输出：

• specs/[###-feature-name]/plan.md

• specs/[###-feature-name]/research.md

• specs/[###-feature-name]/data-model.md

• specs/[###-feature-name]/quickstart.md

• specs/[###-feature-name]/contracts/

工作流程：

1. 设置：运行设置脚本并解析 JSON

2. 加载上下文：读取功能规范和原则

3. 执行计划工作流程

4. 阶段 0：生成研究文档

5. 阶段 1：生成数据模型、契约、快速开始

6. 更新代理上下文

7. 重新评估原则检查

8. 停止并报告

示例：

/speckit.plan 应用使用原生 HTML、CSS 和 JavaScript，
不依赖任何框架。使用 localStorage 进行数据持久化。

---

/speckit.checklist

描述：生成质量检查清单以验证需求的完整性、清晰度和一致性

语法：

/speckit.checklist

输出：specs/[###-feature-name]/checklists/

检查清单类型：

• UX 检查清单

• 安全检查清单

• 性能检查清单

• 测试检查清单

---

/speckit.tasks

描述：基于可用的设计工件，为功能生成可操作的、按依赖关系排序的任务列表

语法：

/speckit.tasks

输出：specs/[###-feature-name]/tasks.md

工作流程：

1. 预执行检查（扩展钩子）

2. 设置：运行检查前提条件脚本

3. 加载设计文档

4. 执行任务生成工作流程

5. 生成 tasks.md

6. 报告

7. 检查扩展钩子

任务生成规则：

• 按用户故事组织：每个用户故事都有独立的任务组

• 独立可测试：每个任务都可以独立完成和测试

• 依赖关系清晰：明确任务的执行顺序

• 支持并行：标记可以并行执行的任务

任务格式：

- [ ] T001 创建项目结构
- [ ] T002 [P] 实现认证中间件
- [ ] T003 [US1] 创建用户模型

---

/speckit.analyze

描述：运行项目一致性分析

语法：

/speckit.analyze

输出：一致性分析报告

分析内容：

• 规范与计划的一致性

• 计划与任务的一致性

• 跨工件对齐检查

• 潜在问题识别

---

/speckit.implement

描述：通过处理和执行 tasks.md 中定义的所有任务来执行实现计划

语法：

/speckit.implement

工作流程：

1. 预执行检查（扩展钩子）

2. 检查检查清单状态

3. 加载和分析实现上下文

4. 项目设置验证

5. 解析 tasks.md 结构

6. 按任务计划执行实现

7. 实现执行规则

8. 进度跟踪和错误处理

9. 完成验证

10. 检查扩展钩子

执行规则：

• 按阶段执行：完成每个阶段后再进入下一个

• 尊重依赖：按顺序执行顺序任务，并行任务可以一起执行

• TDD 方法：如果需要，先执行测试任务

• 基于文件的协调：影响同一文件的任务必须按顺序执行

• 验证检查点：在继续之前验证每个阶段的完成

---

实战示例

示例 1：待办事项应用

步骤 1：建立项目原则

/speckit.constitution 创建一个注重代码质量、测试标准、
用户体验一致性和性能要求的项目原则

生成的原则包含：

• 核心原则：测试优先、代码质量、性能标准

• 技术约束：使用原生技术、响应式设计

• 开发流程：TDD、代码审查

• 治理规则：原则高于一切

---

步骤 2：创建功能规范

/speckit.specify 构建一个待办事项应用，用户可以添加、编辑、
删除和标记完成待办事项。待办事项应该按优先级分类（高、中、低）。
应用需要支持本地存储，数据不会上传到服务器。
界面简洁易用，支持移动端访问。

生成的规范包含：

用户故事 1 - 添加待办事项（优先级：P1）

• 用户可以创建新的待办事项

• 用户可以设置待办事项的优先级

• 待办事项保存到本地存储

用户故事 2 - 管理待办事项（优先级：P2）

• 用户可以编辑待办事项

• 用户可以删除待办事项

• 用户可以标记待办事项为完成

用户故事 3 - 筛选和排序（优先级：P3）

• 用户可以按优先级筛选待办事项

• 用户可以按完成状态筛选待办事项

成功标准：

• 用户可以在 30 秒内添加一个待办事项

• 应用支持 1000+ 待办事项而不降低性能

• 95% 的用户在第一次尝试时成功完成主要任务

---

步骤 3：创建技术计划

/speckit.plan 应用使用原生 HTML、CSS 和 JavaScript，
不依赖任何框架。使用 localStorage 进行数据持久化。
采用响应式设计，支持移动端和桌面端。
遵循渐进增强原则，确保基本功能在所有浏览器中可用。

生成的计划包含：

技术上下文：

• 语言/版本：原生 JavaScript (ES6+)

• 主要依赖：无

• 存储：localStorage

• 测试：Jest

• 目标平台：现代浏览器

• 性能目标：<100ms 响应时间

• 约束：<5MB 存储空间

• 规模：1000+ 待办事项

项目结构：

src/
├── models/
│   └── todo.js
├── services/
│   └── storage.js
├── ui/
│   ├── components/
│   └── views/
└── app.js

tests/
├── unit/
└── integration/

数据模型：

• Todo：id, title, priority, completed, createdAt, updatedAt

---

步骤 4：分解为任务

/speckit.tasks

生成的任务包含：

阶段 1：设置

• T001 创建项目结构

• T002 初始化 package.json

• T003 配置 Jest 测试框架

• T004 [P] 创建基础 HTML 模板

• T005 [P] 创建基础 CSS 样式

阶段 2：基础

• T006 实现 localStorage 服务

• T007 实现 Todo 模型

• T008 [P] 创建单元测试框架

阶段 3：用户故事 1 - 添加待办事项

• T009 [US1] 创建待办事项表单组件

• T010 [US1] 实现添加待办事项功能

• T011 [US1] [P] 编写添加待办事项测试

• T012 [US1] 实现优先级选择器

阶段 4：用户故事 2 - 管理待办事项

• T013 [US2] 实现编辑待办事项功能

• T014 [US2] 实现删除待办事项功能

• T015 [US2] 实现标记完成功能

• T016 [US2] [P] 编写管理待办事项测试

阶段 5：用户故事 3 - 筛选和排序

• T017 [US3] 实现优先级筛选

• T018 [US3] 实现完成状态筛选

• T019 [US3] [P] 编写筛选功能测试

阶段 6：完善

• T020 实现响应式设计

• T021 添加错误处理

• T022 性能优化

• T023 编写集成测试

• T024 文档编写

---

步骤 5：执行实现

/speckit.implement

执行过程：

1. 按阶段执行任务

2. 遵循 TDD 方法

3. 验证每个阶段的完成

4. 报告进度和错误

5. 完成验证

---

示例 2：照片相册应用

步骤 1：建立项目原则

/speckit.constitution 创建一个注重代码质量、测试标准、
用户体验一致性和性能要求的项目原则

---

步骤 2：创建功能规范

/speckit.specify 构建一个照片相册应用，可以按日期组织照片到
不同的相册中。相册可以在主页上通过拖放重新组织。
相册不能嵌套在其他相册中。在每个相册内，照片以平铺界面预览。

用户故事：

• 用户故事 1（P1）：创建和管理相册

• 用户故事 2（P2）：上传和组织照片

• 用户故事 3（P3）：拖放重新组织相册

---

步骤 3：创建技术计划

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

---

步骤 4：分解为任务

/speckit.tasks

---

步骤 5：执行实现

/speckit.implement

---

最佳实践

1. 规范编写最佳实践

做什么

• 专注于用户价值：描述用户能获得什么价值

• 使用清晰的语言：避免技术术语

• 提供上下文：解释为什么需要这个功能

• 定义成功标准：使用可测量的指标

• 考虑边界情况：识别边缘情况和错误场景

避免什么

• 不要涉及实现细节：不要提及具体技术、框架或 API

• 不要使用模糊语言：避免"应该"、"可能"等词

• 不要过度设计：专注于核心功能

• 不要忽略约束：明确时间和资源限制

示例对比

不好：

用户可以使用 React 组件创建待办事项，
数据存储在 MongoDB 中，通过 REST API 访问。

好：

用户可以创建待办事项，设置优先级，
并查看所有待办事项列表。数据保存在本地，
无需网络连接即可使用。

---

2. 用户故事编写最佳实践

用户故事格式

### 用户故事 N - [简短标题]（优先级：Pn）

[用通俗语言描述这个用户旅程]

**为什么这个优先级**：[解释价值和为什么有这个优先级]

**独立测试**：[描述如何独立测试]

**验收场景**：

1. **给定** [初始状态]，**当** [动作]，**那么** [预期结果]
2. **给定** [初始状态]，**当** [动作]，**那么** [预期结果]

关键原则

1. 独立可测试：每个用户故事都可以独立开发和测试

2. 按优先级排序：P1、P2、P3 等

3. 用户导向：从用户视角描述

4. 可交付：每个故事都是可用的功能增量

示例

### 用户故事 1 - 添加待办事项（优先级：P1）

用户可以创建新的待办事项，设置标题和优先级，
并将其保存到本地存储中。

**为什么这个优先级**：这是应用的核心功能，
没有它用户无法使用应用。

**独立测试**：可以通过创建待办事项并验证它出现在列表中来测试。

**验收场景**：

1. **给定** 用户在主页，**当** 用户点击"添加"按钮
   并输入标题和优先级，**那么** 新的待办事项出现在列表中
2. **给定** 用户添加了待办事项，**当** 用户刷新页面，
   **那么** 待办事项仍然存在

---

3. 成功标准编写最佳实践

成功标准的特点

1. 可测量：包含具体指标（时间、百分比、计数、速率）

2. 技术无关：不提及框架、语言、数据库或工具

3. 用户导向：从用户/业务角度描述结果，而不是系统内部

4. 可验证：可以在不知道实现细节的情况下测试/验证

好的示例

• “用户可以在 3 分钟内完成结账”

• “系统支持 10,000 个并发用户”

• “95% 的搜索在 1 秒内返回结果”

• “任务完成率提高 40%”

不好的示例（实现导向）

• “API 响应时间在 200ms 以下”（太技术化）

• “数据库可以处理 1000 TPS”（实现细节）

• “React 组件渲染高效”（框架特定）

• “Redis 缓存命中率超过 80%”（技术特定）

---

4. 任务分解最佳实践

任务格式

- [ ] T001 创建项目结构
- [ ] T002 [P] 实现认证中间件
- [ ] T003 [US1] 创建用户模型

格式说明

1. 复选框：始终以 - [ ] 开头

2. 任务 ID：顺序编号（T001, T002, T003…）

3. [P] 标记：仅在任务可并行执行时包含

4. [Story] 标签：用户故事阶段任务必需

   • 格式：[US1], [US2], [US3] 等

   • 设置阶段：无故事标签

   • 基础阶段：无故事标签

   • 用户故事阶段：必须有故事标签

   • 完善阶段：无故事标签

5. 描述：清晰的操作和精确的文件路径

示例

• 正确：- [ ] T001 创建项目结构

• 正确：- [ ] T005 [P] 在 src/middleware/auth.py 中实现认证中间件

• 正确：- [ ] T012 [P] [US1] 在 src/models/user.py 中创建用户模型

• 正确：- [ ] T014 [US1] 在 src/services/user_service.py 中实现 UserService

• 错误：- [ ] 创建用户模型（缺少 ID 和故事标签）

• 错误：T001 [US1] 创建模型（缺少复选框）

• 错误：- [ ] [US1] 创建用户模型（缺少任务 ID）

• 错误：- [ ] T001 [US1] 创建模型（缺少文件路径）

---

5. 项目原则编写最佳实践

原则文档结构

# [项目名称] 原则

## 核心原则

### [原则 1 名称]
[原则描述]

### [原则 2 名称]
[原则描述]

## [其他部分]

[内容]

## 治理

[治理规则]

**版本**：[版本号] | **批准**：[日期] | **最后修改**：[日期]

关键原则

1. 清晰明确：每个原则都应该清晰、具体

2. 可测试：原则应该是可验证的

3. 有限数量：不要有太多原则（5-7 个最佳）

4. 优先级排序：最重要的原则在前

5. 可执行：每个原则都应该能指导具体行动

示例

# 待办事项应用原则

## 核心原则

### I. 测试优先（不可协商）
TDD 强制：先编写测试 → 用户批准 → 测试失败 → 然后实现
严格遵循红-绿-重构循环

### II. 代码质量
所有代码必须通过 ESLint 检查
代码覆盖率必须达到 80% 以上
所有公共 API 必须有文档

### III. 用户体验
所有操作响应时间 < 100ms
界面必须在所有现代浏览器中一致
支持键盘导航

### IV. 性能
应用必须支持 1000+ 待办事项
页面加载时间 < 2s
内存使用 < 50MB

## 治理

原则高于所有其他实践
修改需要文档、批准和迁移计划
所有 PR/审查必须验证合规性

**版本**：1.0.0 | **批准**：2025-03-17 | **最后修改**：2025-03-17

---

6. 技术计划编写最佳实践

技术上下文

**语言/版本**：Python 3.11
**主要依赖**：FastAPI, SQLAlchemy
**存储**：PostgreSQL
**测试**：pytest
**目标平台**：Linux 服务器
**项目类型**：Web 服务
**性能目标**：1000 req/s
**约束**：<200ms p95, <100MB 内存
**规模/范围**：10k 用户, 50 端点

项目结构

选择适合项目类型的结构：

选项 1：单个项目（默认）

src/
├── models/
├── services/
├── cli/
└── lib/

tests/
├── contract/
├── integration/
└── unit/

选项 2：Web 应用

backend/
├── src/
│   ├── models/
│   ├── services/
│   └── api/
└── tests/

frontend/
├── src/
│   ├── components/
│   ├── pages/
│   └── services/
└── tests/

---

7. 开发流程最佳实践

增量交付

1. 从小开始：先实现 MVP（最小可行产品）

2. 持续验证：每个阶段都要验证是否符合规范

3. 快速反馈：尽早获得用户反馈

4. 迭代改进：根据反馈持续改进

文档驱动

1. 规范先行：在写任何代码之前，先明确要构建什么

2. 技术无关：在规范阶段不要考虑具体技术实现

3. 增量交付：每个用户故事都是独立可测试的

4. 质量保证：通过检查清单确保质量

团队协作

1. 共同语言：规范成为团队的共同语言

2. 知识共享：所有决策都有文档记录

3. 代码审查：基于原则和规范进行审查

4. 持续改进：定期回顾和改进流程

---

常见问题

Q1：Spec Kit 适合什么类型的项目？

A：Spec Kit 适合各种类型的项目：

• Web 应用

• 移动应用

• 桌面应用

• CLI 工具

• 库和框架

• API 服务

• 数据处理管道

不太适合：

• 非常小的脚本（<100 行）

• 一次性任务

• 探索性/实验性项目

---

Q2：我必须使用所有命令吗？

A：不是。核心流程是：

必需的命令：

1. /speckit.constitution（仅一次，项目开始时）

2. /speckit.specify（每个功能）

3. /speckit.plan（每个功能）

4. /speckit.tasks（每个功能）

5. /speckit.implement（每个功能）

可选的命令：

• /speckit.clarify（当需要澄清需求时）

• /speckit.checklist（当需要质量检查时）

• /speckit.analyze（当需要一致性分析时）

---

Q3：规范中应该包含多少细节？

A：规范的详细程度取决于项目的复杂性和团队的经验。

一般原则：

• 足够详细以便 AI 理解

• 足够清晰以便测试

• 足够完整以便实现

• 不要过度设计

• 不要包含实现细节

经验法则：

• 小项目：5-10 个用户故事

• 中等项目：10-20 个用户故事

• 大型项目：20+ 个用户故事（考虑拆分）

---

Q4：如何处理需求变更？

A：Spec Kit 支持迭代和变更：

变更流程：

1. 更新功能规范（spec.md）

2. 重新运行 /speckit.plan（如果技术栈变更）

3. 重新运行 /speckit.tasks（生成新任务）

4. 继续执行 /speckit.implement

最佳实践：

• 在实现之前尽早发现变更

• 记录变更的原因和影响

• 更新相关文档

• 通知团队成员

---

Q5：如何确保代码质量？

A：Spec Kit 通过多种方式确保代码质量：

项目原则：

• 定义质量标准

• 指导开发决策

• 作为审查依据

检查清单：

• /speckit.checklist 生成质量检查清单

• 验证需求完整性

• 确保一致性

任务分解：

• 每个任务都可独立完成

• 支持并行开发

• 清晰的验收标准

实现验证：

• 按阶段执行

• 验证每个阶段

• 报告错误和问题

---

Q6：如何与现有项目集成？

A：Spec Kit 可以与现有项目集成：

集成步骤：

1. 在项目根目录运行 specify init . --ai generic --ai-commands-dir .trae/commands/

2. 创建项目原则（/speckit.constitution）

3. 为新功能创建规范（/speckit.specify）

4. 继续正常工作流程

注意事项：

• 现有代码可能需要重构以符合原则

• 可能需要更新项目结构

• 考虑增量迁移

---

Q7：如何处理技术债务？

A：Spec Kit 帮助管理技术债务：

预防：

• 项目原则定义质量标准

• 技术计划考虑长期维护

• 任务分解确保可测试性

识别：

• /speckit.analyze 识别不一致性

• 检查清单验证质量

• 代码审查基于原则

解决：

• 为技术债务创建专门的用户故事

• 优先级排序（P1、P2、P3）

• 增量偿还

---

Q8：如何与团队协作？

A：Spec Kit 支持团队协作：

共同语言：

• 规范成为团队的共同语言

• 用户故事统一理解

• 原则指导决策

版本控制：

• 所有文档都在 Git 中

• 分支支持并行开发

• PR 审查基于规范

角色分工：

• 产品经理：/speckit.specify

• 架构师：/speckit.plan

• 开发者：/speckit.tasks 和 /speckit.implement

• QA：检查清单和测试

---

Q9：如何学习 Spec Kit？

A：学习 Spec Kit 的建议路径：

初学者：

1. 阅读本文档

2. 在测试项目中练习

3. 从小项目开始

4. 逐步增加复杂性

有经验者：

1. 深入理解核心概念

2. 自定义模板和检查清单

3. 集成到现有项目

4. 分享最佳实践

团队：

1. 建立团队原则

2. 统一工作流程

3. 定期回顾和改进

4. 培训新成员

---

Q10：Spec Kit 的限制是什么？

A：Spec Kit 的一些限制：

学习曲线：

• 需要理解规范驱动开发

• 需要学习工作流程

• 需要适应新思维

前期投入：

• 需要时间创建规范

• 需要时间建立原则

• 需要时间分解任务

灵活性：

• 规范驱动可能感觉僵化

• 变更需要更新文档

• 可能不适合快速原型

适用性：

• 不适合非常小的项目

• 不适合探索性项目

• 不适合一次性任务

---

更多资源

官方资源

• GitHub 仓库：https://github.com/github/spec-kit

• 官方文档：https://github.github.io/spec-kit/

• 发布说明：https://github.com/github/spec-kit/blob/main/CHANGELOG.md

社区资源

• 社区演练：

  • .NET CLI 工具

  • Spring Boot + React 平台

  • ASP.NET CMS 扩展

  • Java 运行时扩展

  • Go/React 仪表板

学习路径

1. 入门：阅读本文档，理解核心概念

2. 实践：在测试项目中练习完整工作流程

3. 深入：研究模板和命令实现

4. 应用：在实际项目中使用 Spec Kit

5. 分享：分享经验和最佳实践

---

总结

Spec Kit 是一个强大的规范驱动开发工具，它通过"规范→计划→任务→实现"的结构化流程，帮助团队构建高质量的软件。

关键要点：

1. 规范先行：在写任何代码之前，先明确要构建什么

2. 技术无关：在规范阶段专注于"什么"和"为什么"

3. 增量交付：每个用户故事都是独立可测试的

4. 质量保证：通过原则、检查清单和验证确保质量

5. 团队协作：规范成为团队的共同语言

开始使用：

1. 初始化项目：uvx --from git+https://github.com/github/spec-kit.git specify init <项目名> --ai generic --ai-commands-dir .trae/commands/

2. 创建原则：/speckit.constitution

3. 创建规范：/speckit.specify <功能描述>

4. 创建计划：/speckit.plan <技术栈>

5. 分解任务：/speckit.tasks

6. 执行实现：/speckit.implement

持续改进：

• 定期回顾工作流程

• 根据经验调整原则

• 分享最佳实践

• 帮助团队学习

祝您使用 Spec Kit 构建出高质量的软件！

[用户18]

你为什么能把帖子写的那么长？