教程概述

task_plan.md 是 3-File Pattern 中最重要的文件，相当于整个任务的"大脑"。它存储目标、追踪进度、记录决策和错误。

你将学到

• ✅ task_plan.md 的完整结构
• ✅ 如何合理划分阶段
• ✅ 状态追踪的最佳实践
• ✅ 决策和错误的记录方法

为什么 task_plan.md 是"大脑"？

flowchart TB
    subgraph 任务生命周期
        A[任务开始] --> B[task_plan.md 创建]
    end

    subgraph 工作循环
        C[PreToolUse Hook] --> D[重读 task_plan.md]
        D --> E[刷新目标到注意力]
        E --> F[执行工作]
        F --> G[更新状态]
        G --> C
    end

    subgraph 完成验证
        H[Stop Hook] --> I[检查 task_plan.md]
        I --> J{所有阶段完成?}
        J -->|是| K[任务完成]
        J -->|否| L[继续工作]
        L --> C
    end

    B --> C
    G --> H

    style B fill:#e1f5ff
    style D fill:#e1f5ff
    style I fill:#e1f5ff

核心作用

标准结构模板

完整结构

# Task Plan: [任务名称]

## Goal
[一句话描述任务目标，回答"我们为什么要做这个？"]

## Context
（可选）任务背景、约束条件、相关资源

## Phases

### Phase 1: [阶段名称]
- [ ] 子任务 1
- [ ] 子任务 2
- [ ] 子任务 3
- **Status:** pending | in_progress | complete
- **Started:** [开始时间]
- **Completed:** [完成时间]
- **Acceptance Criteria:** （可选）
  - 验收标准 1
  - 验收标准 2

### Phase 2: [阶段名称]
...

## Decisions
| Decision | Rationale | Date |
|----------|-----------|------|
| [决策内容] | [决策理由] | [日期] |

## Errors Encountered
| Error | Attempt | Resolution | Date |
|-------|---------|------------|------|
| [错误描述] | [尝试次数] | [解决方案] | [日期] |

## Notes
（可选）其他备注

各部分详解

Goal 部分

好的 Goal：

## Goal
为博客添加标签功能，支持文章与标签的多对多关系，用户可通过标签筛选文章。

不好的 Goal：

## Goal
添加标签功能

原则：

• ✅ 一句话说清楚目标
• ✅ 包含核心业务价值
• ✅ 可验证是否达成
• ❌ 不要过于模糊
• ❌ 不要包含实现细节

Phases 部分

这是 task_plan.md 的核心。每个阶段包含：

### Phase N: 阶段名称

- [ ] 可执行的子任务
- [ ] 另一个子任务
- **Status:** pending
- **Started:** -
- **Completed:** -

Decisions 部分

记录技术决策：

| Decision | Rationale | Date |
|----------|-----------|------|
| 使用 JWT 认证 | 无状态，易于扩展 | 2026-03-26 |
| 选择 PostgreSQL | 支持 JSON，社区活跃 | 2026-03-26 |

Errors 部分

记录错误及解决方案：

| Error | Attempt | Resolution | Date |
|-------|---------|------------|------|
| 数据库连接超时 | 2 | 增加连接池大小到 20 | 2026-03-26 |
| CORS 错误 | 1 | 添加 credentials 配置 | 2026-03-26 |

阶段划分最佳实践

3-7 原则

flowchart LR
    A[复杂任务] --> B{阶段数量}
    B -->|< 3| C[阶段太少<br/>过于笼统]
    B -->|3-7| D[✅ 合适范围]
    B -->|> 7| E[阶段太多<br/>管理复杂]

    style D fill:#c8e6c9
    style C fill:#ffcdd2
    style E fill:#ffcdd2

常见阶段类型

阶段粒度控制

太粗：

### Phase 1: 实现功能
- [ ] 做完所有事
- **Status:** pending

太细：

### Phase 1: 创建文件
- [ ] 创建 index.ts
- **Status:** pending

### Phase 2: 导入库
- [ ] import React
- **Status:** pending

刚刚好：

### Phase 1: 需求分析与设计
- [ ] 确认功能需求
- [ ] 设计数据模型
- [ ] 定义 API 接口
- **Status:** pending

