Planning-with-files 教程 6：progress.md 会话日志

教程概述

progress.md 是 3-File Pattern 中的"日记"，记录会话中的动作、测试结果和错误历史。它是会话恢复的关键文件。

你将学到

✅ progress.md 的完整结构
✅ 会话日志的记录方法
✅ 测试结果的组织方式
✅ 5-Question Reboot Test 的使用
✅ Session Recovery 的工作原理

progress.md 的作用

flowchart TB
    subgraph 会话生命周期
        A[会话开始] --> B[创建 progress.md]
        B --> C[记录动作]
        C --> D[记录测试]
        D --> E[记录错误]
        E --> F{继续工作?}
        F -->|是| C
        F -->|否| G[会话结束]
        G --> H{需要恢复?}
        H -->|是| I[从 progress.md 恢复]
        H -->|否| J[完成]
    end

    style B fill:#e8f5e9
    style I fill:#fff3e0

与其他文件的区别

文件	类比	存储
task_plan.md	大脑	目标、阶段、状态
findings.md	知识库	发现、决策、资源
progress.md	日记	动作、测试、错误

为什么需要 progress.md？

问题场景：

你：我刚才做了什么来着？
AI：让我回忆一下...（翻阅长上下文）
AI：我好像改了几个文件，但不确定具体改了什么

有 progress.md 后：

你：我刚才做了什么来着？
AI：让我查看 progress.md...
AI：你在 10:30 完成了数据库迁移，修改了 schema.sql
    在 11:00 完成了 API 实现，修改了 api/tags.ts

标准结构

完整模板

# Progress: [任务名称]

## Session Log
| Time | Action | Files Modified | Notes |
|------|--------|----------------|-------|
| [时间] | [动作描述] | [文件列表] | [备注] |

## Actions Taken
- [ ] [待完成的动作]
- [x] [已完成的动作]

## Test Results
| Test | Status | Coverage/Notes |
|------|--------|----------------|
| [测试名] | ✅/❌ | [详情] |

## Error Log
| Time | Error | Resolution | Status |
|------|-------|------------|--------|
| [时间] | [错误描述] | [解决方案] | [状态] |

## 5-Question Reboot Test
| Question | Answer |
|----------|--------|
| Where am I? | [当前阶段] |
| Where am I going? | [下一阶段] |
| What's the goal? | [任务目标] |
| What have I learned? | [关键发现] |
| What have I done? | [完成动作] |

各部分详解

Session Log

按时间顺序记录每个动作：

## Session Log
| Time | Action | Files Modified | Notes |
|------|--------|----------------|-------|
| 10:00 | 开始任务，创建规划文件 | task_plan.md, findings.md, progress.md | - |
| 10:15 | 研究现有数据库结构 | schema.sql | 发现无标签表 |
| 10:30 | 设计数据模型 | findings.md | 确定多对多关系 |
| 11:00 | 创建迁移脚本 | migrations/001_add_tags.sql | - |
| 11:15 | 执行迁移，遇到错误 | - | 外键约束失败 |
| 11:20 | 修复迁移脚本 | migrations/001_add_tags.sql | 先创建表再添加约束 |
| 11:30 | 迁移成功 | - | Phase 2 完成 |

Actions Taken

任务列表视图：

## Actions Taken

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

### Phase 2: 数据库实现
- [x] 创建标签表
- [x] 创建关联表
- [x] 执行迁移

### Phase 3: API 实现
- [ ] 标签 CRUD 接口
- [ ] 文章标签关联
- [ ] 筛选功能

Test Results

测试结果记录：

## Test Results

### Unit Tests
| Test Suite | Status | Coverage |
|------------|--------|----------|
| tag.test.ts | ✅ Pass | 85% |
| article.test.ts | ✅ Pass | 82% |

### Integration Tests
| Test | Status | Notes |
|------|--------|-------|
| API: GET /api/tags | ✅ Pass | 响应时间 45ms |
| API: POST /api/tags | ✅ Pass | - |
| API: 标签筛选 | ❌ Fail | 分页参数错误 |

### E2E Tests
| Scenario | Status | Notes |
|----------|--------|-------|
| 创建标签流程 | ✅ Pass | - |
| 标签筛选流程 | ⏳ Pending | 等待修复 |

