planning-with-files

使用文件进行规划

将持久化的 Markdown 文件用作磁盘上的工作记忆。

快速开始

1. 创建规划文件——使用 /plan，或根据模板手动创建
2. 创建 task_plan.md，写明目标、阶段和关键问题
3. 创建 findings.md，记录研究结果和决策
4. 创建 progress.md，记录会话日志
5. 决策前重新阅读计划——让目标重新进入注意力范围
6. 每个阶段结束后更新——标记状态并记录错误

适用场景

• 多步骤任务（3 个以上阶段）
• 需要多次搜索的研究项目
• 涉及多个文件的项目构建或创建
• 需要多次工具调用（超过 10 次）的任务
• 任何一旦偏离目标就会造成高昂代价的工作
• 可能跨越多个会话的任务

不适用场景

• 简单问题或快速查询
• 范围明确的单文件编辑
• 少于 5 次工具调用即可完成的任务
• 无需实现的对话交流

核心模式

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

Anything important gets written to disk.

经过多次工具调用后，最初的目标会逐渐从注意力窗口中淡出。阅读 task_plan.md 能让目标重新浮现。这是基于文件进行规划时最重要的模式。

文件用途

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

这三个文件都应放在项目根目录，而不是插件目录中。

关键规则

1. 先创建计划

没有 task_plan.md，绝不要开始复杂任务。这一点不容妥协。计划就是你的持久化记忆。

2. 两步操作规则

每进行 2 次搜索、浏览或读取操作后，立即将关键发现保存到 findings.md。多模态内容（图像、浏览器结果、PDF 内容）不会保留在上下文中——在其消失前将其记录为文本。

3. 决策前先阅读

在做出任何重大决策前，重新阅读 task_plan.md。这会让目标和上下文重新进入近期注意力窗口，从而抵消大约 50 次工具调用后出现的“中间遗失”效应。

[Original goal -- far away in context, forgotten]
...many tool calls...
[Recently read task_plan.md -- gets ATTENTION]
→ Now make the decision with goals fresh in context

4. 执行后更新

完成任何阶段后：

• 将阶段状态标记为：in_progress -> complete
• 在错误表中记录遇到的错误
• 在 progress.md 中注明创建或修改的文件

5. 记录所有错误

每个错误都要记录在 task_plan.md 中。注明尝试次数和解决方法。这样可以积累经验，避免重复失败。

## Errors Encountered
| Error | Attempt | Resolution |
|-------|---------|------------|
| FileNotFoundError | 1 | Created default config |
| API timeout | 2 | Added retry logic |

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 a different method
  -> Different tool? Different library?
  -> NEVER repeat the 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 (with attempt log)
  -> Share the specific error
  -> Ask for guidance

读取与写入决策矩阵

情况	操作	原因
刚写入文件	不要读取	内容仍在上下文中
查看了图像/PDF	立即写下发现	多模态内容不会保留
浏览器返回了数据	写入文件	截图不会保留
开始新阶段	读取计划/发现	上下文过时则重新梳理方向
发生错误	读取相关文件	需要了解当前状态才能修复
间隔一段时间后恢复工作	读取所有规划文件	恢复完整状态

五问重启测试

如果你能根据规划文件回答以下问题，说明上下文完整：

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

反模式

不要这样做	应改为
只陈述一次目标，然后置之不理	做决定前重新阅读计划
隐瞒错误并静默重试	将每个错误记录到计划文件
把所有内容都塞进上下文	将大量内容存储在文件中
立即开始执行	先创建计划文件
重复失败的操作	跟踪尝试次数，调整方法
在插件目录中创建文件	在项目根目录中创建文件

参考资料

• 模板 -- 适用于全部三种规划文件的起始模板
• 原则 -- 此方法背后的上下文工程原则
• 示例 -- 具体示例和错误恢复模式