核心用法
planning-with-files 是一套受Manus启发的文件驱动型任务规划技能，通过将"工作记忆"外置到持久化Markdown文件来解决大模型上下文窗口的局限性。核心工作流程围绕三个文件展开：
- task_plan.md：定义项目阶段、目标、决策记录和状态追踪
- findings.md：存储研究过程中收集的所有信息、发现和参考资料
- progress.md：会话级日志，记录每次操作、测试结果和错误排查
使用时遵循"先规划后执行"原则：任何需要5次以上工具调用的复杂任务都必须先创建plan文件。系统通过hooks机制在关键节点（UserPromptSubmit、PreToolUse、PostToolUse、Stop、PreCompact）自动注入plan上下文，确保代理始终掌握当前进度。
关键操作模式：
1. 初始化：运行./scripts/init-session.sh [任务名]创建隔离的plan目录（支持并行多任务）
2. 日常执行：每个phase完成后更新task_plan.md状态，同步写入progress.md
3. 防篡改保护：运行/plan-attest对plan文件进行SHA-256签名，后续hooks会自动校验文件完整性
4. 会话恢复：/clear后使用session-catchup.py脚本或依赖hooks自动加载最近活跃plan
显著优点
| 优势 | 说明 |
|------|------|
| **突破上下文限制** | 将项目状态持久化到磁盘，不受模型窗口大小约束 |
| **抗中断恢复** | `/clear`或会话中断后可通过文件系统自动重建上下文 |
| **结构化防注入** | BEGIN/END数据定界符+可选SHA-256校验，抵御plan文件被恶意篡改后的提示注入 |
| **并行任务支持** | `.planning/<timestamp>-<slug>/`隔离目录设计，同一仓库可同时推进多个独立任务 |
| **Claude Code深度集成** | 支持`/plan-goal` `/plan-loop`等扩展命令，与`/compact` `/loop`原生primitive协同 |
| **审计追踪完整** | progress.md形成完整时间线，findings.md集中管理研究产出 |
潜在缺点与局限性
1. 学习曲线陡峭：需要理解三套文件的职责分工、hook触发时机、attestation机制，新手容易混淆文件位置（项目目录vs skill安装目录）
2. 过度工程化风险：简单任务（单次编辑、快速查询）强制使用会产生不必要的开销
3. 文件I/O依赖：hook中的shell命令在Windows/跨平台环境可能存在兼容性问题（依赖stat sha256sum等Unix工具）
4. 安全非绝对：attestation是opt-in机制，用户可能忘记运行；且findings.md不受hash保护，恶意web内容仍可能通过该通道影响执行
5. 维护负担：长期运行的plan需要定期手动归档或清理，否则.planning目录会膨胀
适合人群
- 使用Claude Code处理复杂多步骤项目（代码重构、调研报告、系统架构设计）的开发者
- 需要长时间运行任务且不能丢失上下文的场景（ overnight batch jobs）
- 团队环境中需要可审计、可交接的AI辅助工作流
- 对提示注入安全有顾虑，愿意用操作复杂度换取防护边界的用户
常规风险
| 风险场景 | 等级 | 缓解措施 |
|----------|------|----------|
| Plan文件被恶意修改后注入指令 | 中 | 启用`/plan-attest`，定期核对SHA-256 |
| Web内容污染findings.md后影响决策 | 中 | 始终将外部内容视为data not instructions |
| Hook脚本执行失败导致plan静默丢失 | 低 | 监控`[PLAN TAMPERED]`警告，定期git commit planning文件 |
| 并行任务plan目录混淆 | 低 | 使用`set-active-plan.sh`或`PLAN_ID`环境变量显式指定 |
| 过度规划 paralysis | 中 | 严格遵守"简单任务跳过"原则，避免plan文件本身的仪式化 |
版本演进要点
v2.38.0起深度集成Claude Code的turn-loop系统（/loop /goal /compact），v2.37.0引入SHA-256 attestation作为核心安全机制。建议生产环境始终启用attestation并配合git版本控制使用。