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. 每个阶段结束后更新 — 标记完成状态并记录错误

注意： 所有三个规划文件都应创建在当前工作目录（项目根目录）中，而不是技能安装文件夹中。

存储边界

使用实际安装的技能目录；CLAUDE_PLUGIN_ROOT 是客户端特定的，且可能未设置。将私有规划文件保存在获授权的位置，避免符号链接或路径逃逸，不要覆盖现有文件，也不要自动提交或发布这些文件。脚本只是经审核后可选使用的辅助工具，并非已安装的钩子；完成检查器支持内置的阶段标题／状态模板，而不支持任意清单，也无法确认任务是否成功。对于暂时性错误，有限次数的重试可能是合理的；只有确实存在尚未解决的决策时才应升级处理，不要在尝试三次后机械地升级。

核心模式

Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent within its retention/capacity limits)

→ Persist only necessary authorized findings; exclude secrets, personal data and private source dumps.

文件用途

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

关键规则

1. 先创建计划

遵循现有项目规划规范和用户提供的计划。不要创建相互竞争的状态文件；如果用户另有要求，也不要编辑附带的计划。

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	立即记录发现	多模态信息应先转为文本，以免丢失
浏览器返回数据	写入文件	截图无法持久保存
开始新阶段	阅读计划／发现	如果上下文已过时，重新确认方向
发生错误	阅读相关文件	需要了解当前状态才能修复
间隔一段时间后恢复工作	阅读所有规划文件	恢复工作状态

5 个问题重启测试

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

问题	答案来源
我现在在哪里？	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 文件
只陈述一次目标，然后置之不理	做决定前重新阅读计划
隐藏错误并静默重试	将错误记录到计划文件中
把所有内容都塞进上下文	将大量内容存入文件
立即开始执行	先创建计划文件
重复失败的操作	跟踪尝试次数并调整方法
在技能目录中创建文件	在你的项目中创建文件

限制

• 仅当任务明显符合上述范围时，才使用此技能。
• 不要将输出视为环境特定验证、测试或专家审查的替代品。
• 如果缺少必需的输入、权限、安全边界或成功标准，请暂停并请求澄清。