Planning-with-files 教程 7：实战研究型任务

教程概述

本教程将通过一个完整的技术选型案例，演示如何使用 Planning-with-files 管理研究型任务。

任务背景

你需要为一个新项目选择状态管理方案。这是一个典型的研究型任务，需要：

调研多个候选方案
对比分析优劣
做出技术决策
输出研究报告

你将学到

✅ 研究型任务的阶段划分
✅ findings.md 的高效使用
✅ 技术决策的记录方法
✅ 研究报告的输出

任务启动

Step 1：创建规划文件

/plan 为 Next.js 14 项目选择状态管理方案，团队 3 人，都是 React 新手

AI 创建三个文件：

task_plan.md（初始版）：

# Task Plan: 状态管理方案选型

## Goal
为 Next.js 14 项目选择合适的状态管理方案，平衡学习成本、开发效率和性能。

## Context
- 团队规模: 3 人
- 技术水平: React 新手
- 项目类型: 中型 Web 应用
- 技术栈: Next.js 14 + TypeScript + Tailwind CSS

## Phases

### Phase 1: 需求分析
- [ ] 明确状态管理需求
- [ ] 确定评估维度
- **Status:** in_progress
- **Started:** 2026-03-26 10:00

### Phase 2: 候选方案调研
- [ ] 调研主流方案
- [ ] 收集官方文档和最佳实践
- **Status:** pending

### Phase 3: 对比分析
- [ ] 按维度对比各方案
- [ ] 分析优劣势
- **Status:** pending

### Phase 4: 决策与报告
- [ ] 做出技术决策
- [ ] 输出研究报告
- **Status:** pending

## Decisions
| Decision | Rationale | Date |
|----------|-----------|------|
| - | - | - |

## Errors Encountered
| Error | Attempt | Resolution | Date |
|-------|---------|------------|------|
| - | - | - | - |

Phase 1：需求分析

明确状态管理需求

AI 开始询问：

在选择状态管理方案之前，我需要了解一些细节：

1. 状态复杂度：
   - 预计有多少全局状态？
   - 状态之间的依赖关系复杂吗？

2. 数据流特点：
   - 主要是服务端数据还是客户端状态？
   - 需要实时更新吗？

3. 性能要求：
   - 预计用户量？
   - 对首屏加载时间有要求吗？

你回答：

1. 全局状态不多，主要是用户信息、主题设置、购物车
   状态依赖不复杂

2. 主要是服务端数据（商品、订单）
   不需要实时更新，轮询即可

3. 预计用户量 1 万以内
   首屏加载 < 2s

更新 findings.md

AI 记录到 findings.md：

# Findings: 状态管理方案选型

## Research Findings

### 需求分析

**状态类型**:
- 用户信息（认证状态、用户资料）
- 主题设置（深色/浅色模式）
- 购物车（商品列表、数量、总价）

**状态特点**:
- 全局状态数量: 少（3-5 个）
- 状态依赖: 简单
- 主要数据来源: 服务端（商品、订单）

**性能要求**:
- 用户量: < 10,000
- 首屏加载: < 2s
- 实时性: 无需实时，轮询可接受

### 评估维度

| 维度 | 权重 | 说明 |
|-----|------|------|
| 学习成本 | ⭐⭐⭐⭐⭐ | 团队是新手，成本敏感 |
| 开发效率 | ⭐⭐⭐⭐ | 需要快速迭代 |
| 性能 | ⭐⭐⭐ | 用户量不大 |
| 生态成熟度 | ⭐⭐⭐ | 遇到问题要能找到解决方案 |
| Bundle 大小 | ⭐⭐⭐ | 影响首屏加载 |

完成 Phase 1

### Phase 1: 需求分析
- [x] 明确状态管理需求
- [x] 确定评估维度
- **Status:** complete
- **Started:** 2026-03-26 10:00
- **Completed:** 2026-03-26 10:30

Phase 2：候选方案调研

调研主流方案

AI 开始调研：

让我调研主流的状态管理方案...

[WebSearch "React 状态管理 2024 推荐"]
[WebSearch "Zustand vs Redux vs Jotai"]

2-Action 规则实践

操作 1：WebSearch

发现候选方案：Redux Toolkit, Zustand, Jotai, Recoil, MobX

操作 2：WebFetch 官方文档

