核心用法
planning-with-files 是一套受 Manus 启发的任务管理系统，通过三个 Markdown 文件 (task_plan.md、findings.md、progress.md) 将易失的上下文窗口转化为持久化的"磁盘工作记忆"。
创建规划文件：复杂任务开始前，使用模板初始化三个核心文件——task_plan.md 定义阶段目标与状态，findings.md 存储研究发现，progress.md 记录会话日志。支持并行工作流，通过 .planning/YYYY-MM-DD-<slug>/ 隔离多个任务。
上下文恢复机制：会话中断后，通过 session-catchup.py 从 SQLite 存储或 Git 差异恢复状态，结合 PreCompact 钩子在上下文压缩前自动刷新进度。
Claude Code 集成：v2.38.0+ 深度整合 /loop、/goal 与 PreCompact，支持 /plan-loop 自动轮询与 /plan-goal 目标驱动执行。
显著优点
1. 状态持久化：突破上下文窗口限制，大型项目信息存储于文件系统
2. 会话连续性：/clear 后通过磁盘文件快速恢复，配合 Git 可追溯变更
3. 防篡改机制：v2.37.0 引入 SHA-256 哈希认证 (/plan-attest)，检测到 task_plan.md 变更时阻断注入，防止提示词注入攻击
4. 并行工作流：支持多任务隔离，通过 PLAN_ID 环境变量或 set-active-plan.sh 切换上下文
5. 自动化钩点：UserPromptSubmit、PreToolUse、PostToolUse、PreCompact、Stop 五处钩点实现零人工干预的状态同步
潜在缺点与局限性
- 文件污染风险：规划文件直接写入用户项目根目录，可能与现有文件冲突
- 学习成本：需理解"2-Action Rule"、"3-Strike Error Protocol"等特定工作模式
- 平台依赖：部分脚本 (
check-complete.ps1) 依赖 PowerShell，跨平台兼容性存疑 - 认证盲区：
findings.md不强制认证，外部爬取内容仍可能携带对抗性指令 - 钩子性能：每次工具调用触发 SHA-256 计算，高频操作下存在 I/O 开销
适合人群
- 处理需 5+ 工具调用的复杂多步骤任务
- 跨会话持续的研究与开发项目
- 需要审计追踪的协作场景（哈希认证提供变更记录）
- 使用 Claude Code 专业版的重度工作流用户
常规风险
- 提示词注入：尽管有哈希认证，若攻击者同时控制
task_plan.md与.attestation文件，仍可绕过防护 - 敏感信息泄露：
progress.md默认明文存储，可能记录 API 密钥等敏感数据 - 过度依赖文件：磁盘 I/O 失败或权限问题时，状态同步机制失效
- 并发写入冲突：多终端同时操作同一规划目录时缺乏文件锁机制
版本演进
v2.38.0 新增 OpenCode SQLite 存储支持、PreCompact 钩点集成及 /plan-loop//plan-goal 命令，标志着从静态文件工具向 Claude Code 原生工作流的深度整合。