Initial TrueGrowth source import
This commit is contained in:
815
docs/SPEC_KIT_BEST_PRACTICES.md
Normal file
815
docs/SPEC_KIT_BEST_PRACTICES.md
Normal file
@@ -0,0 +1,815 @@
|
||||
# Spec-Kit 最佳实践指南
|
||||
|
||||
本文档介绍如何在 Opentu 项目中使用 GitHub Spec-Kit 进行规范驱动开发(Spec-Driven Development, SDD)。
|
||||
|
||||
## 目录
|
||||
|
||||
- [什么是 Spec-Kit](#什么是-spec-kit)
|
||||
- [核心理念](#核心理念)
|
||||
- [安装与设置](#安装与设置)
|
||||
- [工作流程](#工作流程)
|
||||
- [Monorepo 项目配置](#monorepo-项目配置)
|
||||
- [最佳实践](#最佳实践)
|
||||
- [常见问题](#常见问题)
|
||||
|
||||
## 什么是 Spec-Kit
|
||||
|
||||
Spec-Kit 是 GitHub 开源的规范驱动开发工具包,它将传统的"先编码后写文档"流程倒置为"先写规范后生成代码"。规范成为项目的真实来源(source of truth),AI 工具根据规范生成、测试和验证代码。
|
||||
|
||||
### 核心组件
|
||||
|
||||
1. **Specify CLI** - 用于初始化项目和下载模板的命令行工具
|
||||
2. **模板和脚本** - 预设的规范模板和辅助脚本
|
||||
3. **AI 集成** - 支持 Claude Code、GitHub Copilot、Gemini CLI 等 AI 编码助手
|
||||
|
||||
### 支持的 AI 工具
|
||||
|
||||
- Claude Code (推荐用于 Opentu 项目)
|
||||
- GitHub Copilot
|
||||
- Gemini CLI
|
||||
- Cursor
|
||||
- 其他兼容的 AI 编码助手
|
||||
|
||||
## 核心理念
|
||||
|
||||
### 规范驱动开发的优势
|
||||
|
||||
1. **意图优先** - 从"做什么"和"为什么"开始,而不是"怎么做"
|
||||
2. **清晰性** - 在编码前就明确需求和架构决策
|
||||
3. **活文档** - 规范与代码同步演进,始终保持最新
|
||||
4. **人机协作** - 人类负责战略决策,AI 负责执行实现
|
||||
5. **早期验证** - 在多个检查点捕获需求偏差,避免后期返工
|
||||
|
||||
### 何时使用 Spec-Kit
|
||||
|
||||
**✅ 推荐使用:**
|
||||
- 为现有系统添加新功能
|
||||
- 复杂的功能开发需要架构决策
|
||||
- 团队协作需要明确的需求文档
|
||||
- 需要保持代码与文档同步
|
||||
|
||||
**❌ 不建议使用:**
|
||||
- 简单的 bug 修复
|
||||
- 样式微调
|
||||
- 配置文件更新
|
||||
- 一次性实验性代码
|
||||
|
||||
## 安装与设置
|
||||
|
||||
### 前置要求
|
||||
|
||||
```bash
|
||||
# 检查 Python 版本 (需要 3.11+)
|
||||
python --version
|
||||
|
||||
# 检查 Git
|
||||
git --version
|
||||
|
||||
# 安装 uv 包管理器
|
||||
curl -LsSf https://astral.sh/uv/install.sh | sh
|
||||
```
|
||||
|
||||
### 初始化 Spec-Kit
|
||||
|
||||
```bash
|
||||
# 在项目根目录执行
|
||||
npx @github/specify init
|
||||
|
||||
# 或使用 Python 包
|
||||
pip install github-specify
|
||||
specify init
|
||||
```
|
||||
|
||||
这将创建 `.specify/` 目录结构:
|
||||
|
||||
```
|
||||
.specify/
|
||||
├── memory/
|
||||
│ └── constitution.md # 项目宪章(非常重要!)
|
||||
├── specifications/ # 功能规范文档
|
||||
├── plans/ # 实现计划
|
||||
└── tasks/ # 任务列表
|
||||
```
|
||||
|
||||
## 快速开始 - Specify 命令步骤流程
|
||||
|
||||
### 完整开发周期命令序列
|
||||
|
||||
```bash
|
||||
# 0. 前置准备 - 初始化项目
|
||||
npx @github/specify init
|
||||
|
||||
# 在 Claude Code 中按顺序执行以下 slash 命令:
|
||||
|
||||
# 1. 建立宪章 (一次性,项目级)
|
||||
/speckit.constitution
|
||||
|
||||
# 2. 编写功能规范 (每个新功能)
|
||||
/speckit.specify
|
||||
|
||||
# 3. (可选)澄清不明确的需求
|
||||
/speckit.clarify
|
||||
|
||||
# 4. 制定实现计划
|
||||
/speckit.plan
|
||||
|
||||
# 5. 生成任务清单
|
||||
/speckit.tasks
|
||||
|
||||
# 6. (可选)分析一致性
|
||||
/speckit.analyze
|
||||
|
||||
# 7. (可选)生成验收检查清单
|
||||
/speckit.checklist
|
||||
|
||||
# 8. 执行实现
|
||||
/speckit.implement
|
||||
|
||||
# 9. (可选)将任务转换为 GitHub Issues
|
||||
/speckit.taskstoissues
|
||||
```
|
||||
|
||||
### 命令详解
|
||||
|
||||
| 命令 | 用途 | 执行时机 | 输出文件 |
|
||||
|------|------|---------|---------|
|
||||
| `/speckit.constitution` | 定义项目宪章和开发原则 | 项目初期(一次性) | `.specify/memory/constitution.md` |
|
||||
| `/speckit.specify` | 编写功能规范(what & why) | 每个新功能开始前 | `.specify/specifications/{feature}.md` |
|
||||
| `/speckit.clarify` | 识别并澄清规范中的不明确之处 | 规范编写后(可选) | 更新 `.specify/specifications/{feature}.md` |
|
||||
| `/speckit.plan` | 制定技术实现方案(how) | 规范确认后 | `.specify/plans/{feature}-plan.md` |
|
||||
| `/speckit.tasks` | 分解为可执行任务 | 计划制定后 | `.specify/tasks/{feature}-tasks.md` |
|
||||
| `/speckit.analyze` | 检查规范/计划/任务的一致性 | 任务生成后(可选) | 分析报告 |
|
||||
| `/speckit.checklist` | 生成验收检查清单 | 实现前(可选) | 自定义检查清单 |
|
||||
| `/speckit.implement` | AI 执行任务实现 | 任务清单确认后 | 实际代码文件 |
|
||||
| `/speckit.taskstoissues` | 将任务转换为 GitHub Issues | 团队协作场景(可选) | GitHub Issues |
|
||||
|
||||
### 典型工作流示例
|
||||
|
||||
#### 场景 1: 首次使用(新项目)
|
||||
|
||||
```bash
|
||||
# Step 1: 初始化
|
||||
cd /path/to/aitu
|
||||
npx @github/specify init
|
||||
|
||||
# Step 2: 在 Claude Code 中
|
||||
/speckit.constitution
|
||||
# AI 会引导你定义项目宪章,你可以基于现有的 CODING_STANDARDS.md
|
||||
|
||||
# Step 3: 开发第一个功能
|
||||
/speckit.specify
|
||||
# 描述: "添加图片圆形裁剪功能"
|
||||
|
||||
/speckit.plan
|
||||
# AI 制定技术方案
|
||||
|
||||
/speckit.tasks
|
||||
# AI 生成任务列表
|
||||
|
||||
/speckit.implement
|
||||
# AI 开始实现
|
||||
```
|
||||
|
||||
#### 场景 2: 日常功能开发
|
||||
|
||||
```bash
|
||||
# 直接跳过 constitution(已存在)
|
||||
|
||||
# Step 1: 写规范
|
||||
/speckit.specify
|
||||
# 输入: "用户可以导出白板为 PDF 格式"
|
||||
|
||||
# Step 2: (可选)澄清
|
||||
/speckit.clarify
|
||||
# AI 提问: "PDF 导出是否包含注释?", "是否支持分页?"等
|
||||
# 你回答后,AI 更新规范
|
||||
|
||||
# Step 3: 制定计划
|
||||
/speckit.plan
|
||||
|
||||
# Step 4: 生成任务
|
||||
/speckit.tasks
|
||||
|
||||
# Step 5: (可选)分析一致性
|
||||
/speckit.analyze
|
||||
# AI 检查规范、计划、任务是否一致
|
||||
|
||||
# Step 6: 实现
|
||||
/speckit.implement
|
||||
```
|
||||
|
||||
#### 场景 3: 团队协作
|
||||
|
||||
```bash
|
||||
# 产品经理/技术负责人
|
||||
/speckit.specify
|
||||
/speckit.plan
|
||||
/speckit.tasks
|
||||
|
||||
# 转换为 GitHub Issues
|
||||
/speckit.taskstoissues
|
||||
# 团队成员可以在 GitHub 上认领任务
|
||||
|
||||
# 开发团队成员
|
||||
# 直接使用 GitHub Issues 进行开发
|
||||
# 或者再次运行 /speckit.implement 自动实现
|
||||
```
|
||||
|
||||
### 工作流检查点
|
||||
|
||||
```
|
||||
┌─────────────────┐
|
||||
│ Constitution │ ← 项目宪章(一次性)
|
||||
└────────┬────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ Specify │ ← 功能规范(每个功能)
|
||||
└────────┬────────┘
|
||||
│
|
||||
├──→ [Clarify] (可选澄清)
|
||||
│
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ Plan │ ← 技术方案
|
||||
└────────┬────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ Tasks │ ← 任务分解
|
||||
└────────┬────────┘
|
||||
│
|
||||
├──→ [Analyze] (可选分析)
|
||||
├──→ [Checklist] (可选检查清单)
|
||||
├──→ [TasksToIssues] (可选团队协作)
|
||||
│
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ Implement │ ← AI 执行实现
|
||||
└─────────────────┘
|
||||
│
|
||||
▼
|
||||
[Code Review]
|
||||
│
|
||||
▼
|
||||
[Merge & Deploy]
|
||||
```
|
||||
|
||||
## 工作流程
|
||||
|
||||
Spec-Kit 遵循五阶段工作流,每个阶段都有明确的检查点:
|
||||
|
||||
### 1. 建立宪章 (Constitution)
|
||||
|
||||
**命令:** `/speckit.constitution`
|
||||
|
||||
宪章是项目的"根本大法",定义不可妥协的原则和标准。
|
||||
|
||||
**Opentu 项目宪章示例:**
|
||||
|
||||
```markdown
|
||||
# Opentu 项目宪章
|
||||
|
||||
## 代码质量原则
|
||||
|
||||
### 文件大小限制
|
||||
- 单个文件不超过 500 行代码(包括空行和注释)
|
||||
- 超过限制必须进行合理拆分
|
||||
|
||||
### TypeScript 规范
|
||||
- 必须使用严格的 TypeScript 配置
|
||||
- 禁止使用 `any` 类型,使用具体类型或泛型
|
||||
- 所有组件 Props 必须有类型定义
|
||||
|
||||
### 架构约定
|
||||
- 使用插件化架构(`withXxx` 模式)
|
||||
- React 组件必须使用函数式组件和 Hooks
|
||||
- 状态管理优先使用 React Context
|
||||
|
||||
### UI/UX 规范
|
||||
- UI 组件必须使用 TDesign React (light 主题)
|
||||
- Tooltip 统一使用 `theme='light'`
|
||||
- 遵循品牌色彩系统(橙金色 #F39C12、蓝紫色 #5A4FCF)
|
||||
|
||||
### 测试要求
|
||||
- 所有新功能必须包含单元测试
|
||||
- 测试覆盖率不低于 80%
|
||||
- 提交前必须通过类型检查和测试
|
||||
|
||||
### Git 提交规范
|
||||
- 遵循 Conventional Commits: `<type>(<scope>): <subject>`
|
||||
- 类型: feat, fix, docs, style, refactor, test, chore, perf, ci
|
||||
|
||||
### 性能要求
|
||||
- 大组件必须使用 React.lazy 进行代码分割
|
||||
- 图片必须使用懒加载
|
||||
- 长列表必须考虑虚拟化
|
||||
|
||||
### 安全原则
|
||||
- 所有用户输入必须验证和清理
|
||||
- 不得硬编码敏感信息
|
||||
- API 调用必须有安全的错误处理
|
||||
```
|
||||
|
||||
**最佳实践:**
|
||||
- 基于现有的 `CODING_STANDARDS.md` 提炼核心原则
|
||||
- 宪章应该简洁(1-2 页),只包含非妥协性原则
|
||||
- 定期审查和更新宪章
|
||||
|
||||
### 2. 编写规范 (Specification)
|
||||
|
||||
**命令:** `/speckit.specify`
|
||||
|
||||
规范聚焦于"做什么"和"为什么",避免过早陷入技术细节。
|
||||
|
||||
**好的规范示例:**
|
||||
|
||||
```markdown
|
||||
# 规范: 图片圆形裁剪功能
|
||||
|
||||
## 背景
|
||||
用户在插入图片后,只能使用方形裁剪,无法创建圆形或椭圆形的图片效果,
|
||||
限制了设计创意。
|
||||
|
||||
## 目标
|
||||
为用户提供三种图片裁剪形状选项:方形、圆形、椭圆形。
|
||||
|
||||
## 用户故事
|
||||
作为白板用户,我希望能够:
|
||||
1. 选中画布上的图片
|
||||
2. 点击工具栏的"裁剪"按钮
|
||||
3. 在弹出菜单中选择裁剪形状(方形/圆形/椭圆形)
|
||||
4. 看到图片以选定形状显示
|
||||
|
||||
## 功能需求
|
||||
- FR1: 在图片选中时显示裁剪按钮
|
||||
- FR2: 提供三种裁剪形状选项
|
||||
- FR3: 裁剪后保持图片质量
|
||||
- FR4: 支持撤销/重做操作
|
||||
|
||||
## 非功能需求
|
||||
- NFR1: 裁剪操作响应时间 < 200ms
|
||||
- NFR2: 裁剪不影响原始图片文件
|
||||
- NFR3: 支持移动端触摸操作
|
||||
|
||||
## 成功标准
|
||||
- 用户可以成功应用三种裁剪形状
|
||||
- E2E 测试通过
|
||||
- 符合品牌设计规范
|
||||
```
|
||||
|
||||
**❌ 避免在规范阶段:**
|
||||
- 指定具体的技术实现(如"使用 canvas API")
|
||||
- 详细的代码结构
|
||||
- 具体的库或框架选择
|
||||
|
||||
### 3. 制定计划 (Plan)
|
||||
|
||||
**命令:** `/speckit.plan`
|
||||
|
||||
计划阶段做出技术决策,选择实现方案。
|
||||
|
||||
**计划示例:**
|
||||
|
||||
```markdown
|
||||
# 实现计划: 图片圆形裁剪功能
|
||||
|
||||
## 技术栈选择
|
||||
- 图片处理: Canvas API (浏览器原生支持)
|
||||
- 组件库: TDesign React Popup 组件
|
||||
- 状态管理: React useState + useCallback
|
||||
|
||||
## 架构方案
|
||||
|
||||
### 组件结构
|
||||
```
|
||||
components/
|
||||
├── image-crop/
|
||||
│ ├── ImageCropPopup.tsx # 裁剪菜单弹窗
|
||||
│ ├── ImageCropPopup.scss # 样式文件
|
||||
│ ├── image-crop.types.ts # 类型定义
|
||||
│ └── use-image-crop.ts # 裁剪逻辑 Hook
|
||||
```
|
||||
|
||||
### 数据流
|
||||
1. 用户选中图片 -> 触发 popup 显示
|
||||
2. 用户选择裁剪形状 -> 调用 `applyCrop(shape)`
|
||||
3. Canvas API 处理图片 -> 生成新的图片 URL
|
||||
4. 更新 Plait 节点数据
|
||||
|
||||
## 依赖项
|
||||
- 无需新增外部依赖
|
||||
- 复用现有的 Plait 插件系统
|
||||
|
||||
## 风险与缓解
|
||||
- 风险: 大图片裁剪可能卡顿
|
||||
- 缓解: 添加 loading 状态,使用 Web Worker
|
||||
|
||||
## 测试策略
|
||||
- 单元测试: 测试 `useImageCrop` Hook
|
||||
- 集成测试: 测试 ImageCropPopup 组件交互
|
||||
- E2E 测试: 测试完整的用户流程
|
||||
```
|
||||
|
||||
**最佳实践:**
|
||||
- 评估多个技术方案,说明选择理由
|
||||
- 识别技术风险和缓解策略
|
||||
- 考虑与现有系统的集成点
|
||||
|
||||
### 4. 分解任务 (Tasks)
|
||||
|
||||
**命令:** `/speckit.tasks`
|
||||
|
||||
将计划分解为可执行的小任务。
|
||||
|
||||
**任务列表示例:**
|
||||
|
||||
```markdown
|
||||
# 任务清单: 图片圆形裁剪功能
|
||||
|
||||
## Phase 1: 类型和工具函数
|
||||
- [ ] 定义 `CropShape` 类型('rectangle' | 'circle' | 'ellipse')
|
||||
- [ ] 定义 `ImageCropPopupProps` 接口
|
||||
- [ ] 实现 `cropImageToShape()` 工具函数
|
||||
|
||||
## Phase 2: 核心组件
|
||||
- [ ] 创建 `ImageCropPopup.tsx` 组件
|
||||
- [ ] 实现 `useImageCrop` Hook
|
||||
- [ ] 添加 BEM 样式 `image-crop-popup.scss`
|
||||
|
||||
## Phase 3: 集成
|
||||
- [ ] 在 popup-toolbar 中添加裁剪按钮
|
||||
- [ ] 连接到 Plait 图片节点更新逻辑
|
||||
- [ ] 添加撤销/重做支持
|
||||
|
||||
## Phase 4: 测试
|
||||
- [ ] 编写 `useImageCrop.test.ts` 单元测试
|
||||
- [ ] 编写 `ImageCropPopup.test.tsx` 组件测试
|
||||
- [ ] 编写 E2E 测试场景
|
||||
|
||||
## Phase 5: 文档和优化
|
||||
- [ ] 更新组件文档
|
||||
- [ ] 性能测试和优化
|
||||
- [ ] Code review 和修复问题
|
||||
```
|
||||
|
||||
**最佳实践:**
|
||||
- 每个任务应该可以在 2-4 小时内完成
|
||||
- 按逻辑依赖关系排序
|
||||
- 包含测试和文档任务
|
||||
|
||||
### 5. 执行实现 (Implement)
|
||||
|
||||
**命令:** `/speckit.implement`
|
||||
|
||||
AI 根据规范、计划和任务开始生成代码。
|
||||
|
||||
**工作方式:**
|
||||
1. AI 按顺序执行任务列表
|
||||
2. 生成代码并运行测试
|
||||
3. 遇到问题时暂停,寻求人类指导
|
||||
4. 完成后更新任务状态
|
||||
|
||||
**人类在循环中的角色:**
|
||||
- 审查生成的代码
|
||||
- 在检查点提供反馈
|
||||
- 解决 AI 无法处理的设计决策
|
||||
- 批准关键的架构变更
|
||||
|
||||
## Monorepo 项目配置
|
||||
|
||||
Opentu 使用 Nx monorepo 结构,需要特殊配置来支持 Spec-Kit。
|
||||
|
||||
### 当前限制
|
||||
|
||||
⚠️ Spec-Kit 假设 `.specify` 在项目根目录,但 monorepo 中不同包可能需要独立的宪章。
|
||||
|
||||
### 推荐配置
|
||||
|
||||
#### 方案 1: 单一宪章(适合小型 monorepo)
|
||||
|
||||
```
|
||||
aitu/
|
||||
├── .specify/
|
||||
│ └── memory/
|
||||
│ └── constitution.md # 全局宪章
|
||||
├── apps/
|
||||
│ └── web/
|
||||
└── packages/
|
||||
├── drawnix/
|
||||
└── react-board/
|
||||
```
|
||||
|
||||
**适用场景:** 所有包遵循相同的编码标准
|
||||
|
||||
#### 方案 2: 分层宪章(适合大型 monorepo)
|
||||
|
||||
```
|
||||
aitu/
|
||||
├── .specify/
|
||||
│ └── memory/
|
||||
│ └── constitution.md # 根宪章(通用原则)
|
||||
├── packages/
|
||||
│ ├── drawnix/
|
||||
│ │ └── .specify/
|
||||
│ │ └── memory/
|
||||
│ │ └── constitution.md # drawnix 特定原则
|
||||
│ └── react-board/
|
||||
│ └── .specify/
|
||||
│ └── memory/
|
||||
│ └── constitution.md # react-board 特定原则
|
||||
```
|
||||
|
||||
**适用场景:** 不同包有不同的技术栈或规范
|
||||
|
||||
**⚠️ 注意:** 截至 2025 年初,Spec-Kit 对子目录 `.specify` 的支持仍在开发中。建议先使用方案 1。
|
||||
|
||||
### Monorepo 工作流建议
|
||||
|
||||
```bash
|
||||
# 1. 在项目根目录初始化 Spec-Kit
|
||||
cd /path/to/aitu
|
||||
npx @github/specify init
|
||||
|
||||
# 2. 创建全局宪章
|
||||
# 在 Claude Code 中运行: /speckit.constitution
|
||||
|
||||
# 3. 为特定包开发功能时,在规范中明确范围
|
||||
# 示例规范开头:
|
||||
# Specification: Add Image Crop Feature to Drawnix Package
|
||||
# Scope: packages/drawnix/
|
||||
# ...
|
||||
|
||||
# 4. 在计划阶段明确文件路径
|
||||
# 示例计划:
|
||||
# Files to modify:
|
||||
# - packages/drawnix/src/components/image-crop/ImageCropPopup.tsx
|
||||
# - packages/drawnix/src/hooks/useImageCrop.ts
|
||||
```
|
||||
|
||||
## 最佳实践
|
||||
|
||||
### 1. 编写高质量规范
|
||||
|
||||
**✅ DO:**
|
||||
- 使用用户故事格式("作为[角色],我希望[功能],以便[价值]")
|
||||
- 定义明确的成功标准
|
||||
- 包含非功能需求(性能、安全、可访问性)
|
||||
- 使用具体的场景和示例
|
||||
|
||||
**❌ DON'T:**
|
||||
- 过早指定技术实现细节
|
||||
- 假设读者了解隐含的业务逻辑
|
||||
- 使用模糊的术语("用户体验良好")
|
||||
|
||||
### 2. 渐进式规范
|
||||
|
||||
对于复杂功能,采用分阶段规范:
|
||||
|
||||
```markdown
|
||||
# Phase 1 Specification: 基础图片裁剪
|
||||
- 支持方形裁剪
|
||||
- 基本的 UI 交互
|
||||
|
||||
# Phase 2 Specification: 高级裁剪形状
|
||||
- 添加圆形和椭圆形
|
||||
- 裁剪预览
|
||||
|
||||
# Phase 3 Specification: 性能优化
|
||||
- Web Worker 处理大图
|
||||
- 缓存裁剪结果
|
||||
```
|
||||
|
||||
### 3. 版本控制规范
|
||||
|
||||
```bash
|
||||
# 提交规范文档
|
||||
git add .specify/specifications/image-crop.md
|
||||
git commit -m "docs(spec): add image crop feature specification"
|
||||
|
||||
# 提交计划
|
||||
git add .specify/plans/image-crop-plan.md
|
||||
git commit -m "docs(plan): add implementation plan for image crop"
|
||||
|
||||
# 实现完成后更新规范
|
||||
git add .specify/specifications/image-crop.md
|
||||
git commit -m "docs(spec): update image crop spec with final implementation"
|
||||
```
|
||||
|
||||
### 4. 团队协作
|
||||
|
||||
**规范审查会议:**
|
||||
1. 产品经理提出需求
|
||||
2. 使用 `/speckit.specify` 起草规范
|
||||
3. 团队审查规范,提出问题和建议
|
||||
4. 迭代规范直到达成共识
|
||||
5. 技术负责人制定计划
|
||||
6. 开发团队执行实现
|
||||
|
||||
**异步协作:**
|
||||
- 在 GitHub PR 中审查规范文档
|
||||
- 使用 GitHub Discussions 讨论计划方案
|
||||
- 在 Issues 中跟踪规范变更请求
|
||||
|
||||
### 5. 测试驱动规范
|
||||
|
||||
在规范中明确测试场景:
|
||||
|
||||
```markdown
|
||||
## 测试场景
|
||||
|
||||
### 场景 1: 成功裁剪为圆形
|
||||
Given: 用户已上传一张图片
|
||||
When: 用户选择"圆形裁剪"
|
||||
Then: 图片以圆形显示,保持原始宽高比
|
||||
|
||||
### 场景 2: 大图片性能
|
||||
Given: 用户上传 10MB 的高分辨率图片
|
||||
When: 用户应用裁剪
|
||||
Then: 操作在 500ms 内完成,UI 不卡顿
|
||||
|
||||
### 场景 3: 移动端触摸
|
||||
Given: 用户在移动设备上
|
||||
When: 用户触摸选择裁剪形状
|
||||
Then: 触摸区域足够大(最小 44x44px),操作流畅
|
||||
```
|
||||
|
||||
### 6. 活文档原则
|
||||
|
||||
规范是"活"的,随代码演进:
|
||||
|
||||
```markdown
|
||||
# Specification: Image Crop Feature
|
||||
|
||||
## Version History
|
||||
- v1.0 (2025-01-15): Initial specification
|
||||
- v1.1 (2025-01-20): Added ellipse shape after user feedback
|
||||
- v1.2 (2025-01-25): Updated performance requirements
|
||||
|
||||
## Implementation Status
|
||||
✅ Completed: Rectangle and circle crop
|
||||
🚧 In Progress: Ellipse crop
|
||||
📋 Planned: Custom polygon crop
|
||||
```
|
||||
|
||||
### 7. 利用 Opentu 现有规范
|
||||
|
||||
将项目现有文档整合到 Spec-Kit 工作流:
|
||||
|
||||
```markdown
|
||||
# Constitution 引用现有规范
|
||||
参见项目根目录的详细规范:
|
||||
- 编码标准: docs/CODING_STANDARDS.md
|
||||
- 品牌指南: docs/BRAND_GUIDELINES.md
|
||||
- 设计系统: docs/TDESIGN_THEME_INTEGRATION.md
|
||||
|
||||
本宪章提炼这些文档中的核心原则,作为 AI 开发的指导方针。
|
||||
```
|
||||
|
||||
### 8. 性能与质量检查
|
||||
|
||||
在实现阶段嵌入自动检查:
|
||||
|
||||
```markdown
|
||||
# Implementation Checklist (自动化)
|
||||
|
||||
## 代码质量
|
||||
- [ ] TypeScript 类型检查通过 (`nx typecheck drawnix`)
|
||||
- [ ] ESLint 检查通过 (`nx lint drawnix`)
|
||||
- [ ] 单元测试通过 (`nx test drawnix`)
|
||||
- [ ] 文件行数 < 500 行
|
||||
|
||||
## 性能基准
|
||||
- [ ] 裁剪操作 < 200ms (Lighthouse)
|
||||
- [ ] 组件首次渲染 < 100ms
|
||||
- [ ] Bundle 大小增加 < 10KB
|
||||
|
||||
## 安全检查
|
||||
- [ ] 输入验证完整
|
||||
- [ ] 无硬编码密钥
|
||||
- [ ] 依赖漏洞扫描通过
|
||||
```
|
||||
|
||||
## 常见问题
|
||||
|
||||
### Q: Spec-Kit 会让开发变慢吗?
|
||||
|
||||
**A:** 初期可能稍慢,但长期加速开发:
|
||||
- ✅ 减少返工(早期发现需求偏差)
|
||||
- ✅ 降低沟通成本(规范即文档)
|
||||
- ✅ 提升代码质量(AI 遵循宪章)
|
||||
- ✅ 新成员上手快(规范清晰)
|
||||
|
||||
### Q: 简单功能也要写规范吗?
|
||||
|
||||
**A:** 根据复杂度判断:
|
||||
- 简单 bug 修复 → 直接编码
|
||||
- 添加新 UI 组件 → 简化的规范(1-2 段)
|
||||
- 复杂功能 → 完整的规范-计划-任务流程
|
||||
|
||||
### Q: 规范与代码不同步怎么办?
|
||||
|
||||
**A:** 建立同步机制:
|
||||
1. PR 模板要求更新相关规范
|
||||
2. CI 检查规范文件的修改时间
|
||||
3. 定期规范审计(每月/每季度)
|
||||
|
||||
### Q: 如何处理规范变更?
|
||||
|
||||
**A:** 版本化规范文档:
|
||||
```markdown
|
||||
# Specification: Feature X (v2.0)
|
||||
|
||||
## Changes from v1.0
|
||||
- Added: Support for dark mode
|
||||
- Removed: Legacy browser support
|
||||
- Modified: Performance requirement from 500ms to 200ms
|
||||
|
||||
## Migration Guide
|
||||
...
|
||||
```
|
||||
|
||||
### Q: AI 生成的代码不符合预期怎么办?
|
||||
|
||||
**A:** 调整规范和宪章:
|
||||
1. 检查宪章是否明确约束
|
||||
2. 在规范中添加反例("不应该...")
|
||||
3. 在计划中明确技术选择理由
|
||||
4. 人工审查并修正,然后更新规范
|
||||
|
||||
### Q: Spec-Kit 与 CLAUDE.md 的关系?
|
||||
|
||||
**A:** 互补使用:
|
||||
- **CLAUDE.md** - 项目级指导,所有会话生效
|
||||
- **.specify/constitution.md** - 功能级宪章,特定开发任务生效
|
||||
- 建议: CLAUDE.md 保持简洁,详细规范放入 `.specify/`
|
||||
|
||||
|
||||
### Q: 为什么不是全自动？
|
||||
|
||||
**A:** 这是设计理念，而不是技术限制：
|
||||
|
||||
1. 检查点验证 - 每个阶段都是质量门禁，防止错误累积
|
||||
2. 人类在循环中 - 关键决策（架构选择、技术方案）需要人类判断
|
||||
3. 早期纠偏 - 在编码前发现需求理解偏差，避免返工
|
||||
4. 渐进式明确 - 从模糊的想法逐步细化到可执行任务
|
||||
|
||||
可以简化的场景
|
||||
|
||||
对于简单、明确的需求，你可以：
|
||||
|
||||
快速模式（跳过可选步骤）：
|
||||
/speckit.specify # 必需
|
||||
/speckit.plan # 必需
|
||||
/speckit.tasks # 必需
|
||||
/speckit.implement # 必需
|
||||
|
||||
最小化模式（极简单任务）：
|
||||
/speckit.specify # 直接在这里描述清楚所有细节
|
||||
/speckit.implement # 跳过 plan 和 tasks，直接实现
|
||||
|
||||
未来可能性
|
||||
|
||||
虽然官方没有全自动模式，但理论上你可以：
|
||||
|
||||
1. 自己创建自动化脚本（但不推荐）：
|
||||
#!/bin/bash
|
||||
# 不推荐：绕过检查点可能导致质量问题
|
||||
claude-code "/speckit.specify $1 && /speckit.plan && /speckit.tasks && /speckit.implement"
|
||||
|
||||
2. 提交 Feature Request 到 https://github.com/github/spec-kit/issues，建议增加：
|
||||
- --auto 标志自动执行所有步骤
|
||||
- --fast 模式跳过可选步骤
|
||||
- 交互式确认点（而非完全自动）
|
||||
|
||||
我的建议
|
||||
|
||||
保持当前的分阶段流程，因为：
|
||||
- ✅ 质量更高：每个检查点都是质量保证
|
||||
- ✅ 更可控：出问题时容易定位在哪个阶段
|
||||
- ✅ 更灵活：可以在任何阶段调整方向
|
||||
- ✅ 学习价值：理解 AI 的思考过程
|
||||
|
||||
对于重复性高的简单任务，可以使用快速模式（跳过 clarify/analyze），但保留核心的 specify → plan → tasks → implement 流程。
|
||||
## 参考资源
|
||||
|
||||
### 官方文档
|
||||
- [Spec-Kit GitHub](https://github.com/github/spec-kit)
|
||||
- [Spec-Driven Development 博客](https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/)
|
||||
|
||||
### Opentu 项目文档
|
||||
- [编码规范](./CODING_STANDARDS.md)
|
||||
- [品牌指南](./BRAND_GUIDELINES.md)
|
||||
- [项目指导](../CLAUDE.md)
|
||||
|
||||
### 社区讨论
|
||||
- [Monorepo 支持讨论](https://github.com/github/spec-kit/discussions/769)
|
||||
- [工作区支持 Issue](https://github.com/github/spec-kit/issues/1026)
|
||||
|
||||
---
|
||||
|
||||
**文档版本:** v1.0
|
||||
**最后更新:** 2025-01-22
|
||||
**维护者:** Opentu 团队
|
||||
|
||||
*本文档遵循 Spec-Kit 的活文档原则,会随着工具和项目实践持续演进。*
|
||||
Reference in New Issue
Block a user