Planning with files

核心用法

planning-with-files 是一套受Manus启发的文件驱动型任务规划系统，将AI的上下文窗口（RAM）与文件系统（Disk）分离管理。用户通过创建三个Markdown文件构建"外置工作记忆"：

• task_plan.md：阶段化任务蓝图，含目标、阶段清单、决策记录、错误日志
• findings.md：研究结果的持久化仓库，所有搜索/浏览发现即时归档
• progress.md：会话级执行日志，时间戳标记的操作流水

系统通过Hook机制深度集成Claude Code生命周期：

• UserPromptSubmit：用户提交时自动注入活跃计划上下文
• PreToolUse：工具调用前再次确认计划状态
• PostToolUse：文件写入后提示更新progress.md
• Stop：会话结束时校验阶段完成度
• PreCompact：上下文压缩前自动提醒保存进度

显著优点

| 维度 | 优势 |

|------|------|

| **持久化** | `/clear`后通过`session-catchup.py`秒级恢复上下文 |

| **隔离性** | `.planning/<plan-id>/`支持多任务并行，PLAN_ID环境变量精确路由 |

| **防篡改** | v2.37.0引入SHA-256校验，计划文件被外部修改时自动阻断注入 |

| **自动化** | `/plan-loop`+`/plan-goal`实现"托管式执行"，定时自检直至完成 |

| **安全性** | 明确区分可信计划(task_plan.md)与不可信发现(findings.md)，降低提示注入风险 |

潜在局限

1. 学习曲线陡峭：需理解文件分工、Hook时机、attestation机制等多层概念
2. 维护开销：简单任务（<3步）强制创建三文件反而降低效率
3. 环境依赖：部分脚本依赖PowerShell/macOS stat语法，跨平台兼容性需验证
4. 版本漂移：findings.md长期累积可能导致信息过载，缺乏自动归档机制

适合人群

• 复杂项目开发者：需5+工具调用、跨会话持续工作的研发任务
• 研究团队：多源信息整合、需可追溯决策链条的调研场景
• AI工作流设计师：希望构建可审计、可复现的人机协作流程

常规风险

| 风险 | 缓解措施 |

|------|---------|

| 提示注入攻击 | 强制`findings.md`存储外部内容；`task_plan.md`启用attestation |

| 计划-执行脱节 | 2-Action Rule强制每2次浏览/搜索后立即写入findings |

| 会话状态丢失 | PreCompact Hook+session-catchup双重保障 |

| 并行计划冲突 | PLAN_ID环境变量+`.planning/.active_plan`指针精确隔离 |