夜雨聆风
前言
上一课我们学习了规范格式与最佳实践，这一课我们将深入学习任务清单（tasks.md）和设计文档（design.md）的编写。这两种文档在OpenSpec工作流程中扮演着重要角色，它们连接了规范和代码实现。
任务清单详解
tasks.md是实施阶段的核心文档，它将复杂的变更分解为一系列可执行、可验证的任务。
任务清单结构
# Tasks: [变更名称]## 1. [类别或阶段]- [ ] 1.1 [具体任务]- [ ] 1.2 [具体任务]## 2. [另一个类别]- [ ] 2.1 [具体任务]- [ ] 2.2 [具体任务]## 3. 验证与测试- [ ] 3.1 [验证步骤]- [ ] 3.2 [测试步骤]
任务命名规则
·使用动词开头描述任务
·任务应该简洁明了
·包含明确的验收标准
✓ 正确：- [ ] 1.1 创建数据库表结构- [ ] 1.2 实现用户认证Service- [ ] 1.3 添加API端点文档✗ 错误：- [ ] 1.1 做数据库相关的事情- [ ] 1.2 实现一些功能- [ ] 1.3 添加文档
任务分解原则
粒度适中
每个任务应该控制在1-2小时内完成。太大了需要拆分，太小了可以合并。
✓ 正确：- [ ] 1.1 创建ThemeContext（管理主题状态）- [ ] 1.2 添加localStorage读写- [ ] 1.3 实现系统偏好检测✗ 错误（粒度太大）：- [ ] 1.1 实现整个暗黑模式功能✗ 错误（粒度太小）：- [ ] 1.1.1 创建ThemeContext文件- [ ] 1.1.2 定义状态类型- [ ] 1.1.3 实现toggle方法
前后依赖清晰
任务应该按逻辑顺序排列，前置任务在前，依赖任务在后。
## 1. 数据层- [ ] 1.1 创建数据库表结构- [ ] 1.2 实现Repository层## 2. 业务层- [ ] 2.1 实现Service层- [ ] 2.2 添加业务逻辑验证## 3. 接口层- [ ] 3.1 实现API端点- [ ] 3.2 添加请求验证## 4. 前端- [ ] 4.1 创建UI组件- [ ] 4.2 集成API调用## 5. 测试- [ ] 5.1 编写单元测试- [ ] 5.2 进行集成测试
任务示例：用户认证
# Tasks: Add User Authentication## 1. 数据库设计- [ ] 1.1 设计用户表结构（id, username, email, password_hash, created_at, updated_at）- [ ] 1.2 创建数据库迁移文件- [ ] 1.3 执行迁移并验证## 2. 后端实现- [ ] 2.1 实现User模型和Repository- [ ] 2.2 实现AuthService（注册、登录、Token生成）- [ ] 2.3 实现登录API端点 POST /api/auth/login- [ ] 2.4 实现注册API端点 POST /api/auth/register- [ ] 2.5 实现Token验证中间件## 3. 前端实现- [ ] 3.1 创建LoginPage组件- [ ] 3.2 创建RegisterPage组件- [ ] 3.3 实现表单验证逻辑- [ ] 3.4 实现Token存储（localStorage）- [ ] 3.5 创建AuthContext管理登录状态## 4. 测试- [ ] 4.1 编写后端单元测试（覆盖率>80%）- [ ] 4.2 编写前端组件测试- [ ] 4.3 进行端到端测试- [ ] 4.4 测试边界情况（错误密码、过期Token等）## 5. 文档- [ ] 5.1 更新API文档- [ ] 5.2 添加使用示例
任务标记与进度
在实施过程中，每完成一个任务，标记为完成：
- [ ] 1.1 创建ThemeContext- [x] 1.2 添加localStorage读写 ✓- [ ] 1.3 实现系统偏好检测
当所有任务完成时：
所有任务完成:- [x] 1.1 创建ThemeContext ✓- [x] 1.2 添加localStorage读写 ✓- [x] 1.3 实现系统偏好检测 ✓
设计文档详解
design.md是可选的文档，当变更涉及复杂的技术决策时需要创建。
何时需要设计文档
跨多个服务/模块的变更
当变更涉及多个服务或多个模块时，需要设计文档来明确边界和接口。
新的架构模式
采用新的架构模式（如微服务、事件驱动等）时，需要详细的设计文档。
重要的数据模型变更
数据库schema变更、表结构调整等，需要设计文档记录变更方案。
安全或性能敏感的变更
涉及安全机制、性能优化的变更，需要详细的技术设计。
设计文档结构
# Design: [变更名称]## Overview[简要概述变更内容]## Background[当前状态和变更原因]## Goals / Non-Goals**Goals:**- [我们试图实现的目标]**Non-Goals:**- [明确不在范围内的内容]## Technical Decisions### Decision 1: [决策标题][方法解释和理由]**Options Considered:**- Option A: [描述]- Option B: [描述]**Chosen:** Option B**Reason:** [选择原因]## API Design### Endpoints#### POST /api/endpoint**Request:**
{
"field": "value"
}
**Response:**
{
"result": "success"
}
## Data Model### Database Schema
CREATE TABLE table_name (
id UUID PRIMARY KEY,
field VARCHAR(255) NOT NULL,
created_at TIMESTAMP DEFAULT NOW()
);
## File Changes- `src/file1.ts` — 新建，实现xxx功能- `src/file2.ts` — 修改，添加xxx逻辑- `src/file3.ts` — 删除，不再需要## Migration Plan1. [步骤1]2. [步骤2]3. [步骤3]## Rollback Plan如果出现问题，回滚步骤：1. [回滚步骤1]2. [回滚步骤2]
设计文档示例：暗黑模式
# Design: Add Dark Mode## Overview为应用添加暗黑模式支持，允许用户在亮色和暗色主题之间切换。## Background用户反馈在低光环境下使用应用时，亮色主题会导致眼睛疲劳。多数现代应用都支持暗黑模式，这是用户的基本预期。## Goals / Non-Goals**Goals:**- 在应用头部添加主题切换按钮- 为所有颜色定义亮色和暗色两套值- 将用户偏好持久化到localStorage- 默认跟随系统偏好(prefers-color-scheme)**Non-Goals:**- 添加主题切换动画- 实现自定义主题颜色- 云端同步用户偏好## Technical Decisions### Decision 1: 主题切换方式**Options Considered:**- Option A: 使用CSS变量（--bg-primary, --text-primary等）- Option B: 使用Tailwind的dark:前缀- Option C: 使用CSS-in-JS动态样式**Chosen:** Option B（Tailwind dark:前缀）**Reason:**- 已有项目使用Tailwind CSS，保持一致- Tailwind的dark:前缀与现有工具链集成良好- 不需要额外维护CSS变量映射表### Decision 2: 主题状态管理**Options Considered:**- Option A: React Context- Option B: Redux/Zustand等状态管理- Option C: 组件内部状态**Chosen:** Option A（React Context）**Reason:**- 主题状态是全局状态，影响整个应用- 不需要引入额外的状态管理库- React Context足够满足需求## API Design主题切换是纯前端功能，不需要API调用。## Data Model
// ThemeContext
interface ThemeContextType {
theme: 'light' | 'dark';
toggleTheme: () => void;
}
// localStorage存储
interface StoredPreference {
theme: 'light' | 'dark' | 'system';
updatedAt: string;
}
## File Changes**New Files:**- `src/context/ThemeContext.tsx` — 主题状态管理- `src/components/ThemeToggle.tsx` — 主题切换按钮**Modified Files:**- `src/index.css` — 添加dark模式样式- `src/components/Header.tsx` — 添加ThemeToggle组件- `src/main.tsx` — 用ThemeProvider包裹App## Implementation Steps1. 创建ThemeContext，实现状态管理和localStorage持久化2. 定义CSS变量或使用Tailwind dark:前缀3. 创建ThemeToggle组件4. 在Header中集成ThemeToggle5. 更新现有组件使用新主题## Rollback Plan如需回滚：1. 删除ThemeContext和相关组件2. 恢复原有的CSS样式3. 移除Header中的ThemeToggle
与AI协作编写文档
创建提案时
让AI自动生成任务清单和设计文档：
/opsx:propose "添加用户个人资料管理功能"
AI会根据需求描述生成相应的文档，您再根据实际情况进行调整。
补充完善时
您可以告诉AI补充细节：
添加关于头像上传的技术决策，使用localStorage存储临时文件
修改时
直接告诉AI需要修改的内容：
把任务清单中关于测试的部分拆分得更细一些
保持简洁
设计文档应该简洁，避免过度设计。一个小的功能可能只需要几句话的设计说明。
及时更新
当设计方案发生变化时，及时更新设计文档。文档应该反映当前的实现状态。
关联规范
任务清单应该与规范文档关联。每个任务完成后，检查是否满足规范中的要求。
保存历史
设计文档是项目的技术资产，应该保存到代码仓库中，供日后参考。
练习题
1.为"添加文件上传功能"编写任务清单，要求覆盖：
- 前端组件
- 后端API
- 数据库设计
- 测试
2.为"重构搜索功能"编写设计文档，包含：
- 当前问题
- 解决方案选项
- 技术决策说明
- 迁移计划
3.使用AI辅助生成上述文档，然后根据实际情况进行调整。
4.模拟实施过程，将任务清单中的任务标记为完成。
下节预告
下一课我们将学习：
·OpenSpec与Cursor的集成使用
·OpenSpec与Claude Code的集成使用
·AI助手斜杠命令的高级用法
·自定义配置与工作流优化
