用途
planning-with-files 是一个面向 AI 智能体的工作方法技能，目标是“像 Manus 一样工作”：使用持久化的 Markdown 文件作为“磁盘上的工作记忆”。它把上下文窗口类比为 RAM（易失、有限），把文件系统类比为磁盘（持久、无限），因此任何重要内容都应写入磁盘。
主要能力
该技能围绕三个规划文件组织工作：
- task_plan.md：记录阶段、进度与决策，在每个阶段完成后更新。
- findings.md：记录研究与发现，在任何发现之后更新。
- progress.md：记录会话日志与测试结果，在整个会话过程中持续更新。
技能目录（${CLAUDE_PLUGIN_ROOT}/）存放模板、脚本与参考文档；规划文件应创建在项目目录中，与代码放在一起，而不是埋在技能安装目录里。
使用方式
在任何复杂任务开始前：
- 在项目中创建 task_plan.md，参考 templates/task_plan.md。
- 在项目中创建 findings.md，参考 templates/findings.md。
- 在项目中创建 progress.md，参考 templates/progress.md。
- 在做出决策前重读计划，让目标重新进入注意力窗口。
- 每个阶段完成后更新：标记完成、记录错误。
三个规划文件都应创建在当前工作目录（项目根目录），而不是技能安装目录。
技能提供模板：templates/task_plan.md（阶段跟踪）、templates/findings.md（研究存储）、templates/progress.md（会话日志）。还提供辅助脚本：scripts/init-session.sh（初始化所有规划文件）、scripts/check-complete.sh（校验所有阶段是否完成）。
关键规则
- 先创建计划：没有 task_plan.md 绝不开始复杂任务。
- 两动作规则：每进行 2 次查看/浏览器/搜索操作后，立即把关键发现保存到文本文件，防止视觉/多模态信息丢失。
- 决策前先阅读：重大决策前阅读计划文件，让目标保持在注意力窗口内。
- 行动后更新：完成任何阶段后，把阶段状态从 in_progress 改为 complete，记录遇到的错误，注明创建/修改的文件。
- 记录所有错误：每个错误都写入计划文件，积累知识、避免重复。
- 不重复失败：如果动作失败，下一个动作不能是同一个动作；跟踪尝试过的内容，改变方法。
三振错误处理协议：
- 第 1 次尝试：诊断并修复——仔细阅读错误、定位根因、应用针对性修复。
- 第 2 次尝试：替代方案——若同样错误，换方法、换工具或换库，绝不重复完全相同的失败动作。
- 第 3 次尝试：更广泛地重新思考——质疑假设、搜索解决方案、考虑更新计划。
- 3 次失败后：升级给用户——说明尝试过什么、分享具体错误、请求指导。
读写决策矩阵：刚写完文件不要读（内容仍在上下文中）；查看图片/PDF 后立即写发现（多模态转文本以防丢失）；浏览器返回数据后写入文件（截图不会持久）；开始新阶段时读计划/发现（上下文陈旧时重新定位）；发生错误时读相关文件（需要当前状态来修复）；中断后恢复时读所有规划文件（恢复状态）。
五问重启测试：能回答“我在哪”（task_plan.md 中的当前阶段）、“我要去哪”（剩余阶段）、“目标是什么”（计划中的目标陈述）、“我学到了什么”（findings.md）、“我做了什么”（progress.md），说明上下文管理是可靠的。
适用场景
适用于：多步骤任务（3 步以上）、研究任务、构建/创建项目、跨越大量工具调用的任务、任何需要组织性的工作。
可跳过：简单问题、单文件编辑、快速查询。
反模式
不要用 TodoWrite 做持久化，而应创建 task_plan.md 文件；不要只陈述一次目标就忘记，而应在决策前重读计划；不要隐藏错误并静默重试，而应把错误记录到计划文件；不要把一切塞进上下文，而应把大内容存入文件；不要立即开始执行，而应先创建计划文件；不要重复失败动作，而应跟踪尝试并改变方法；不要在技能目录中创建文件，而应在项目中创建。
限制
仅当任务明确匹配上述范围时使用本技能。不要将输出视为环境特定验证、测试或专家评审的替代品。如果缺少必要输入、权限、安全边界或成功标准，应停止并请求澄清。
进阶主题
Manus 原则见 reference.md；真实示例见 examples.md。