核心用法
planning-with-files 是一套受 Manus 启发的文件驱动型任务管理系统，核心思想是将"上下文窗口视为易失内存，文件系统视为持久存储"。
启动流程：
1. 创建 task_plan.md —— 定义任务阶段、目标、验收标准
2. 创建 findings.md —— 记录研究过程中的关键发现
3. 创建 progress.md —— 记录会话日志、测试结果、决策变更
Hook 自动化：通过 UserPromptSubmit、PreToolUse、PostToolUse、PreCompact、Stop 五个钩子实现：
- 每次用户输入前自动注入当前计划状态
- 工具调用前校验计划完整性（含 SHA-256 篡改检测 v2.37.0+）
- 文件写入后提醒更新进度
- 上下文压缩前提示刷盘
- 会话结束时检查任务完成度
并行任务：v2.2.0+ 支持 .planning/YYYY-MM-DD-<slug>/ 隔离目录，通过 PLAN_ID 环境变量或 .planning/.active_plan 指针切换上下文。
Claude Code 集成：v2.38.0+ 深度集成 /loop、/goal 原语，提供 /plan-loop 和 /plan-goal 命令实现"监护至完成"的自动化工作流。
显著优点
| 维度 | 优势 |
|------|------|
| **持久化** | `/clear` 或会话中断后可通过 `session-catchup.py` 完整恢复 |
| **可审计** | 三层文件天然形成决策日志，便于复盘 |
| **防篡改** | SHA-256 认证机制确保 `task_plan.md` 内容经用户显式审批后才注入上下文 |
| **并行性** | 多终端可同时处理同一仓库的不同任务，互不干扰 |
| **自动化** | Hook 驱动减少人工记忆负担，"2-Action 规则"防止视觉信息丢失 |
| **生态集成** | 与 Claude Code 2026 年新增的 `/loop`、`/goal`、`PreCompact` 无缝衔接 |
潜在局限
1. 启动成本：简单任务（单文件编辑、快速查询）强制创建三文件反而 overhead 过高
2. 认知负担：需理解 scoped vs root 模式、attestation 机制、hook 注入边界，新手学习曲线陡峭
3. 环境依赖：部分脚本依赖 Python/PowerShell，跨平台兼容性需验证
4. 安全假设：篡改检测依赖用户主动运行 /plan-attest，默认关闭；findings.md 内容无认证，存在提示注入风险
5. 版本锁定：与 Claude Code 特定版本（v2.1.72+ / v2.38.0+）深度绑定，升级可能破坏兼容性
适合人群
- 需要处理 5+ 工具调用 的复杂研发任务
- 研究型工作（需要持续积累 findings）
- 多阶段项目（明确分阶段交付）
- 长会话场景（担心上下文丢失或压缩）
- 团队协作（需要可审计的决策记录）
不适合：一次性问答、单文件修改、无需追踪的临时查询。
常规风险
| 风险类型 | 说明 | 缓解措施 |
|----------|------|----------|
| **提示注入** | `task_plan.md` 自动注入，若含恶意指令可能被误执行 | 运行 `/plan-attest` 锁定计划；将外部内容写入 `findings.md` 而非 `task_plan.md` |
| **状态漂移** | 人工编辑计划文件后未重新认证，导致 hook 拒绝注入 | 编辑后执行 `/plan-attest` 更新哈希 |
| **并行冲突** | 多任务同时修改同一 scoped plan | 使用独立 plan ID 或显式 `set-active-plan` |
| **敏感信息泄露** | `findings.md`、`progress.md` 可能记录 API key、私钥 | 配置 `.gitignore` 排除 planning 目录；定期清理 |
| **过度规划** | 简单任务套用复杂流程，降低效率 | 遵循 "3 步以下跳过" 原则 |