Planning-with-files 教程 3：快速开始

教程概述

本教程将通过一个实际案例，带你完成第一个 Planning-with-files 任务。你将学习完整的 5 步工作流程，理解三个文件如何协作。

你将学到

✅ 如何调用规划技能
✅ 如何分解任务阶段
✅ 如何实践 2-Action 规则
✅ 如何追踪任务进度
✅ 如何验证任务完成

示例任务

我们将使用一个常见的场景：为博客添加标签系统

我想给博客添加标签功能，让文章可以有多个标签，用户可以按标签筛选文章。

Step 1：调用技能并描述任务

启动规划会话

在 Claude Code（或其他 AI 编程工具）中，使用 /plan 命令：

/plan 为博客添加标签系统，文章可以有多个标签，用户可以按标签筛选

AI 的响应

AI 会自动创建三个文件：

✓ 创建 task_plan.md
✓ 创建 findings.md
✓ 创建 progress.md

生成的初始文件

task_plan.md（初始版本）：

# Task Plan: 博客标签系统

## Goal
为博客添加标签功能，实现文章与标签的多对多关系，支持按标签筛选文章。

## Phases

### Phase 1: 需求分析与设计
- [ ] 确定标签数据模型
- [ ] 设计 API 接口
- [ ] 确定前端展示方案
- **Status:** in_progress
- **Started:** 2026-03-26 10:00

### Phase 2: 数据库实现
- [ ] 创建标签表
- [ ] 创建文章-标签关联表
- [ ] 编写迁移脚本
- **Status:** pending

### Phase 3: 后端 API 实现
- [ ] 标签 CRUD 接口
- [ ] 文章标签关联接口
- [ ] 按标签筛选接口
- **Status:** pending

### Phase 4: 前端实现
- [ ] 标签列表组件
- [ ] 文章标签选择器
- [ ] 标签筛选功能
- **Status:** pending

### Phase 5: 测试与部署
- [ ] 单元测试
- [ ] 集成测试
- [ ] 部署上线
- **Status:** pending

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

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

findings.md（初始版本）：

# Findings: 博客标签系统

## Research Findings
（将在研究过程中填充）

## Technical Decisions
（将在决策过程中记录）

## Resources & References
（将在发现资源时添加）

progress.md（初始版本）：

# Progress: 博客标签系统

## Session Log
| Time | Action | Files Modified |
|------|--------|----------------|
| 10:00 | 开始任务，创建规划文件 | task_plan.md, findings.md, progress.md |

## Test Results
| Test | Status | Notes |
|------|--------|-------|
| - | - | - |

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

Step 2：规划阶段

阶段划分原则

flowchart LR
    A[复杂任务] --> B{分解阶段}
    B --> C[3-7 个阶段]
    C --> D[每个阶段独立可验证]
    D --> E[明确依赖关系]

    style C fill:#e1f5ff

好的阶段划分：

✅ 每个阶段有明确的目标
✅ 阶段之间有清晰的边界
✅ 可以独立验证完成
✅ 3-7 个阶段为宜

不好的阶段划分：

❌ 阶段过于笼统（如"实现功能"）
❌ 阶段过于细碎（如"创建文件"）
❌ 阶段之间高度耦合

审查并调整阶段

AI 生成的初始阶段可能需要调整。你可以要求修改：

这个阶段划分太细了，Phase 3 和 Phase 4 可以合并吗？

AI 会更新 task_plan.md：

### Phase 3: 功能实现（合并后）
- [ ] 后端标签 CRUD 接口
- [ ] 前端标签组件
- [ ] 标签筛选功能
- **Status:** pending

设置验收标准

在每个阶段中添加验收标准：

### Phase 2: 数据库实现
- [ ] 创建标签表
- [ ] 创建文章-标签关联表
- [ ] 编写迁移脚本
- **Status:** pending
- **Acceptance Criteria:**
  - 迁移脚本无错误执行
  - 数据模型支持多对多关系
  - 外键约束正确设置

