Planning with Files
让 AI 编程 agent 用磁盘上的 task_plan.md / findings.md / progress.md 三个文件作为外置工作记忆，通过 hook 每回合自动注入计划，使任务计划在 /clear、上下文压缩和崩溃后依然存活，支持跨会话自动恢复与多 agent 并行共享状态。
仓库：OthmanAdi/planning-with-files
热度证据：26k star，npm 与插件市场可装；26,139 star,规划类技能热门仓库；字节笔记本'用了3个月近百个Skills'Top11 第05条（11k星）；KB 文章 doc:wechat:53785 'Codex必装的11个Skil
五维评分
热度5/5
质量5/5
创新4/5
易用4/5
文档5/5
优秀点拆解
- 机制化而非靠自觉：把 Manus 上下文工程原则（recitation、KV-cache 稳定、文件即外存）做成 hooks 自动注入引擎（UserPromptSubmit 全量注入 + PreToolUse 短注入 + PreCompact 提醒），进度尾做时间戳归一化保 KV-cache，稳态每轮仅约 330 tokens
- 注入安全设计是一等公民：BEGIN/END 分隔符声明数据非指令、SHA-256 attestation 锁定计划（篡改即阻断并报 [PLAN TAMPERED]）、不可信网页内容只许进 findings.md、v3 模式无 attestation 拒绝注入、SHA 缓存迁移出 /tmp 防投毒，每条规则附安全编号追溯
- 工程级健壮性：400+ 测试、legacy invariant（无 .mode 时输出与 v2.43 字节等价）、单一可测脚本收拢 hook 逻辑、realpath/readlink/python 多级 canonicalizer 降级链、Windows 反斜杠归一化、plan-doctor.sh 自检静默失效机制
- 真实解决多任务并行与多 host 生态：.planning/<日期>-<slug>/ 隔离目录 + .active_plan 指针 + PLAN_ID/PWF_PLAN_ROOT 钉扎 + 嵌套根歧义 fail-closed；60+ agent 适配、SH/PS1 双版本脚本、6 种语言翻译
- 用数据证明价值：skill-creator 官方评估 30 条客观断言 96.7% vs 6.7%、盲测 A/B 3/3 全胜、/clear 后恢复 5.0 轮 vs 13.3 轮，评估方法论文档化
可复用的设计模式
- 文件即状态机：机器可解析的 markdown 结构（**Status:** complete、- [ ]）+ hook 注入循环 + grep/awk 判定，状态文件同时给人看和给机器判
- 数据/指令分离的注入安全边界：分隔符标记、当作数据处理、不可信内容专用文件、可选哈希锁定、失败显式降级
- legacy invariant 兼容契约：新功能全部 opt-in（.mode 标记文件）、默认输出与旧版字节等价、行为矩阵文档化，升级零惊扰
- 确定性终止判定：完成状态由磁盘工件判定而非对话转录，配阻止计数上限、无进展放行、host 能力分档等防失控护栏
适用场景
跨 /clear、autoCompact、崩溃仍要续跑的多步骤/研究型长任务（5+ 工具调用）多 agent 线程共享一个仓库时的并行任务规划（.planning 隔离 + PLAN_ID 钉扎）无人值守循环：gated 模式 + /plan-goal 组合实现 babysit-until-done多模态信息密集任务：2-Action 规则强制把看图/浏览器结果先落盘再继续
边界与注意：少于 5 个工具调用的简单任务不划算（每轮约 330 tokens 注入开销）；全自动注入依赖 host 支持 hooks，且完成门的硬阻断只在 Claude Code/Codex 等 Tier 1 host 生效；计划文件同域可被改写（legacy 模式需手动 /plan-attest 启用哈希锁定）；.planning 默认 gitignore，计划文件需自行决定沉淀
完整拆解分析文档
本页为摘要版，完整精读分析（核心机制、逐条优秀点拆解、写作过程）见本地 Markdown 文档：
analysis/planning-with-files.md