planning-with-files

使用文件进行规划

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

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

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

# Linux/macOS
$(command -v python3 || command -v python) ${CLAUDE_PLUGIN_ROOT}/scripts/session-catchup.py "$(pwd)"

# Windows PowerShell
& (Get-Command python -ErrorAction SilentlyContinue).Source "$env:USERPROFILE\.claude\skills\planning-with-files\scripts\session-catchup.py" (Get-Location)

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

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. 两次操作规则

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

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

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 原则： docs/workflow.md
• 真实示例： examples/
• IDE 集成： Cursor、Codex、Gemini 等

反模式

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

---

致谢

此技能基于 Othman Adi 的 planning-with-files，采用 MIT 许可证。原始实现介绍了面向 AI 编码 Agent 的“Manus 风格”基于文件的规划模式。