Step 3：工作与记录

这是最关键的步骤。在工作过程中，你需要持续更新三个文件。

更新 findings.md

何时更新

触发条件	更新内容
研究/探索代码库	Research Findings
每 2 次查看操作	必须更新！
做出技术决策	Technical Decisions
发现有用资源	Resources & References

2-Action 规则详解

sequenceDiagram
    participant AI as AI 助手
    participant F as findings.md

    AI->>AI: 查看文件 1
    Note over AI: 记录发现（内存）
    AI->>AI: 查看文件 2
    Note over AI: 必须写入 findings.md！
    AI->>F: 更新 Research Findings

    AI->>AI: 搜索关键词
    Note over AI: 记录结果（内存）
    AI->>AI: 获取文档
    Note over AI: 必须写入 findings.md！
    AI->>F: 更新 Research Findings

实际操作示例

操作 1：查看现有数据库结构

AI: 让我先查看现有的数据库模型...

[Read schema.sql]
发现文章表有 id, title, content 字段

操作 2：搜索标签相关代码

AI: 搜索项目中是否有标签相关的实现...

[Grep "tag"]
发现没有现有标签实现，需要从零开始

此时必须更新 findings.md：

# Findings: 博客标签系统

## Research Findings

### 数据库现状
- 文章表 (articles): id, title, content, created_at
- 用户表 (users): id, email, password_hash
- 评论表 (comments): id, article_id, user_id, content
- **无现有标签实现**

### 技术栈确认
- 数据库: MySQL 8.0
- ORM: Prisma
- 前端: React + TypeScript

## Technical Decisions
（待补充）

## Resources & References
- [数据库 schema 文件](./prisma/schema.prisma)

记录技术决策

当你做出决策时，记录到 findings.md：

AI: 基于研究，我建议使用扁平标签（无层级），使用多对多关系表。

用户: 同意，就用这个方案。

更新 findings.md：

## Technical Decisions

### TD-1: 标签结构设计
- **决策**: 采用扁平标签结构，无层级
- **理由**:
  1. 博客标签通常数量有限，无需层级
  2. 实现简单，查询高效
  3. 用户使用直观
- **替代方案**: 层级标签（过于复杂，不适合当前场景）
- **日期**: 2026-03-26

### TD-2: 数据模型选择
- **决策**: 多对多关系表
- **理由**: 一篇文章可有多个标签，一个标签可关联多篇文章
- **模型**: Article ←→ ArticleTag ←→ Tag

更新 progress.md

每完成一个操作，更新 progress.md：

## Session Log
| Time | Action | Files Modified |
|------|--------|----------------|
| 10:00 | 开始任务，创建规划文件 | task_plan.md, findings.md, progress.md |
| 10:15 | 研究现有数据库结构 | findings.md |
| 10:30 | 确定标签数据模型 | findings.md |
| 10:45 | 完成数据库迁移脚本 | migrations/add_tags.sql |

Step 4：决策前重读

PreToolUse Hook 自动触发

如果你配置了 Hooks，在每次 Write/Edit/Bash 操作前，AI 会自动重读 task_plan.md。

flowchart TD
    A[准备执行工具] --> B{PreToolUse Hook}
    B --> C[读取 task_plan.md]
    C --> D[刷新目标到上下文]
    D --> E[执行工具]

    style B fill:#fff3e0
    style C fill:#e1f5ff

为什么这很重要？

注意力操控原理：在长会话中，AI 容易"忘记"原始目标。强制重读计划确保目标始终在注意力中。

手动重读方法

如果没有配置 Hooks，可以手动要求：

在继续之前，请重读 task_plan.md 并确认当前进度

AI 会：

让我重读一下任务计划...

[Read task_plan.md]

当前状态:
- Phase 1: 需求分析与设计 ✅ complete
- Phase 2: 数据库实现 🔄 in_progress
- Phase 3-5: pending

