Planning with files

核心机制

planning-with-files 借鉴Manus AI的工作模式，建立"上下文窗口=RAM（易失、有限），文件系统=磁盘（持久、无限）"的认知框架。通过强制创建三个Markdown文件解决大模型上下文遗忘与容量限制问题：

• task_plan.md：任务阶段、进度状态、决策记录
• findings.md：研究发现、探索成果、关键信息
• progress.md：会话日志、测试结果、执行轨迹

显著优点

1. 会话恢复能力：通过PreToolUse钩子自动读取plan文件，实现/clear后的状态重建
2. 结构化防遗忘：强制2-Action规则（每2次搜索/浏览后必须写入文件），阻断视觉信息流失
3. 错误追踪机制：3-Strike错误协议+错误表格记录，防止重复踩坑
4. Hook自动化：UserPromptSubmit/PreToolUse/PostToolUse/Stop四阶段钩子实现半自动维护
5. 安全边界设计：区分task_plan.md（可信、自动注入）与findings.md（不可信外部内容），防范间接提示注入

局限与风险

• 启动成本：5步以下简单任务强制创建3个文件反而增加摩擦
• 文件污染风险：Stop钩子执行外部脚本（check-complete.ps1/sh），若脚本被篡改存在代码执行风险
• 钩子的双刃剑：PreToolUse每次读取task_plan.md前30行，若文件被恶意修改会导致持续上下文污染
• 模板依赖：初次使用需手动复制模板，缺乏交互式初始化引导

适用人群

• 需要处理5+工具调用的复杂项目
• 跨会话的长周期研究任务
• 易在上下文中丢失目标的多步骤开发工作
• 团队协作需可追溯决策记录的场景

安全等级

整体S级设计思路，但Stop钩子的外部脚本执行与findings.md的内容隔离依赖用户自律执行，实际安全性介于S-A之间。

核心功能

planning-with-files 是一套受 Manus 启发的文件化规划框架，核心思想是将 上下文窗口视为易失性内存（RAM），将文件系统视为持久化磁盘。通过强制创建三个 Markdown 文件（task_plan.md 阶段规划、findings.md 研究发现、progress.md 进度日志），实现复杂任务的系统化拆解与状态持久化。

显著优点

1. 自动会话恢复：通过 session-catchup.py 脚本在 /clear 后自动恢复上下文，解决大模型对话中断后的状态丢失问题
2. Hook 驱动的智能提醒：注册 4 个生命周期 Hook（UserPromptSubmit/PreToolUse/PostToolUse/Stop），在关键节点自动读取/提醒更新规划文件，降低认知负担
3. 严格的规划纪律：强制"先规划后执行"、2-Action 规则（每 2 次搜索/浏览立即记录）、3-Strike 错误协议，防止盲目试错
4. 清晰的读写决策矩阵：明确区分何时读取计划（决策前）、何时写入发现（浏览后），优化注意力管理
5. 零外部依赖：纯本地文件操作，无网络请求，无第三方依赖包

潜在局限

1. 适用范围受限：明确建议仅用于 5+ 工具调用的复杂任务，简单查询使用反而增加摩擦
2. 文件污染风险：未提供自动清理机制，长期项目可能积累大量规划文件
3. Hook 性能开销：PreToolUse 每次工具调用前读取 task_plan.md，高频调用场景存在 I/O 开销
4. 学习曲线：需要用户理解 Manus 式规划范式，初次使用可能感到约束过多

适合人群

• 需要处理多步骤复杂任务的研究人员、开发者、项目经理
• 经常遭遇上下文中断（如对话达到 token 上限被 /clear）的重度 Claude 用户
• 希望系统化沉淀工作过程（而非仅结果）的知识工作者
• 团队协作场景：规划文件可作为人类-AI 协作的交接文档

安全考量

虽然获得 S 级（85 分）认证，但存在低风险点：Stop Hook 访问 ~/.claude/plugins/cache/ 目录执行检查脚本，属于 Agent 上下文边界跨越。建议用户定期审计该目录内容，或关注后续版本将此功能改为工具调用方式。

使用建议

首次使用时建议完整阅读 SKILL.md 中的"Critical Rules"和"Anti-Patterns"，避免将规划文件创建在 Skill 目录而非项目目录。对于涉及外部网页/搜索的研究任务，务必遵守安全边界：仅将结果写入 findings.md，防止 task_plan.md 被间接注入恶意指令。