Jammy/TrueGrowth

Fork 0

Files

Jammy 3b6781d695 Initial TrueGrowth source import

2026-07-07 09:36:36 +08:00

21 KiB

Raw Blame History

Spec-Kit 最佳实践指南

本文档介绍如何在 Opentu 项目中使用 GitHub Spec-Kit 进行规范驱动开发(Spec-Driven Development, SDD)。

什么是 Spec-Kit

Spec-Kit 是 GitHub 开源的规范驱动开发工具包,它将传统的"先编码后写文档"流程倒置为"先写规范后生成代码"。规范成为项目的真实来源(source of truth),AI 工具根据规范生成、测试和验证代码。

核心组件

Specify CLI - 用于初始化项目和下载模板的命令行工具
模板和脚本 - 预设的规范模板和辅助脚本
AI 集成 - 支持 Claude Code、GitHub Copilot、Gemini CLI 等 AI 编码助手

支持的 AI 工具

Claude Code (推荐用于 Opentu 项目)
GitHub Copilot
Gemini CLI
Cursor
其他兼容的 AI 编码助手

核心理念

规范驱动开发的优势

意图优先 - 从"做什么"和"为什么"开始,而不是"怎么做"
清晰性 - 在编码前就明确需求和架构决策
活文档 - 规范与代码同步演进,始终保持最新
人机协作 - 人类负责战略决策,AI 负责执行实现
早期验证 - 在多个检查点捕获需求偏差,避免后期返工

何时使用 Spec-Kit

✅ 推荐使用:

为现有系统添加新功能
复杂的功能开发需要架构决策
团队协作需要明确的需求文档
需要保持代码与文档同步

❌ 不建议使用:

简单的 bug 修复
样式微调
配置文件更新
一次性实验性代码

安装与设置

前置要求

# 检查 Python 版本 (需要 3.11+)
python --version

# 检查 Git
git --version

# 安装 uv 包管理器
curl -LsSf https://astral.sh/uv/install.sh | sh

初始化 Spec-Kit

# 在项目根目录执行
npx @github/specify init

# 或使用 Python 包
pip install github-specify
specify init

这将创建 .specify/ 目录结构:

.specify/
├── memory/
│   └── constitution.md      # 项目宪章(非常重要!)
├── specifications/          # 功能规范文档
├── plans/                   # 实现计划
└── tasks/                   # 任务列表

快速开始 - Specify 命令步骤流程

完整开发周期命令序列

# 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: 首次使用(新项目)

# 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: 日常功能开发

# 直接跳过 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: 团队协作

# 产品经理/技术负责人
/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 项目宪章示例:

# 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

规范聚焦于"做什么"和"为什么",避免过早陷入技术细节。

好的规范示例:

# 规范: 图片圆形裁剪功能

## 背景
用户在插入图片后,只能使用方形裁剪,无法创建圆形或椭圆形的图片效果,
限制了设计创意。

## 目标
为用户提供三种图片裁剪形状选项:方形、圆形、椭圆形。

## 用户故事
作为白板用户,我希望能够:
1. 选中画布上的图片
2. 点击工具栏的"裁剪"按钮
3. 在弹出菜单中选择裁剪形状(方形/圆形/椭圆形)
4. 看到图片以选定形状显示

## 功能需求
- FR1: 在图片选中时显示裁剪按钮
- FR2: 提供三种裁剪形状选项
- FR3: 裁剪后保持图片质量
- FR4: 支持撤销/重做操作

## 非功能需求
- NFR1: 裁剪操作响应时间 < 200ms
- NFR2: 裁剪不影响原始图片文件
- NFR3: 支持移动端触摸操作

## 成功标准
- 用户可以成功应用三种裁剪形状
- E2E 测试通过
- 符合品牌设计规范

❌ 避免在规范阶段:

指定具体的技术实现(如"使用 canvas API")
详细的代码结构
具体的库或框架选择

3. 制定计划 (Plan)

命令: /speckit.plan

计划阶段做出技术决策,选择实现方案。

计划示例:

# 实现计划: 图片圆形裁剪功能

## 技术栈选择
- 图片处理: 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

将计划分解为可执行的小任务。

任务列表示例:

# 任务清单: 图片圆形裁剪功能

## 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 根据规范、计划和任务开始生成代码。

工作方式:

AI 按顺序执行任务列表
生成代码并运行测试
遇到问题时暂停,寻求人类指导
完成后更新任务状态

人类在循环中的角色:

审查生成的代码
在检查点提供反馈
解决 AI 无法处理的设计决策
批准关键的架构变更

Monorepo 项目配置

Opentu 使用 Nx monorepo 结构,需要特殊配置来支持 Spec-Kit。

当前限制

⚠️ Spec-Kit 假设 .specify 在项目根目录,但 monorepo 中不同包可能需要独立的宪章。

Monorepo 工作流建议

# 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. 渐进式规范

对于复杂功能,采用分阶段规范:

# Phase 1 Specification: 基础图片裁剪
- 支持方形裁剪
- 基本的 UI 交互

# Phase 2 Specification: 高级裁剪形状
- 添加圆形和椭圆形
- 裁剪预览

# Phase 3 Specification: 性能优化
- Web Worker 处理大图
- 缓存裁剪结果

3. 版本控制规范

# 提交规范文档
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. 团队协作

规范审查会议:

产品经理提出需求
使用 /speckit.specify 起草规范
团队审查规范,提出问题和建议
迭代规范直到达成共识
技术负责人制定计划
开发团队执行实现