接下来应该: 创建标签表和关联表

Step 5：完成与验证

检查所有阶段状态

在声称完成任务之前，必须验证：

## Phases

### Phase 1: 需求分析与设计
- [x] 确定标签数据模型
- [x] 设计 API 接口
- [x] 确定前端展示方案
- **Status:** complete ✅

### Phase 2: 数据库实现
- [x] 创建标签表
- [x] 创建文章-标签关联表
- [x] 编写迁移脚本
- **Status:** complete ✅

### Phase 3: 功能实现
- [x] 后端标签 CRUD 接口
- [x] 前端标签组件
- [x] 标签筛选功能
- **Status:** complete ✅

### Phase 4: 测试与部署
- [x] 单元测试
- [x] 集成测试
- [x] 部署上线
- **Status:** complete ✅

运行完成检查

自动检查（如果配置了 Stop Hook）：

AI: 任务已完成，所有阶段都已标记为 complete。

[Stop Hook 执行]
检查 task_plan.md...
✓ Phase 1: complete
✓ Phase 2: complete
✓ Phase 3: complete
✓ Phase 4: complete

任务验证通过，可以结束。

手动检查：

# 如果有 check-complete.sh 脚本
./scripts/check-complete.sh

5-Question Reboot Test

在完成任务前，回答这 5 个问题：

问题	答案来源	你的答案
我在哪个阶段？	task_plan.md	Phase 4，已完成
我要去哪里？	task_plan.md	所有阶段已完成
目标是什么？	task_plan.md Goal	为博客添加标签系统
我学到了什么？	findings.md	数据模型设计、API 设计…
我做了什么？	progress.md	创建了迁移、接口、组件…

如果所有问题都能回答，说明你的上下文管理是成功的。

完整示例展示

最终文件状态

task_plan.md（最终版）：

# Task Plan: 博客标签系统

## Goal
为博客添加标签功能，实现文章与标签的多对多关系，支持按标签筛选文章。

## Phases

### Phase 1: 需求分析与设计
- [x] 确定标签数据模型
- [x] 设计 API 接口
- [x] 确定前端展示方案
- **Status:** complete
- **Started:** 2026-03-26 10:00
- **Completed:** 2026-03-26 10:45

### Phase 2: 数据库实现
- [x] 创建标签表 (tags)
- [x] 创建文章-标签关联表 (article_tags)
- [x] 编写迁移脚本
- **Status:** complete
- **Started:** 2026-03-26 10:45
- **Completed:** 2026-03-26 11:30

### Phase 3: 功能实现
- [x] 后端标签 CRUD 接口
- [x] 前端标签组件
- [x] 标签筛选功能
- **Status:** complete
- **Started:** 2026-03-26 11:30
- **Completed:** 2026-03-26 14:00

### Phase 4: 测试与部署
- [x] 单元测试 (覆盖率 82%)
- [x] 集成测试 (全部通过)
- [x] 部署上线
- **Status:** complete
- **Started:** 2026-03-26 14:00
- **Completed:** 2026-03-26 15:30

## Decisions
| Decision | Rationale | Date |
|----------|-----------|------|
| 扁平标签结构 | 简单直观，适合博客场景 | 2026-03-26 |
| 多对多关系表 | 灵活，符合业务需求 | 2026-03-26 |
| 使用 Prisma 迁移 | 与现有技术栈一致 | 2026-03-26 |

## Errors Encountered
| Error | Attempt | Resolution | Date |
|-------|---------|------------|------|
| 迁移脚本外键错误 | 1 | 先创建表再添加约束 | 2026-03-26 11:15 |
| 标签颜色显示异常 | 1 | 添加 CSS 变量 | 2026-03-26 13:30 |

findings.md（最终版）：

# Findings: 博客标签系统

## Research Findings