⚠️ 必须更新 findings.md！

更新 findings.md：

### 候选方案概览

| 方案 | Star | 最新版本 | 维护状态 |
|-----|------|---------|---------|
| Redux Toolkit | 60k+ | 2.0 | 活跃 |
| Zustand | 40k+ | 4.4 | 活跃 |
| Jotai | 17k+ | 2.6 | 活跃 |
| Recoil | 18k+ | 0.7 | Meta 维护 |
| MobX | 27k+ | 6.10 | 活跃 |

### 各方案特点

#### Redux Toolkit
- 官方推荐，生态最成熟
- DevTools 强大
- 学习曲线陡峭
- 样板代码较多（但比 Redux 少）

#### Zustand
- API 极简，学习成本低
- Bundle 小（~3KB）
- TypeScript 支持好
- DevTools 较简单

#### Jotai
- 原子化设计
- 性能最优
- 概念较新
- 社区较小

#### Recoil
- Meta 出品
- 适合复杂状态图
- 仍处于 0.x 版本
- 学习成本中等

#### MobX
- 响应式编程
- 自动追踪依赖
- 需要理解 Observable
- 装饰器语法

继续调研

[WebFetch Zustand 官方文档]
[WebFetch Redux Toolkit 官方文档]

更新 findings.md：

### 详细调研

#### Zustand 深入
**安装**: `npm install zustand`

**基础用法**:
```typescript
import { create } from 'zustand'

const useStore = create((set) => ({
  count: 0,
  increment: () => set((state) => ({ count: state.count + 1 })),
}))

优点:

无 Provider 包裹
支持 SSR
支持 React 18

资源: 官方文档

Redux Toolkit 深入

安装: npm install @reduxjs/toolkit react-redux

基础用法:

import { createSlice, configureStore } from '@reduxjs/toolkit'

const counterSlice = createSlice({
  name: 'counter',
  initialState: { value: 0 },
  reducers: {
    increment: (state) => { state.value += 1 },
  },
})

优点:

官方推荐
DevTools 最强大
时间旅行调试
中间件生态

资源: 官方文档


### 完成 Phase 2

```markdown
### Phase 2: 候选方案调研
- [x] 调研主流方案
- [x] 收集官方文档和最佳实践
- **Status:** complete
- **Started:** 2026-03-26 10:30
- **Completed:** 2026-03-26 11:30

Phase 3：对比分析

按维度对比

AI 生成对比表格：

### 对比分析

#### 学习成本对比

| 方案 | 概念数量 | 上手时间 | 文档质量 | 评分 |
|-----|---------|---------|---------|------|
| Redux Toolkit | 多（store, slice, reducer, action, dispatch） | 2-3 天 | ⭐⭐⭐⭐⭐ | ⭐⭐ |
| Zustand | 少（store, action） | 半天 | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
| Jotai | 中（atom, derived atom） | 1 天 | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
| Recoil | 多（atom, selector, RecoilRoot） | 2 天 | ⭐⭐⭐ | ⭐⭐⭐ |
| MobX | 多（observable, action, computed） | 2 天 | ⭐⭐⭐⭐ | ⭐⭐⭐ |

#### 性能对比

| 方案 | Bundle 大小 | 渲染性能 | 更新性能 | 评分 |
|-----|-----------|---------|---------|------|
| Redux Toolkit | ~42KB | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐ |
| Zustand | ~3KB | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
| Jotai | ~4KB | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
| Recoil | ~30KB | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
| MobX | ~16KB | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ |

#### 开发效率对比

| 方案 | 样板代码 | DevTools | 调试体验 | 评分 |
|-----|---------|----------|---------|------|
| Redux Toolkit | 中等 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
| Zustand | 最少 | ⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
| Jotai | 少 | ⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
| Recoil | 中等 | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
| MobX | 中等 | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ |

#### 综合评分

| 方案 | 学习成本(30%) | 开发效率(30%) | 性能(20%) | 生态(20%) | 总分 |
|-----|-------------|-------------|---------|---------|------|
| Redux Toolkit | 2 | 4 | 3 | 5 | **3.4** |
| Zustand | 5 | 5 | 5 | 3 | **4.6** |
| Jotai | 4 | 4 | 5 | 3 | **4.0** |
| Recoil | 3 | 4 | 4 | 3 | **3.5** |
| MobX | 3 | 4 | 5 | 4 | **3.9** |

