OthmanAdi/planning-with-files

解决的问题

本项目解决了 AI 编程代理中“上下文腐烂”和记忆丢失的问题。当代理的上下文窗口填满，或者用户触发 /clear 命令或代理崩溃时，代理通常会丢失其当前任务、进度和发现。此工具确保代理的规划状态持久化在本地磁盘上，而不是仅仅依赖易失性 RAM。

工作原理

该项目实现了“3 文件模式” (task_plan.md, findings.md, 和 progress.md)，作为代理的持久化外部存储。它使用生命周期钩子在每一轮开始时自动将这些文件注入到代理的上下文窗口中。由于状态以标准 Markdown 文件形式存储在文件系统中，即使代理重置了会话，它仍然可用，从而允许代理从中断的地方准确恢复。

适用人群

它专为使用 AI 编程代理（如 Claude Code, Cursor, GitHub Copilot 或各种基于 CLI 的代理）进行长时间运行或复杂编码任务的开发者设计，这些任务超出了单个上下文窗口的容量或需要抵御会话中断。

亮点

• 持久化状态： 将任务计划、研究发现和进度日志保存在磁盘上，在 /clear 命令和崩溃后依然存在。
• 广泛兼容性： 通过 Agent Skills 标准支持 60 多种代理和 IDE，并为 Claude Code, Qoder 和 Hermes 等工具提供原生插件。
• 性能优化： 钩子经过速度优化（低于 300ms），并在模型的注意力窗口中保持稳定性。
• 效果验证： 经基准测试断言通过率为 96.7%，并在盲测 A/B 测试中证明了其成功性。