异步协作:

在 GitHub PR 中审查规范文档
使用 GitHub Discussions 讨论计划方案
在 Issues 中跟踪规范变更请求

5. 测试驱动规范

在规范中明确测试场景:

## 测试场景

### 场景 1: 成功裁剪为圆形
Given: 用户已上传一张图片
When: 用户选择"圆形裁剪"
Then: 图片以圆形显示,保持原始宽高比

### 场景 2: 大图片性能
Given: 用户上传 10MB 的高分辨率图片
When: 用户应用裁剪
Then: 操作在 500ms 内完成,UI 不卡顿

### 场景 3: 移动端触摸
Given: 用户在移动设备上
When: 用户触摸选择裁剪形状
Then: 触摸区域足够大(最小 44x44px),操作流畅

6. 活文档原则

规范是"活"的,随代码演进:

# 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 工作流:

# Constitution 引用现有规范
参见项目根目录的详细规范:
- 编码标准: docs/CODING_STANDARDS.md
- 品牌指南: docs/BRAND_GUIDELINES.md
- 设计系统: docs/TDESIGN_THEME_INTEGRATION.md

本宪章提炼这些文档中的核心原则,作为 AI 开发的指导方针。

8. 性能与质量检查

在实现阶段嵌入自动检查:

# 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: 建立同步机制:

PR 模板要求更新相关规范
CI 检查规范文件的修改时间
定期规范审计(每月/每季度)

Q: 如何处理规范变更?

A: 版本化规范文档:

# 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: 调整规范和宪章:

检查宪章是否明确约束
在规范中添加反例("不应该...")
在计划中明确技术选择理由
人工审查并修正,然后更新规范

Q: Spec-Kit 与 CLAUDE.md 的关系?

A: 互补使用:

CLAUDE.md - 项目级指导,所有会话生效
.specify/constitution.md - 功能级宪章,特定开发任务生效
建议: CLAUDE.md 保持简洁,详细规范放入 .specify/

Q: 为什么不是全自动？

A: 这是设计理念，而不是技术限制：

检查点验证 - 每个阶段都是质量门禁，防止错误累积
人类在循环中 - 关键决策（架构选择、技术方案）需要人类判断
早期纠偏 - 在编码前发现需求理解偏差，避免返工
渐进式明确 - 从模糊的想法逐步细化到可执行任务

可以简化的场景

对于简单、明确的需求，你可以：

快速模式（跳过可选步骤）： /speckit.specify # 必需 /speckit.plan # 必需
/speckit.tasks # 必需 /speckit.implement # 必需

最小化模式（极简单任务）： /speckit.specify # 直接在这里描述清楚所有细节 /speckit.implement # 跳过 plan 和 tasks，直接实现

未来可能性

虽然官方没有全自动模式，但理论上你可以：

自己创建自动化脚本（但不推荐）： #!/bin/bash

不推荐：绕过检查点可能导致质量问题

claude-code "/speckit.specify $1 && /speckit.plan && /speckit.tasks && /speckit.implement"

提交 Feature Request 到 https://github.com/github/spec-kit/issues，建议增加： - --auto 标志自动执行所有步骤 - --fast 模式跳过可选步骤 - 交互式确认点（而非完全自动）

我的建议

保持当前的分阶段流程，因为：

✅ 质量更高：每个检查点都是质量保证
✅ 更可控：出问题时容易定位在哪个阶段
✅ 更灵活：可以在任何阶段调整方向
✅ 学习价值：理解 AI 的思考过程

对于重复性高的简单任务，可以使用快速模式（跳过 clarify/analyze），但保留核心的 specify → plan → tasks → implement 流程。

参考资源

官方文档

Opentu 项目文档

社区讨论

文档版本: v1.0 最后更新: 2025-01-22 维护者: Opentu 团队

本文档遵循 Spec-Kit 的活文档原则,会随着工具和项目实践持续演进。

21 KiB Raw Blame History Unescape Escape

Spec-Kit 最佳实践指南

目录

什么是 Spec-Kit

核心组件

支持的 AI 工具

核心理念

规范驱动开发的优势

何时使用 Spec-Kit

安装与设置

前置要求

初始化 Spec-Kit

快速开始 - Specify 命令步骤流程

完整开发周期命令序列

命令详解

典型工作流示例

场景 1: 首次使用(新项目)

场景 2: 日常功能开发

场景 3: 团队协作

工作流检查点

工作流程

1. 建立宪章 (Constitution)

2. 编写规范 (Specification)

3. 制定计划 (Plan)

4. 分解任务 (Tasks)

5. 执行实现 (Implement)

Monorepo 项目配置

当前限制

推荐配置

方案 1: 单一宪章(适合小型 monorepo)

方案 2: 分层宪章(适合大型 monorepo)

Monorepo 工作流建议

最佳实践

1. 编写高质量规范

2. 渐进式规范

3. 版本控制规范

4. 团队协作

5. 测试驱动规范

6. 活文档原则

7. 利用 Opentu 现有规范

8. 性能与质量检查

常见问题

Q: Spec-Kit 会让开发变慢吗?

Q: 简单功能也要写规范吗?

Q: 规范与代码不同步怎么办?

Q: 如何处理规范变更?

Q: AI 生成的代码不符合预期怎么办?

Q: Spec-Kit 与 CLAUDE.md 的关系?

Q: 为什么不是全自动？

不推荐：绕过检查点可能导致质量问题

参考资源

官方文档

Opentu 项目文档

社区讨论

21 KiB

Raw Blame History