优劣势分析

### 各方案优劣势

#### Zustand（推荐）

**优势**:
1. 学习成本最低，适合 React 新手
2. Bundle 最小（3KB），不影响首屏
3. API 简洁，无样板代码
4. TypeScript 支持完善
5. 适合中型应用

**劣势**:
1. DevTools 功能不如 Redux
2. 社区生态较小
3. 复杂场景需要额外设计

**适用场景**:
- 中小型应用
- 团队 React 经验不足
- 追求开发效率

#### Redux Toolkit（备选）

**优势**:
1. 官方推荐，生态最成熟
2. DevTools 最强大
3. 社区资源丰富
4. 适合大型复杂应用

**劣势**:
1. 学习曲线陡峭
2. 概念较多
3. Bundle 较大

**适用场景**:
- 大型复杂应用
- 需要强大调试工具
- 团队有 Redux 经验

完成 Phase 3

### Phase 3: 对比分析
- [x] 按维度对比各方案
- [x] 分析优劣势
- **Status:** complete
- **Started:** 2026-03-26 11:30
- **Completed:** 2026-03-26 13:00

Phase 4：决策与报告

技术决策

更新 task_plan.md：

## Decisions
| Decision | Rationale | Date |
|----------|-----------|------|
| 选择 Zustand | 学习成本低、Bundle 小、适合团队现状 | 2026-03-26 |

更新 findings.md：

## Technical Decisions

### TD-001: 选择 Zustand 作为状态管理方案

**状态**: ✅ 已采纳
**日期**: 2026-03-26

**背景**:
- 团队 3 人，都是 React 新手
- 项目是中型 Web 应用
- 预计用户量 < 10,000
- 状态复杂度不高

**决策**:
选择 Zustand 作为状态管理方案。

**理由**:
1. **学习成本最低**: 团队是 React 新手，需要低学习成本的方案
2. **Bundle 最小**: 3KB，不影响首屏加载（< 2s 的要求）
3. **开发效率高**: API 简洁，无样板代码
4. **满足需求**: 状态复杂度不高，Zustand 完全覆盖

**替代方案**:
- Redux Toolkit：学习成本太高
- Jotai：原子化概念对新手不友好
- Recoil：版本不稳定

**风险缓解**:
- 如果未来状态变复杂，可以逐步引入 Jotai 处理局部状态
- DevTools 功能可以通过 zustand/middleware 补充

**后续行动**:
- [ ] 团队学习 Zustand（预计半天）
- [ ] 搭建示例项目
- [ ] 制定使用规范

输出研究报告

创建 research-report.md：

# 状态管理方案选型报告

## 执行摘要

经过需求分析、方案调研和对比分析，推荐使用 **Zustand** 作为项目的状态管理方案。

## 需求背景

| 项目 | 信息 |
|-----|------|
| 团队规模 | 3 人 |
| 技术水平 | React 新手 |
| 项目类型 | 中型 Web 应用 |
| 状态复杂度 | 低-中 |

## 评估过程

### 评估维度
1. 学习成本（权重 30%）
2. 开发效率（权重 30%）
3. 性能（权重 20%）
4. 生态成熟度（权重 20%）

### 候选方案
- Redux Toolkit
- Zustand
- Jotai
- Recoil
- MobX

### 综合评分

| 方案 | 总分 |
|-----|------|
| **Zustand** | **4.6** |
| Jotai | 4.0 |
| MobX | 3.9 |
| Recoil | 3.5 |
| Redux Toolkit | 3.4 |

## 决策建议

**推荐方案**: Zustand

**理由**:
1. 学习成本最低，适合团队现状
2. Bundle 最小（3KB）
3. API 简洁，开发效率高
4. 完全满足项目需求

**后续步骤**:
1. 团队学习（半天）
2. 搭建示例项目
3. 制定使用规范

## 附录

### 详细对比表
（见 findings.md）

