planning-with-files

使用文件进行规划

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

重要：文件存放位置

使用此技能时：

• 模板存储在技能目录 ${CLAUDE_PLUGIN_ROOT}/templates/ 中
• 你的规划文件（task_plan.md、findings.md、progress.md）应创建在你的项目目录中——即你正在工作的文件夹

位置	存放内容
技能目录（${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 — 验证所有阶段均已完成

进阶主题

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

反模式

不要	而应
使用 TodoWrite 进行持久化	创建 task_plan.md 文件
只陈述一次目标然后抛诸脑后	做决策前重新阅读计划
隐藏错误并静默重试	将错误记录到计划文件
把所有内容都塞进上下文	将大型内容存储在文件中
立即开始执行	首先创建计划文件
重复失败的操作	记录尝试次数，改变方法
在 skill 目录中创建文件	在你的项目中创建文件