阶段依赖关系

flowchart TD
    A[Phase 1: 需求分析] --> B[Phase 2: 设计]
    B --> C[Phase 3: 数据层]
    B --> D[Phase 4: 后端实现]
    C --> D
    D --> E[Phase 5: 前端实现]
    E --> F[Phase 6: 测试]
    F --> G[Phase 7: 部署]

    style A fill:#e1f5ff
    style G fill:#c8e6c9

并行阶段：如果两个阶段没有依赖，可以并行：

### Phase 3: 后端 API
- [ ] 实现接口
- **Status:** pending

### Phase 4: 前端组件
- [ ] 创建组件
- **Status:** pending
- **Dependencies:** None (可与 Phase 3 并行)

状态追踪机制

三种状态

状态转换

stateDiagram-v2
    [*] --> pending: 创建阶段
    pending --> in_progress: 开始执行
    in_progress --> complete: 所有子任务完成
    in_progress --> pending: 遇到阻塞，暂停
    complete --> [*]: 阶段结束

状态更新时机

### Phase 2: 数据库实现

开始时更新：
- **Status:** in_progress
- **Started:** 2026-03-26 10:30

完成后更新：
- [x] 创建标签表
- [x] 创建关联表
- [x] 编写迁移脚本
- **Status:** complete
- **Completed:** 2026-03-26 11:45

自动状态更新（Hooks）

如果配置了 PostToolUse Hook，AI 会提醒更新状态：

[PostToolUse Hook]
检测到文件修改: migrations/add_tags.sql
提醒: 如果完成了 Phase 2 的任务，请更新 task_plan.md 状态

决策记录

为什么记录决策？

1. 追溯原因：为什么选择这个方案？
2. 避免重复讨论：已经决策的事情不再重新争论
3. 知识传承：新人能理解决策背景
4. 修正依据：当情况变化时，知道如何调整

决策记录格式

| Decision | Rationale | Date |
|----------|-----------|------|
| 选择 Redis 做缓存 | QPS 预计 10000+，需要高性能 | 2026-03-26 |
| 不使用 GraphQL | 团队不熟悉，学习成本高 | 2026-03-26 |
| 使用单体架构 | 用户量 < 1000，无需微服务 | 2026-03-26 |

决策记录最佳实践

记录什么：

• ✅ 技术选型决策
• ✅ 架构设计决策
• ✅ 重要的权衡取舍
• ✅ 否定的替代方案

不记录什么：

• ❌ 琐碎的实现细节
• ❌ 显而易见的选择
• ❌ 没有争议的决定

ADR 风格（进阶）

对于重要决策，可以使用 Architecture Decision Record 风格：

## Decisions

### DR-001: 认证方案选择 JWT

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

**背景**:
需要为 API 设计认证机制，支持移动端和 Web 端。

**决策**:
使用 JWT (JSON Web Token) 进行认证。

**理由**:
1. 无状态，服务端不需要存储 session
2. 天然支持分布式部署
3. 客户端可以存储用户信息

**替代方案**:
- Session + Cookie：需要服务端存储，不利于扩展
- OAuth 2.0：过于复杂，当前不需要第三方登录

**影响**:
- 需要处理 token 过期和刷新
- 需要客户端安全存储 token

错误管理

为什么记录错误？

flowchart TD
    A[遇到错误] --> B{记录到 Errors 表?}
    B -->|是| C[分析根本原因]
    C --> D[找到解决方案]
    D --> E[记录解决方案]
    E --> F[避免重复犯错]

    B -->|否| G[快速修复]
    G --> H[忘记错误]
    H --> I[再次遇到同样错误]
    I --> A

    style F fill:#c8e6c9
    style I fill:#ffcdd2

错误记录格式

| Error | Attempt | Resolution | Date |
|-------|---------|------------|------|
| 数据库迁移失败：外键约束 | 1 | 先创建表，后添加约束 | 2026-03-26 |
| JWT 验证失败：签名不匹配 | 2 | 检查密钥配置，统一使用环境变量 | 2026-03-26 |
| CORS 预检请求失败 | 1 | 添加 OPTIONS 方法支持 | 2026-03-26 |