### 数据库现状
- 文章表 (articles): id, title, content, created_at
- 用户表 (users): id, email, password_hash
- 无现有标签实现

### 技术栈确认
- 数据库: MySQL 8.0
- ORM: Prisma
- 前端: React + TypeScript
- API: REST

### API 设计结果
| 接口 | 方法 | 描述 |
|-----|------|------|
| /api/tags | GET | 获取所有标签 |
| /api/tags | POST | 创建标签 |
| /api/articles/:id/tags | GET | 获取文章标签 |
| /api/articles/:id/tags | PUT | 更新文章标签 |
| /api/tags/:slug/articles | GET | 按标签筛选文章 |

## Technical Decisions

### TD-1: 标签结构设计
- **决策**: 扁平标签，无层级
- **理由**: 简单直观，适合博客场景

### TD-2: 数据模型
- **决策**: 多对多关系表
- **模型**: Article ←→ ArticleTag ←→ Tag

### TD-3: 标签颜色
- **决策**: 预设 10 种颜色，用户不可自定义
- **理由**: 避免颜色混乱，保持视觉一致性

## Resources & References
- [Prisma 多对多关系文档](https://www.prisma.io/docs/concepts/components/prisma-schema/relations/many-to-many-relations)
- [数据库迁移脚本](./migrations/20260326_add_tags.sql)
- [API 文档](./docs/api/tags.md)

progress.md（最终版）：

# Progress: 博客标签系统

## Session Log
| Time | Action | Files Modified |
|------|--------|----------------|
| 10:00 | 开始任务，创建规划文件 | task_plan.md, findings.md, progress.md |
| 10:15 | 研究现有数据库结构 | findings.md |
| 10:30 | 确定标签数据模型 | findings.md |
| 10:45 | 完成 Phase 1 | task_plan.md |
| 11:00 | 创建迁移脚本 | migrations/20260326_add_tags.sql |
| 11:15 | 修复外键错误 | migrations/20260326_add_tags.sql |
| 11:30 | 完成 Phase 2 | task_plan.md |
| 13:00 | 实现后端接口 | src/api/tags.ts, src/api/articles.ts |
| 13:30 | 修复标签颜色显示 | src/components/Tag.tsx |
| 14:00 | 完成 Phase 3 | task_plan.md |
| 14:30 | 编写测试 | tests/tags.test.ts |
| 15:00 | 运行测试，全部通过 | - |
| 15:30 | 完成 Phase 4，任务完成 | task_plan.md |

## Test Results
| Test | Status | Notes |
|------|--------|-------|
| 单元测试 | ✅ Pass | 覆盖率 82% |
| 集成测试 | ✅ Pass | 5/5 通过 |
| E2E 测试 | ✅ Pass | 标签流程正常 |

## Error Log
| Time | Error | Resolution |
|------|-------|------------|
| 11:15 | 外键约束失败 | 先创建表，后添加约束 |
| 13:30 | 标签颜色未显示 | 添加 CSS 变量定义 |

最佳实践总结

1. 永远先创建 task_plan.md

❌ 直接开始工作
✅ 先创建计划文件，再开始工作

2. 严格执行 2-Action 规则

查看操作 1 → 记录
查看操作 2 → 必须更新 findings.md！

3. 记录所有错误，即使快速修复

❌ "这个问题很快解决了，不用记录"
✅ 记录到 Errors 表格，避免重复

4. 阶段完成立即更新状态

❌ 完成后继续工作，稍后更新
✅ 完成 Phase 后立即更新 Status

5. 验证后再声称完成

❌ "我觉得完成了"
✅ 检查所有 Status: complete，通过 Stop Hook

下一步

完成本教程后，继续深入学习：

📖 教程 4：task_plan.md 深度解析 - 掌握阶段划分技巧
📖 教程 5：findings.md 研究管理 - 深入理解 2-Action 规则
📖 教程 6：progress.md 会话日志 - 学会会话恢复

系列导航：