Error Log

错误及解决记录：

## Error Log
| Time | Error | Resolution | Status |
|------|-------|------------|--------|
| 11:15 | 外键约束失败 | 先创建表再添加约束 | ✅ 已解决 |
| 14:30 | JWT 验证失败 | 检查密钥配置 | ✅ 已解决 |
| 15:00 | CORS 错误 | 添加 credentials 配置 | 🔄 调查中 |

会话日志记录

记录时机

flowchart LR
    A[执行动作] --> B{动作类型?}
    B -->|文件修改| C[记录到 Session Log]
    B -->|运行测试| D[记录到 Test Results]
    B -->|遇到错误| E[记录到 Error Log]
    B -->|完成阶段| F[更新 Actions Taken]

    C --> G[更新 progress.md]
    D --> G
    E --> G
    F --> G

记录原则

应该记录：

✅ 每次文件创建/修改
✅ 测试执行结果
✅ 错误及解决方案
✅ 阶段完成

不需要记录：

❌ 每个微小的命令
❌ 临时调试输出
❌ 中间思考过程

记录格式最佳实践

好的记录：

| Time | Action | Files Modified | Notes |
|------|--------|----------------|-------|
| 11:00 | 创建标签表迁移脚本 | migrations/001_add_tags.sql | 包含 tags 和 article_tags 表 |

不好的记录：

| Time | Action | Files Modified | Notes |
|------|--------|----------------|-------|
| 11:00 | 做了一些事 | - | - |

测试结果记录

测试类型

测试类型	记录内容	更新频率
单元测试	测试套件、覆盖率	每次运行后
集成测试	API 端点、响应时间	每次运行后
E2E 测试	用户场景、流程验证	每次运行后
性能测试	响应时间、资源使用	关键节点

测试结果格式

## Test Results

### Unit Tests
运行时间: 2026-03-26 15:30

| Suite | Tests | Passed | Failed | Coverage |
|-------|-------|--------|--------|----------|
| tags | 12 | 12 | 0 | 85% |
| articles | 15 | 14 | 1 | 82% |
| auth | 8 | 8 | 0 | 90% |

**失败的测试**:
- `articles.test.ts: should filter by tag` - 分页参数错误

### Integration Tests
运行时间: 2026-03-26 15:45

| Endpoint | Status | Response Time | Notes |
|----------|--------|---------------|-------|
| GET /api/tags | ✅ | 45ms | - |
| POST /api/tags | ✅ | 52ms | - |
| GET /api/tags/:id/articles | ❌ | 500ms | 需要优化查询 |

测试趋势追踪

### Test History

| Date | Total | Passed | Failed | Coverage |
|------|-------|--------|--------|----------|
| 03-24 | 25 | 22 | 3 | 70% |
| 03-25 | 32 | 30 | 2 | 78% |
| 03-26 | 35 | 34 | 1 | 85% |

**趋势分析**: 测试覆盖率稳步上升，失败用例持续减少。

错误日志

错误记录的重要性

flowchart TD
    A[遇到错误] --> B[记录到 Error Log]
    B --> C[分析根本原因]
    C --> D[找到解决方案]
    D --> E[记录解决方案]
    E --> F[更新状态: 已解决]

    style B fill:#ffcdd2
    style F fill:#c8e6c9

错误记录格式

完整格式：

| Time | Error | Resolution | Status |
|------|-------|------------|--------|
| 11:15 | 数据库迁移失败: 外键约束 | 修改迁移脚本，先创建表再添加外键 | ✅ 已解决 |
| 14:30 | JWT 验证失败: invalid signature | 统一使用环境变量配置密钥 | ✅ 已解决 |
| 15:00 | CORS 错误: credentials not allowed | 添加 credentials: 'include' 配置 | 🔄 调查中 |

错误状态

状态	含义
🔄 调查中	正在分析原因
⏳ 待解决	原因已找到，等待修复
✅ 已解决	已修复并验证
❌ 无法解决	需要外部帮助或放弃

错误与 task_plan.md 的关联

错误应该同时记录在两个文件：

progress.md（详细记录）：

| Time | Error | Resolution | Status |
|------|-------|------------|--------|
| 11:15 | 外键约束失败 | 先创建表再添加约束 | ✅ 已解决 |

