它是什么
planning-with-files 是一个面向 AI 编码智能体（coding agent）与长周期任务的持久化规划技能包（Skill）。它的核心主张可以概括为一句话：智能体的上下文窗口会死，但写在磁盘上的计划不会。因此它不再依赖"模型记住计划"这种易失机制，而是把规划落到项目目录里的 Markdown 文件上，并借助宿主智能体的生命周期钩子，在每一轮对话中把关键规划片段重新注入上下文。
背景上，主流 AI 编码智能体（Claude Code、Codex CLI 等）都受限于有限的上下文窗口：会话一旦被执行 /clear、被自动压缩（compaction）、或进程崩溃，此前的推理链、已确认的决策与待办事项就会一起蒸发，智能体只能重新摸索。规划类提示词虽然能起到一定作用，但它本质上是"模型可能会遵守的建议"，一旦被挤出上下文就彻底失效。本项目把规划从"提示词"改造成"可执行的基础设施"：文件是事实来源，钩子是强制执行通道。项目以 MIT 协议开源，通过 Agent Skills 标准分发。
核心功能 / 内容清单
- 三份磁盘规划文件：技能在项目中维护
task_plan.md（任务计划与步骤拆解）、findings.md（调研结论与关键事实）、progress.md（进度与已完成/待办状态）。三者分工明确——计划说明"要做什么"，发现记录"知道了什么"，进度记录"做到哪了"，避免不同性质的信息混在一处互相污染。 - 生命周期 Hook 逐轮再注入（per-turn re-injection）：这是它区别于普通提示词的关键。宿主智能体每处理一轮对话，钩子都会把选定的项目规划上下文重新放回当前上下文，用来对抗"上下文腐化"（context rot）——即随着对话变长，早期信息在注意力中被逐渐稀释、在自动摘要中被丢失的现象。
- 崩溃安全与自动恢复：计划存在磁盘上，因此可以跨越
/clear、上下文压缩与进程崩溃存活。新会话启动时，自动恢复机制会重新载入计划，无需人工复述背景。 - 显式 catchup 模式：自动恢复默认只读取项目自身的文件。如果希望读取同一项目下的本地智能体会话记录，用于聚合统计或有界回放（bounded replay），需要显式开启 catchup 模式。这一设计把"跨会话读取"从默认行为变成了需要主动选择的行为。
- 广泛的安装覆盖面：通过 Agent Skills 标准，该技能可安装到 60 余种智能体中；同时对 Claude Code、Codex CLI、Pi 和 Hermes Agent 提供原生插件支持，意味着在这些宿主上能获得最完整的钩子能力。
- 配套评测：README 给出基准结果 96.7% 通过率（29/30），并称在 3 次盲测 A/B 对比中全部胜出。这些数字属于项目自述，可作为参考而非第三方验证结论。
典型使用场景
场景一：跨越多次上下文压缩的大型重构。
当你让智能体重构一个横跨十几个文件的模块时，任务往往远超单次上下文预算，中途必然发生自动压缩。模型很容易"忘记"早先敲定的接口约定、命名规范和已排除的方案，于是开始反复推翻自己。启用本技能后，约定与结论落在 task_plan.md 和 findings.md 中；每轮对话开始时钩子重新注入，智能体始终能看到同一份约定。即使对话历史被压缩掉，"已决定不采用方案 B"这类关键结论依然在场。
场景二：误触 /clear 或进程崩溃后的续接。
会话被清空、终端被关掉、机器重启在工作中都很常见。没有持久化规划时，只能重写一段长长的背景说明，还要承担模型理解偏差的风险。使用本技能后，重新打开该项目并下达"继续"，自动恢复会从磁盘读取计划文件、重建任务状态，然后从 progress.md 记录的断点接着推进。项目明确说明，这一恢复过程只读取项目内的文件。
场景三：多会话或多智能体推进同一项目。
因为事实来源是项目目录中的文件而非某个会话的内存，同一项目的不同会话（例如一个负责实现、一个负责调研）可以围绕同一份规划文件协作，减少各自为政带来的重复劳动与方向偏移。
适合谁用
- 重度使用 AI 编码智能体的开发者：尤其是日常跑 Claude Code、Codex CLI 这类长会话工具、经常遭遇上下文耗尽的人。
- 承担长周期任务的团队：需要任务状态可追溯、可交接，而不只存在于某个人的终端历史里。
- 多智能体编排与 Agent 框架使用者：希望用一个与框架无关的标准（Agent Skills）统一规划层，同时又能利用原生插件的深度集成。
- 需要审计与复盘的项目：Markdown 计划文件天然可读、可 diff、可入库，方便回顾"当时为什么这么决定"。
- 不太适合：一次性小问题、几轮就能结束的问答式使用。这类场景下维护计划文件的成本可能高于收益。
快速上手
安装走 Agent Skills 标准流程，把技能包放入宿主智能体识别的技能目录即可；在 Claude Code、Codex CLI、Pi、Hermes Agent 上还可使用官方提供的原生插件，以获得完整的生命周期钩子支持。使用路径大致为：安装技能 → 在项目中触发规划技能 → 技能生成并维护 task_plan.md、findings.md、progress.md → 按计划逐轮推进 → 会话中断后自动从磁盘恢复。若需读取本地会话记录做统计或回放，需手动开启 catchup 模式。具体命令、目录约定与各宿主的安装差异，以官方 README 为准。
注意事项
- 对宿主能力的依赖：逐轮再注入依赖宿主智能体提供的生命周期钩子。60 余种智能体虽可通过标准安装，但不同宿主暴露的钩子深度不同，实际效果可能存在差异，建议先在目标宿主上小范围验证。
- 上下文成本：每轮注入规划片段会持续占用 token。计划文件写得越长，常驻开销越大，需要权衡详尽程度与预算。
- 敏感信息：计划与发现文件会写入项目目录，可能包含内部设计、接口细节等。若项目会提交到版本库或对外共享，需注意其中的信息边界。
- 恢复范围：自动恢复只读项目文件；跨会话读取本地记录需显式启用 catchup 模式。不要在未确认的情况下假定它能自动重建历史对话。
- 协议：MIT，允许商用、修改与再分发，需保留版权与许可声明。
- 数据说明：README 中的基准通过率与盲测胜负结果均为项目自述，缺少第三方独立复现，应作为参考信息看待。