Planning with files

核心用法

planning-with-files 是一套受Manus启发的文件化工作流管理系统，核心思想是将"上下文窗口=内存（易失、有限），文件系统=磁盘（持久、无限）"。通过强制创建三类Markdown文件来组织复杂任务：

| 文件 | 用途 | 更新时机 |

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

| `task_plan.md` | 阶段划分、进度状态、决策记录 | 每阶段完成后 |

| `findings.md` | 研究发现、搜索/浏览结果 | 每次发现后 |

| `progress.md` | 会话日志、测试结果、错误记录 | 全程持续更新 |

启动流程：检查现有规划文件→创建三文件（或使用模板）→执行阶段→更新状态→重复。支持通过scripts/init-session.sh快速初始化，并具备/clear后的会话恢复能力。

显著优点

• 跨会话持久化：文件存储打破上下文窗口限制，支持长周期复杂任务
• 自动状态注入：通过UserPromptSubmit/PreToolUse/PostToolUse/PreCompact/Stop五类hooks自动将规划内容注入模型上下文
• 多任务并行：.planning/<timestamp-slug>/隔离目录+PLAN_ID环境变量支持同时推进多个任务
• v3增强模式：
• Autonomous模式：降低token消耗（移除PreToolUse注入）、结构化ledger摘要替代原始progress.md
• Gated模式：增加完成门禁机制，防止未完成任务提前终止，支持20次阻断上限+停滞检测
• 安全加固：SHA-256哈希认证（attestation）防止计划文件被篡改，nonce动态分隔符防御分隔符混淆注入

潜在缺点与局限性

• 学习成本：必须理解"先写计划再执行"的非协商规则，新手易跳过
• hook依赖：完整功能需Claude Code等支持hooks的平台，部分环境降级为通知模式
• token权衡：v2模式每工具调用注入计划头带来+68%token开销（v3 autonomous模式已优化）
• 门禁限制：Gated模式仅在Tier 1主机（Claude Code、Codex CLI等）支持硬阻断，其他环境仅为通知
• 文件污染：频繁更新markdown文件可能产生git噪音，需配合.gitignore管理

适合人群

• 需要处理5+工具调用的多步骤复杂任务的开发者
• 进行长期研究、需要跨会话保持上下场的知识工作者
• 追求可审计、可复现工作流程的团队
• 使用Claude Code并愿意采用结构化代理模式的Opus/Fable/GPT-5.5级模型用户

常规风险

• 提示注入：若未启用attestation，task_plan.md中的恶意指令可能通过hook注入上下文（v3默认开启认证缓解）
• 进度幻觉：模型可能错误标记阶段完成，需配合check-complete.sh验证
• 无限循环风险：Gated模式虽有20次上限+停滞检测，但复杂任务仍可能触发多次阻断
• 并行冲突：多终端同时写入同一ledger文件需依赖文件系统原子性，极端并发场景可能损坏
• 外部内容污染：findings.md收集的网页/API内容需按"数据非指令"处理，避免自动执行其中指令

版本亮点

• v3.0.0：新增自主/门禁双模式，SHA认证默认开启，ledger结构化摘要，nonce动态分隔符
• v2.38.0+：深度集成Claude Code /loop /goal 原语，支持PreCompact hook自动 flush 进度
• v2.2.0：session-catchup.py实现/clear后上下文恢复

核心用法

planning-with-files 是一种受 Manus AI 启发的上下文工程方法，将易失的 LLM 上下文窗口（RAM）转化为持久的文件系统状态（Disk）。它通过三种 Markdown 文件实现工作记忆外化：

• `task_plan.md`：定义任务阶段、目标、决策点和当前状态
• `findings.md`：存储研究、发现、外部信息（如网页搜索结果）
• `progress.md`：记录会话日志、测试输出、错误追踪

典型工作流程

1. 启动阶段：运行 init-session.sh ["任务名"] 创建规划文件（可选 --autonomous 或 --gated 进入 v3 模式）
2. 执行阶段：每完成一个阶段，更新 task_plan.md 中的状态标记；发现重要信息立即写入 findings.md
3. 检查点：关键决策前重新阅读 task_plan.md 确保目标对齐
4. 恢复阶段：/clear 后运行 session-catchup.py 自动检测未同步的代码变更并恢复上下文

v3 高级模式（v3.0.0 新增）

| 模式 | 特性 | 适用场景 |

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

| **Legacy（默认）** | 完整计划注入、高 token 消耗、无强制门禁 | 常规交互式任务 |

| **Autonomous** | 降低重复注入（-68% token）、结构化 ledger 摘要、默认启用 SHA-256 认证 | 长时运行的自主任务 |

| **Gated** | Autonomous 特性 + 完成门禁（阻止提前终止）| 关键管道、生产部署 |

门禁机制通过评估磁盘上的 plan 文件而非对话记录来判断完成状态，有效防止模型幻觉导致的提前终止。

显著优点

1. 上下文持久化：解决 LLM 上下文窗口截断和 /clear 后状态丢失问题
2. 注意力管理：通过"2-Action 规则"强制将视觉/多模态信息转为文本保存
3. 抗幻觉设计：v3 的门禁和认证机制将 ground truth 锚定在文件系统而非对话历史
4. 并行任务支持：.planning/<slug>/ 目录结构允许同一仓库并发处理多个独立任务
5. 零外部依赖：纯标准库实现，无供应链攻击面
6. 安全边界清晰：通过 BEGIN/END 定界符、SHA-256 认证、nonce 注入等分层防御提示词投毒

潜在局限性与风险

| 局限 | 说明 |

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

| 启动摩擦 | 简单任务（<5 步工具调用）强制创建 3 个文件显得冗余 |

| 学习曲线 | 需要理解 Manus 风格的"文件即状态"心智模型 |

| Token 成本 | Legacy 模式下每工具调用注入计划内容，可能增加 68% token 消耗（v3 已优化）|

| 文件污染 | 规划文件可能被意外提交到版本控制（建议添加 `.gitignore`）|

| 门禁限制 | Gated 模式仅在 Claude Code 等 Tier 1 宿主上能真正硬阻塞；其他宿主降级为通知 |

| 认证管理 | 编辑计划后需重新运行 `/plan-attest`，增加交互步骤 |

适合人群

• 复杂项目开发者：需要 10+ 步、跨会话的软件构建任务
• 研究员：需要跟踪多源信息、避免"搜索-遗忘"循环
• 运维工程师：长时运行的部署、迁移、故障排查任务
• 团队协作者：通过 plan 文件实现人机、人人之间的状态同步

常规风险

1. 提示词注入：task_plan.md 内容通过 hooks 注入 Agent 上下文。若攻击者能写入该文件，可能注入指令。缓解：启用 SHA-256 认证（/plan-attest）后，未认证修改会触发 [PLAN TAMPERED] 警告。
2. 外部内容污染：findings.md 旨在容纳网页抓取等不可信内容，但传统上也被注入。v3 模式改用结构化 ledger 摘要替代原始 progress.md 尾部注入，减少攻击面。
3. 过度依赖文件：模型可能机械地读写文件而忽视上下文中的实时信息，导致决策延迟。
4. 路径遍历：虽已实现 is_within_root 检查和 slug 验证，但在不可信环境中仍需确保 ${CLAUDE_PLUGIN_ROOT} 等环境变量未被篡改。