### 参考资源
- [Zustand 官方文档](https://zustand-demo.pmnd.rs/)
- [Redux Toolkit 官方文档](https://redux-toolkit.js.org/)
- [React 状态管理对比](https://xxx)

完成 Phase 4

### Phase 4: 决策与报告
- [x] 做出技术决策
- [x] 输出研究报告
- **Status:** complete
- **Started:** 2026-03-26 13:00
- **Completed:** 2026-03-26 14:00

最终文件状态

task_plan.md

# Task Plan: 状态管理方案选型

## Goal
为 Next.js 14 项目选择合适的状态管理方案，平衡学习成本、开发效率和性能。

## Phases

### Phase 1: 需求分析
- [x] 明确状态管理需求
- [x] 确定评估维度
- **Status:** complete
- **Started:** 2026-03-26 10:00
- **Completed:** 2026-03-26 10:30

### Phase 2: 候选方案调研
- [x] 调研主流方案
- [x] 收集官方文档和最佳实践
- **Status:** complete
- **Started:** 2026-03-26 10:30
- **Completed:** 2026-03-26 11:30

### Phase 3: 对比分析
- [x] 按维度对比各方案
- [x] 分析优劣势
- **Status:** complete
- **Started:** 2026-03-26 11:30
- **Completed:** 2026-03-26 13:00

### Phase 4: 决策与报告
- [x] 做出技术决策
- [x] 输出研究报告
- **Status:** complete
- **Started:** 2026-03-26 13:00
- **Completed:** 2026-03-26 14:00

## Decisions
| Decision | Rationale | Date |
|----------|-----------|------|
| 选择 Zustand | 学习成本低、Bundle 小、适合团队现状 | 2026-03-26 |

## Errors Encountered
| Error | Attempt | Resolution | Date |
|-------|---------|------------|------|
| - | - | - | - |

progress.md

# Progress: 状态管理方案选型

## Session Log
| Time | Action | Files Modified |
|------|--------|----------------|
| 10:00 | 创建规划文件 | task_plan.md, findings.md, progress.md |
| 10:15 | 分析需求 | findings.md |
| 10:30 | 完成 Phase 1 | task_plan.md |
| 10:45 | 调研 Redux Toolkit | findings.md |
| 11:00 | 调研 Zustand | findings.md |
| 11:15 | 调研 Jotai | findings.md |
| 11:30 | 完成 Phase 2 | task_plan.md |
| 12:00 | 生成对比表格 | findings.md |
| 12:30 | 分析优劣势 | findings.md |
| 13:00 | 完成 Phase 3 | task_plan.md |
| 13:30 | 记录技术决策 | task_plan.md, findings.md |
| 14:00 | 输出研究报告 | research-report.md |

## Test Results
（研究型任务无测试）

## Error Log
| Time | Error | Resolution |
|------|-------|------------|
| - | - | - |

## 5-Question Reboot Test
| Question | Answer |
|----------|--------|
| Where am I? | Phase 4，已完成 |
| Where am I going? | 所有阶段已完成 |
| What's the goal? | 选择状态管理方案 |
| What have I learned? | Zustand 最适合团队现状 |
| What have I done? | 调研、对比、决策、输出报告 |

研究型任务最佳实践

1. 明确评估维度

在 Phase 1 就确定评估维度和权重，避免主观偏见。

2. 严格执行 2-Action 规则

研究型任务涉及大量查看操作，必须严格执行 2-Action 规则，避免信息丢失。

3. 使用 ADR 记录决策

技术决策使用 Architecture Decision Record 格式，记录完整上下文。

4. 输出可复用的报告

研究报告应该结构化，可供团队分享和后续参考。

5. 追踪决策执行

决策后的行动项应该被追踪，确保落地执行。

系列导航：

教程概述

任务背景

你将学到

任务启动

Step 1：创建规划文件

Phase 1：需求分析

明确状态管理需求

更新 findings.md

完成 Phase 1

Phase 2：候选方案调研

调研主流方案

2-Action 规则实践

继续调研

Redux Toolkit 深入

Phase 3：对比分析

按维度对比

优劣势分析

完成 Phase 3

Phase 4：决策与报告

技术决策

输出研究报告

完成 Phase 4

最终文件状态

task_plan.md

progress.md

研究型任务最佳实践

1. 明确评估维度

2. 严格执行 2-Action 规则

3. 使用 ADR 记录决策

4. 输出可复用的报告

5. 追踪决策执行

🍪 Cookie 使用通知

Cookie 偏好设置

必要 Cookie

分析 Cookie

广告 Cookie