planning-with-files

使用文件进行规划

像 Manus 一样工作：使用持久化的 Markdown 文件作为“磁盘上的工作记忆”。

首先：检查之前的会话（v2.2.0）

开始工作前，检查之前会话中是否有尚未同步的上下文：

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/session-catchup.py "$(pwd)"

如果追赶报告显示有尚未同步的上下文：

1. 运行 git diff --stat 查看实际的代码更改
2. 阅读当前的规划文件
3. 根据追赶报告和 git diff 更新规划文件
4. 然后继续任务

重要提示：文件存放位置

• 模板位于 ${CLAUDE_PLUGIN_ROOT}/templates/
• 规划文件放在项目目录中

位置	存放内容
技能目录（${CLAUDE_PLUGIN_ROOT}/）	模板、脚本、参考文档
项目目录	task_plan.md、findings.md、progress.md

快速入门

开始任何复杂任务前：

1. 创建 task_plan.md —— 参考 templates/task_plan.md
2. 创建 findings.md —— 参考 templates/findings.md
3. 创建 progress.md —— 参考 templates/progress.md
4. 做决定前重新阅读计划 —— 将目标刷新到注意力窗口中
5. 每个阶段结束后更新 —— 标记完成状态并记录错误

注意： 规划文件应放在项目根目录，而不是技能安装目录中。

核心模式

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

→ Anything important gets written to disk.

文件用途

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

关键规则

1. 先创建计划

没有 task_plan.md，绝不开始复杂任务。这是必须遵守的规则。

2. 两次操作规则

“每进行 2 次查看、浏览器或搜索操作后，立即将关键发现保存到文本文件中。”

这可以防止视觉或多模态信息丢失。

3. 决策前先阅读

做出重大决策前，先阅读计划文件。这能让目标保持在注意力窗口中。

4. 操作后更新

完成任何阶段后：

• 将阶段状态从 in_progress 更新为 complete
• 记录遇到的错误
• 记下创建或修改的文件

5. 记录所有错误

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

## 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 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

读取与写入决策矩阵

情况	操作	原因
刚写入文件	不要读取	内容仍在上下文中
查看了图像或 PDF	立即写下发现	在多模态信息丢失前将其转为文本
浏览器返回了数据	写入文件	屏幕截图不会持久保存
开始新阶段	阅读计划和发现	如果上下文已过时，重新确定方向
发生错误	阅读相关文件	修复问题需要了解当前状态
间隔一段时间后恢复工作	阅读所有规划文件	恢复工作状态

五问重启测试

如果你能回答以下问题，说明上下文管理得当：

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

何时使用此模式

适用于：

• 多步骤任务（3 步以上）
• 研究任务
• 构建或创建项目
• 涉及多次工具调用的任务
• 任何需要组织安排的工作

不适用于：

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

模板

复制以下模板以开始：

• templates/task_plan.md —— 阶段跟踪
• templates/findings.md —— 研究记录
• templates/progress.md —— 会话日志

脚本

用于自动化的辅助脚本：

• scripts/init-session.sh — 初始化所有规划文件
• scripts/check-complete.sh — 验证所有阶段是否已完成
• scripts/session-catchup.py — 从上一次会话恢复上下文（v2.2.0）

高级主题

• **Manus 原则：**参见 reference.md
• **实际示例：**参见 examples.md

反模式

不要这样做	建议做法
使用 TodoWrite 进行持久化	创建 task_plan.md 文件
只陈述一次目标，然后置之不理	在做出决定前重新阅读计划
隐瞒错误并静默重试	将错误记录到计划文件中
把所有内容都塞进上下文	将大量内容存储在文件中
立即开始执行	首先创建计划文件
重复失败的操作	跟踪尝试次数，调整方法
在技能目录中创建文件	在项目中创建文件