错误分类

Attempt 字段的意义

记录尝试次数帮助：

1. 评估复杂度：尝试次数多说明问题复杂
2. 避免无限循环：超过 3 次应考虑换方案
3. 经验积累：知道哪些问题容易解决

模板定制

按项目类型定制

Web 应用项目模板：

# Task Plan: [项目名称]

## Goal
[目标描述]

## Phases

### Phase 1: 需求分析
- **Status:** pending

### Phase 2: 数据库设计
- **Status:** pending

### Phase 3: 后端 API
- **Status:** pending

### Phase 4: 前端实现
- **Status:** pending

### Phase 5: 测试与部署
- **Status:** pending

研究项目模板：

# Task Plan: [研究主题]

## Goal
[研究目标]

## Phases

### Phase 1: 文献调研
- **Status:** pending

### Phase 2: 数据收集
- **Status:** pending

### Phase 3: 分析与结论
- **Status:** pending

## Key Questions
- 问题 1
- 问题 2

团队共享模板

将模板放在项目根目录：

.project/
└── templates/
    └── task_plan_template.md

团队成员可以复制使用：

cp .project/templates/task_plan_template.md task_plan.md

实战案例

案例：电商平台订单系统

task_plan.md：

# Task Plan: 电商平台订单系统

## Goal
实现完整的订单生命周期管理，包括下单、支付、发货、收货、售后流程。

## Context
- 预计日订单量：10000+
- 需要支持多种支付方式
- 需要与现有库存系统集成

## Phases

### Phase 1: 需求分析与设计
- [x] 确认订单状态流转
- [x] 设计订单数据模型
- [x] 定义 API 接口规范
- **Status:** complete
- **Started:** 2026-03-20 09:00
- **Completed:** 2026-03-20 12:00

### Phase 2: 数据层实现
- [x] 创建订单表及相关表
- [x] 实现订单状态机
- [x] 集成库存系统接口
- **Status:** complete
- **Started:** 2026-03-20 14:00
- **Completed:** 2026-03-21 17:00

### Phase 3: 支付集成
- [x] 接入支付宝
- [x] 接入微信支付
- [ ] 实现支付回调处理
- **Status:** in_progress
- **Started:** 2026-03-22 09:00

### Phase 4: 订单管理后台
- [ ] 订单列表页面
- [ ] 订单详情页面
- [ ] 发货管理
- **Status:** pending

### Phase 5: 用户端实现
- [ ] 下单流程
- [ ] 订单查询
- [ ] 申请售后
- **Status:** pending

### Phase 6: 测试与上线
- [ ] 单元测试
- [ ] 压力测试
- [ ] 灰度发布
- **Status:** pending

## Decisions
| Decision | Rationale | Date |
|----------|-----------|------|
| 使用状态机管理订单状态 | 状态流转复杂，需要严格控制 | 2026-03-20 |
| 支付采用异步回调 | 支付耗时不确定，异步更可靠 | 2026-03-20 |
| 订单号使用雪花算法 | 支持分布式，有序且唯一 | 2026-03-21 |

## Errors Encountered
| Error | Attempt | Resolution | Date |
|-------|---------|------------|------|
| 状态机死锁 | 2 | 使用分布式锁 | 2026-03-21 |
| 支付回调重复处理 | 1 | 添加幂等性检查 | 2026-03-22 |

小结

task_plan.md 核心要点

1. 它是任务的大脑 - 存储目标、进度、决策、错误
2. 阶段划分 3-7 个 - 不太多也不太少
3. 状态追踪三种 - pending / in_progress / complete
4. 决策记录要追溯 - 记录为什么选择这个方案
5. 错误必须记录 - 避免重复犯错

检查清单

在完成任务前，确认：

• Goal 清晰且可验证
• 阶段数量在 3-7 个
• 每个阶段有明确的子任务
• 所有状态都已更新为 complete
• 重要决策已记录
• 遇到的错误已记录解决方案

系列导航：

• ← 上一篇：教程 3：快速开始
• → 下一篇：教程 5：findings.md 研究管理
• 返回：教程系列索引