介绍
# Planning with Files
像 Manus 一样工作：使用持久的 markdown 文件作为你的“磁盘工作记忆”。
## 首先：检查上次会话 (v2.2.0)
**在开始工作之前**，检查来自上次会话的未同步上下文：
```bash # Linux/macOS $(command -v python3 || command -v python) ${CLAUDE_PLUGIN_ROOT}/scripts/session-catchup.py "$(pwd)" ```
```powershell # 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/` - **你的规划文件** 放在 **你的项目目录** 中
| 位置 | 存放内容 | |----------|-----------------| | Skill 目录 (`${CLAUDE_PLUGIN_ROOT}/`) | 模板、脚本、参考文档 | | 你的项目目录 | `task_plan.md`、`findings.md`、`progress.md` |
## 快速开始
在任何复杂任务之前：
1. **创建 `task_plan.md`** — 参考 [templates/task_plan.md](templates/task_plan.md) 2. **创建 `findings.md`** — 参考 [templates/findings.md](templates/findings.md) 3. **创建 `progress.md`** — 参考 [templates/progress.md](templates/progress.md) 4. **在做出决策前重新阅读计划** — 刷新注意力窗口中的目标 5. **在每个阶段后更新** — 标记完成，记录错误
> **注意：** 规划文件应放在你的项目根目录，而不是 skill 安装文件夹中。
## 核心模式
``` 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-操作规则
> “每执行 2 次 view/browser/search 操作后，**立即**将关键发现保存到文本文件。”
这可以防止视觉/多模态信息丢失。
### 3. 决策前先阅读
在做重大决策之前，阅读计划文件。这能让目标保持在你的注意力窗口中。
### 4. 执行后更新
完成任何阶段后： - 标记阶段状态：`in_progress` → `complete` - 记录遇到的任何错误 - 注明已创建/修改的文件
### 5. 记录所有错误
每个错误都要写入计划文件。这能积累知识并防止重复。
```markdown ## Errors Encountered | Error | Attempt | Resolution | |-------|---------|------------| | FileNotFoundError | 1 | Created default config | | API timeout | 2 | Added retry logic | ```
### 6. 绝不重复失败
``` if action_failed: next_action != same_action ```
追踪你尝试过的方法。调整方法。
## 3 次错误规则协议
``` 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/task_plan.md) — 阶段跟踪 - [templates/findings.md](templates/findings.md) — 研究存储 - [templates/progress.md](templates/progress.md) — 会话记录
## 脚本
用于自动化的辅助脚本：
- `scripts/init-session.sh` — 初始化所有规划文件 - `scripts/check-complete.sh` — 验证所有阶段是否完成 - `scripts/session-catchup.py` — 从上次会话恢复上下文 (v2.2.0)
## 高级主题
- **Manus 原则：** 参见 [reference.md](reference.md) - **真实示例：** 参见 [examples.md](examples.md)
## 反模式
| 不要做 | 应该这样做 | |-------|------------| | 使用 TodoWrite 进行持久化 | 创建 task_plan.md 文件 | | 陈述一次目标后便遗忘 | 在决策前重读计划 | | 隐藏错误并静默重试 | 将错误记录到计划文件 | | 把所有内容塞进上下文 | 将大内容存储在文件中 | | 立即开始执行 | 先创建计划文件 | | 重复失败的操作 | 追踪尝试，调整方法 | | 在 skill 目录中创建文件 | 在你的项目中创建文件 |