planning-with-files

使用文件进行规划——Manus 风格的基于文件规划

像 Manus 一样工作（Meta 收购的估值 20 亿美元的 AI Agent）：使用持久化 Markdown 文件作为“存储在磁盘上的工作记忆”。

核心原则

Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)

→ Anything important gets written to disk.

三文件模式

对于每项复杂任务，都在项目目录中创建三个文件：

task_plan.md      → Track phases and progress
findings.md       → Store research and findings
progress.md       → Session log and test results

模板位于： .claude/templates/planning/

何时使用此模式

适用于：

• 多步骤任务（3 步以上）
• 研究任务
• 构建／创建项目
• 涉及大量工具调用的任务
• 任何需要组织规划的任务

不适用于：

• 简单问题
• 单文件编辑
• 快速查询

关键时间规则

这些规则模拟钩子，以确保工作流正确执行：

📌 任务开始时（SessionStart）

必须先创建全部三个文件，再进行任何其他工作：

1. 使用模板创建 task_plan.md
2. 使用模板创建 findings.md
3. 使用模板创建 progress.md
4. 填写 task_plan.md 中的 Goal 部分

**原因：**没有规划文件，进行 50 多次工具调用后就会忘记目标。

📌 做出重大决策前（PreToolUse）

在以下操作之前，必须重新阅读 task_plan.md：

• 编写或编辑文件
• 执行命令
• 做出架构决策
• 实现功能

**方法：**使用 Read 工具，在上下文中刷新计划。

**原因：**这能让目标始终处于注意力窗口中（Manus 所说的“注意力操控”）。

📌 文件操作后（PostToolUse）

在以下操作后，必须立即更新状态：

• 编写文件
• 编辑文件
• 完成一个任务阶段

**方法：**编辑 task_plan.md，更新阶段状态：

- **Status:** pending → in_progress → complete

**原因：**记录进度，避免忘记已完成的事项。

📌 任务结束前（Stop）

必须确认任务已完成：

• 检查所有阶段是否都标记为 complete
• 检查交付物部分
• 确保没有尚未解决的错误

**原因：**避免工作尚未完成就过早结束。

六条关键规则

1. 先创建计划

复杂任务开始前，必须先创建 task_plan.md。这是不可妥协的要求。

## Goal

[One sentence describing the end state]

## Current Phase

Phase 1

## Phases

### Phase 1: Requirements & Discovery

- [ ] Understand user intent
- [ ] Identify constraints
- **Status:** in_progress

2. 两次操作规则

“每进行两次查看／浏览器／搜索操作后，立即将关键发现保存到 findings.md。”

这样可以避免视觉／多模态信息丢失。

## Visual/Browser Findings

- Screenshot shows login form with email and password fields
- API documentation indicates JSON response format

3. 决策前先阅读

做出重大决策前，先阅读计划文件。这能让目标始终处于注意力窗口中。

# Before implementing a feature:
Read tool → task_plan.md
# Now proceed with implementation

4. 操作后更新

完成任何阶段后：

• 标记阶段状态：pending → in_progress → complete
• 记录遇到的错误
• 记下新建／修改的文件

## Errors Encountered

| Error             | Attempt | Resolution             |
| ----------------- | ------- | ---------------------- |
| FileNotFoundError | 1       | Created default config |

5. 记录所有错误

将每个错误都记入计划文件。这有助于积累知识，避免重复犯错。

6. 切勿重复失败尝试

if action_failed:
    next_action != same_action

记录尝试过的方法，并调整策略。

三次尝试错误处理流程

ATTEMPT 1: Diagnose & Fix
  → Read error carefully
  → Identify root cause
  → Apply targeted fix

ATTEMPT 2: Alternative Approach
  → Same error? Try different method
  → Different tool? Different library?
  → NEVER repeat exact same failing action

ATTEMPT 3: Broader Rethink
  → Question assumptions
  → Search for solutions
  → Consider updating the plan

AFTER 3 FAILURES: Escalate to User
  → Explain what you tried
  → Share the specific error
  → Ask for guidance

文件用途

文件	用途	更新时机
task_plan.md	阶段、进度、决策	每个阶段结束后
findings.md	研究、发现	任何发现之后
progress.md	会话日志、测试结果	整个会话期间

读写决策表

情况	操作	原因
刚写入文件	不要读取	内容仍在上下文中
查看了图像／PDF	立即写入 findings	多模态信息须在丢失前转为文本
浏览器返回了数据	写入文件	截图不会持久保存
开始新阶段	阅读计划／发现	上下文过时时重新调整方向
出现错误	阅读相关文件	需要了解当前状态才能修复
间隔一段时间后恢复工作	阅读所有规划文件	恢复工作状态

5 个问题重启测试