task_plan.md（摘要）：

## Errors Encountered
| Error | Attempt | Resolution | Date |
|-------|---------|------------|------|
| 外键约束失败 | 1 | 先创建表再添加约束 | 2026-03-26 |

5-Question Reboot Test

什么是 5-Question Reboot Test？

这是一个用于验证上下文是否完整的测试。如果无法回答这 5 个问题，说明需要查看规划文件。

flowchart TD
    A[5-Question Test] --> B{Q1: Where am I?}
    B -->|能回答| C{Q2: Where am I going?}
    B -->|不能| D[查看 task_plan.md]
    C -->|能回答| E{Q3: What's the goal?}
    C -->|不能| D
    E -->|能回答| F{Q4: What have I learned?}
    E -->|不能| G[查看 findings.md]
    F -->|能回答| H{Q5: What have I done?}
    F -->|不能| G
    H -->|能回答| I[上下文完整 ✅]
    H -->|不能| J[查看 progress.md]

    style I fill:#c8e6c9

五个问题

问题	答案来源	示例回答
Where am I?	task_plan.md Phase	Phase 2: 数据库实现，进行中
Where am I going?	task_plan.md 剩余 Phases	Phase 3-5: API、前端、测试
What’s the goal?	task_plan.md Goal	为博客添加标签系统
What have I learned?	findings.md	使用多对多关系，选择 Zustand
What have I done?	progress.md	创建了迁移脚本，修复了外键错误

使用场景

场景 1：长时间中断后恢复

你：我昨天做了一半，今天继续。我做到哪了？
AI：让我回答 5-Question Test...

Q1: Where am I? → Phase 2，已完成
Q2: Where am I going? → Phase 3: API 实现
Q3: What's the goal? → 博客标签系统
Q4: What have I learned? → 多对多关系，Prisma 方案
Q5: What have I done? → 完成迁移脚本，修复外键错误

接下来应该：开始 Phase 3，实现标签 CRUD 接口

场景 2：上下文膨胀后

AI：上下文快满了，需要总结...
AI：执行 5-Question Test 确认关键信息都在文件中...

✅ 所有问题都能从文件回答
✅ 可以安全地继续或重启会话

场景 3：团队交接

开发者 A：我要休假了，项目交接给你
开发者 B：好的，让我了解一下状态...

（阅读三个文件后）

开发者 B：
- 当前在 Phase 2，已完成
- 下一步是 Phase 3 API 实现
- 目标是标签系统
- 已决定用多对多关系
- 已完成迁移脚本

我可以接手了！

Session Recovery 机制

什么是 Session Recovery？

当 Claude Code 会话被清除（/clear）后，Planning-with-files 可以自动恢复之前的工作状态。

sequenceDiagram
    participant User
    participant Claude
    participant Files as 规划文件

    Note over User,Files: 正常工作
    User->>Claude: 完成部分工作
    Claude->>Files: 更新 progress.md

    Note over User,Files: 上下文满，清除
    User->>Claude: /clear
    Claude->>Claude: 上下文重置

    Note over User,Files: 恢复会话
    User->>Claude: 继续工作
    Claude->>Files: 读取 task_plan.md
    Claude->>Files: 读取 findings.md
    Claude->>Files: 读取 progress.md
    Claude->>User: 恢复状态，继续工作

Session Recovery 工作原理

检测恢复点：查找项目目录中的规划文件
读取状态：从 task_plan.md 读取当前阶段
恢复知识：从 findings.md 读取已发现的信息
恢复进度：从 progress.md 读取已完成的动作
生成恢复报告：总结需要继续的工作

恢复报告示例

[Session Recovery]

检测到未完成的任务: 博客标签系统

当前状态:
- Phase 1: 需求分析 ✅ complete
- Phase 2: 数据库实现 ✅ complete
- Phase 3: API 实现 🔄 in_progress (30%)
- Phase 4: 前端实现 ⏳ pending
- Phase 5: 测试部署 ⏳ pending

上次会话完成:
- 创建了标签表迁移脚本
- 修复了外键约束错误
- 开始实现标签 CRUD 接口

接下来应该:
1. 完成标签 CRUD 接口
2. 实现文章标签关联
3. 开始 Phase 4 前端实现

是否继续之前的任务？

启用 Session Recovery

方法 1：使用 SessionStart Hook（推荐）

{
  "hooks": {
    "SessionStart": {
      "command": "bash .claude/hooks/session-start.sh"
    }
  }
}

方法 2：手动触发

/plan:status

禁用自动 Compact

为了最大化上下文利用率：

{
  "autoCompact": false
}

这样在上下文满时手动 /clear，而不是自动压缩，确保 Session Recovery 能完整恢复。

实战案例

完整的 progress.md 示例

# Progress: 博客标签系统

## Session Log

### 2026-03-26 上午
| Time | Action | Files Modified | Notes |
|------|--------|----------------|-------|
| 10:00 | 开始任务，创建规划文件 | task_plan.md, findings.md, progress.md | - |
| 10:15 | 研究现有数据库结构 | prisma/schema.prisma | 发现无标签表 |
| 10:30 | 确定数据模型 | findings.md | 多对多关系 |
| 10:45 | 完成 Phase 1 | task_plan.md | Status: complete |
| 11:00 | 创建迁移脚本 | migrations/20260326_add_tags.sql | - |
| 11:15 | 执行迁移失败 | - | 外键约束错误 |
| 11:20 | 修复迁移脚本 | migrations/20260326_add_tags.sql | 先创建表再添加约束 |
| 11:30 | 迁移成功 | task_plan.md | Phase 2 complete |

### 2026-03-26 下午
| Time | Action | Files Modified | Notes |
|------|--------|----------------|-------|
| 14:00 | 开始 Phase 3 | task_plan.md | Status: in_progress |
| 14:30 | 实现标签 CRUD 接口 | src/app/api/tags/route.ts | - |
| 15:00 | 实现文章标签关联 | src/app/api/articles/[id]/tags/route.ts | - |
| 15:30 | 编写单元测试 | tests/tags.test.ts | - |

## Actions Taken

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

### Phase 2: 数据库实现 ✅
- [x] 创建标签表
- [x] 创建关联表
- [x] 执行迁移

### Phase 3: API 实现 🔄
- [x] 标签 CRUD 接口
- [x] 文章标签关联接口
- [ ] 按标签筛选接口
- [ ] API 文档

### Phase 4: 前端实现 ⏳
- [ ] 标签组件
- [ ] 筛选功能

### Phase 5: 测试部署 ⏳
- [ ] 集成测试
- [ ] 部署上线

## Test Results

### Unit Tests (2026-03-26 15:45)
| Suite | Tests | Passed | Failed | Coverage |
|-------|-------|--------|--------|----------|
| tags.test.ts | 12 | 12 | 0 | 85% |
| articles.test.ts | 8 | 8 | 0 | 80% |

### Integration Tests (2026-03-26 16:00)
| Endpoint | Status | Response Time |
|----------|--------|---------------|
| GET /api/tags | ✅ Pass | 45ms |
| POST /api/tags | ✅ Pass | 52ms |
| GET /api/articles?tag=xxx | ⏳ Pending | - |

## Error Log
| Time | Error | Resolution | Status |
|------|-------|------------|--------|
| 11:15 | 外键约束失败 | 先创建表再添加约束 | ✅ 已解决 |
| 15:15 | TypeScript 类型错误 | 添加 Tag 类型定义 | ✅ 已解决 |

## 5-Question Reboot Test
| Question | Answer |
|----------|--------|
| Where am I? | Phase 3: API 实现，进行中 |
| Where am I going? | Phase 4: 前端实现 |
| What's the goal? | 博客标签系统，支持多对多和筛选 |
| What have I learned? | Prisma 多对多，扁平标签结构 |
| What have I done? | 完成数据库迁移和标签 CRUD 接口 |

小结

progress.md 核心要点

日记定位 - 记录动作、测试、错误
时间线清晰 - Session Log 按时间记录
测试可追踪 - Test Results 记录每次运行
错误有闭环 - Error Log 记录状态变化
恢复有依据 - 5-Question Test 验证完整性

检查清单

每次文件修改记录到 Session Log
测试结果记录到 Test Results
错误记录到 Error Log 并追踪状态
能回答 5-Question Reboot Test
Session Recovery 文件就绪

系列导航：