核心用法
planning-with-files 是一套面向 Claude Code 的文件级任务规划框架，灵感源自 Manus AI 的工作记忆机制。其核心设计将「上下文窗口」类比为易失性 RAM，而将「文件系统」作为持久化的磁盘存储，确保复杂任务的关键状态不会因会话中断而丢失。
三大核心文件：
task_plan.md：定义任务阶段、目标、决策点，是规划的中枢findings.md：存储研究过程中的所有发现，替代易失的多模态记忆progress.md：会话日志，记录每一步操作、错误与测试结果
典型工作流：
1. 初始化阶段调用 init-session.sh 创建规划文件（支持并行任务隔离目录）
2. 每完成一个阶段立即更新 task_plan.md 状态（in_progress → complete）
3. 所有研究发现实时写入 findings.md，防止「2 操作后遗忘」
4. 关键决策前重新读取规划文件，保持目标在注意力窗口内
5. 遇到错误时记录至「Errors Encountered」表格，执行「3 次尝试法则」后仍未解决则上报用户
高级特性：
- 会话恢复：
/clear后通过session-catchup.py自动恢复未同步的上下文 - 并行任务：
.planning/YYYY-MM-DD-<slug>/目录隔离多任务，通过PLAN_ID或.active_plan指针切换 - Claude Code 深度集成：支持
/plan-loop（定时轮询）、/plan-goal（目标驱动执行）、PreCompact钩子（上下文压缩前自动刷盘） - 防篡改机制：
/plan-attest生成 SHA-256 校验值，钩子自动检测task_plan.md是否被静默修改，阻断潜在的提示词注入攻击
显著优点
- 状态持久化：彻底解决 LLM 上下文窗口有限、会话易失的问题
- 可审计性：完整的操作日志与错误追踪，便于复盘与知识积累
- 安全设计：双层防御（定界符隔离 + 哈希校验）抵御文件内容投毒
- 工作流标准化：「先规划后执行」「读-决策-写」的强制节奏减少幻觉
- 并行友好：原生支持多终端、多任务同时推进
潜在局限
- 启动成本：简单任务（单文件编辑、快速查询）使用此模式反而累赘
- 文件污染：项目目录下常驻 3+ 个 markdown 文件，需
.gitignore管理 - 认知负荷：用户需理解「数据 vs 指令」的边界规则，误操作可能导致规划失效
- 钩子依赖：部分高级功能（如 PreCompact、防篡改校验）依赖 Claude Code 特定版本支持
适合人群
- 处理 5+ 步骤的复杂研发任务（重构、调研、多模块开发）
- 需要跨会话保持上下文的长期项目
- 多任务并行管理的开发者或团队
- 重视可审计性与安全边界的专业用户
常规风险
- 提示词注入：若将未经验证的网页内容写入
task_plan.md，可能被钩子重复注入。缓解方案：外部内容仅写入findings.md，并启用/plan-attest锁定规划文件 - 哈希校验误报：手动编辑规划文件后未重新执行
/plan-attest，将导致后续钩子注入被阻断 - 目录混淆：初学者可能误在技能安装目录（
$CLAUDE_PLUGIN_ROOT）而非项目目录创建规划文件