如果你能回答这些问题，说明你的上下文管理很稳健：

问题	答案来源
我在哪里？	task_plan.md 中的当前阶段
我要去哪里？	剩余阶段
目标是什么？	计划中的目标陈述
我学到了什么？	findings.md
我做了什么？	progress.md

模板结构

task_plan.md 模板

# Task Plan: [Brief Description]

## Goal

[One sentence describing the end state]

## Current Phase

Phase 1

## Phases

### Phase 1: Requirements & Discovery

- [ ] Understand user intent
- [ ] Identify constraints and requirements
- [ ] Document findings in findings.md
- **Status:** in_progress

### Phase 2: Planning & Structure

- [ ] Define technical approach
- [ ] Create project structure if needed
- [ ] Document decisions with rationale
- **Status:** pending

### Phase 3: Implementation

- [ ] Execute the plan step by step
- [ ] Write code to files before executing
- [ ] Test incrementally
- **Status:** pending

### Phase 4: Testing & Verification

- [ ] Verify all requirements met
- [ ] Document test results in progress.md
- [ ] Fix any issues found
- **Status:** pending

### Phase 5: Delivery

- [ ] Review all output files
- [ ] Ensure deliverables are complete
- [ ] Deliver to user
- **Status:** pending

## Key Questions

1. [Question to answer]
2. [Question to answer]

## Decisions Made

| Decision | Rationale |
| -------- | --------- |
|          |           |

## Errors Encountered

| Error | Attempt | Resolution |
| ----- | ------- | ---------- |
|       | 1       |            |

findings.md 模板

# Findings & Decisions

## Requirements

_Add requirements captured from user request here._

## Research Findings

_Document key discoveries during exploration here._

## Technical Decisions

_Record decisions made with rationale._

| Decision | Rationale |
| -------- | --------- |
|          |           |

## Issues Encountered

_Document errors and how they were resolved._

| Issue | Resolution |
| ----- | ---------- |
|       |            |

## Resources

_Add URLs, file paths, and API references here._

## Visual/Browser Findings

_CRITICAL: Update after every 2 view/browser operations._

progress.md 模板

# Progress Log

## Session: [DATE]

### Phase 1: [Title]

- **Status:** in_progress
- **Started:** [timestamp]
- Actions taken:
- Files created/modified:

## Test Results

| Test | Input | Expected | Actual | Status |
| ---- | ----- | -------- | ------ | ------ |
|      |       |          |        |        |

## Error Log

| Timestamp | Error | Attempt | Resolution |
| --------- | ----- | ------- | ---------- |
|           |       | 1       |            |

## 5-Question Reboot Check

| Question             | Answer           |
| -------------------- | ---------------- |
| Where am I?          | Phase X          |
| Where am I going?    | Remaining phases |
| What's the goal?     | [goal statement] |
| What have I learned? | See findings.md  |
| What have I done?    | See above        |

铁律

1. 务必在开始任何复杂任务之前创建 task_plan.md、findings.md 和 progress.md——文件系统中的记忆在上下文重置后仍然存在，而工作记忆不会。
2. 务必在做出重大决策之前重新阅读 task_plan.md——上下文窗口不稳定，而文件会一直保留。
3. 绝不要使用完全相同的输入重试失败的操作——在计划文件中记录失败，诊断根本原因，并调整方法。
4. 务必在获取多模态发现（屏幕截图、浏览器数据）后立即将其写入 findings.md——视觉上下文一旦离开注意力窗口，就无法再找回。
5. 绝不要在未确认所有阶段均为 complete 且所有交付物均已记录在进度文件中时，就将任务标记为完成。

反模式

反模式	失败原因	正确做法
使用会话任务工具进行持久化	内存中的任务跟踪不稳定；上下文重置后会丢失	在磁盘上创建 task_plan.md 文件——重置后仍会保留
陈述一次目标后便将其遗忘	上下文会逐渐填满；目标会失焦，缺少锚定	每次做出重大决策前重新阅读计划文件
隐藏错误并静默重试	静默重试会无休止地重复相同的失败	在计划文件中记录每个错误及尝试次数
将所有研究都塞进上下文	上下文窗口会被填满；较早的内容会丢失	将大量内容和发现存储在 findings.md 中
不做计划就开始执行	范围不明确会导致工作浪费和步骤遗漏	在采取任何行动之前，先创建全部三个计划文件

Manus 原则

原则	实施方式
将文件系统用作记忆	存储在文件中，而非上下文
注意力管理	决策前重新阅读计划
错误持久化	在计划文件中记录失败
目标跟踪	使用复选框显示进度
完成情况验证	停止前检查所有阶段

---

请记住： 前期收集并写入磁盘的上下文越多，执行效果就越好。文件就是你的持久记忆。