Planning-with-Files：AI 编码代理的持久性 Markdown 规划技能

Planning-with-Files 是由 OthmanAdi 开发的创新开源项目，为 AI 编码代理实现了一个基于 Markdown 的持久性规划系统。灵感来自 Manus 的规划方法，该项目使用结构化的 3 文件系统，维护一份随着 AI 代理处理任务而不断演进的动态规划文档。它既可作为 Claude Code 技能使用，也可通过 Agents SDK 作为独立集成。

Planning-with-Files 的核心洞见是：AI 编码代理——特别是那些处理复杂多步骤任务的代理——能够从持久性、结构化的规划中获得巨大好处，这种规划能跨越对话轮次与模型上下文窗口限制而持续存在。通过在 Markdown 文件中维护规划，并随着工作进展读取、更新与写回，该系统让 AI 代理即使在上下文窗口耗尽时也能维持连贯的长期策略。

3 文件系统如何运作？

规划系统维护三个不同的 Markdown 文件，协同运作以提供全面的任务管理。计划文件包含高层级策略与任务分解。进度文件跟踪已完成、进行中与剩余的工作。暂存文件为不属于计划本身的中间推理、笔记与发现提供空间。

什么是 Manus 风格的规划？

Manus 是一个 AI 编码助手，以其对复杂任务采取有条理、规划优先的方法而闻名。在开始实现之前，Manus 会创建详细计划、根据需求验证，然后逐步执行，并在新信息出现时更新计划。Planning-with-Files 通过将规划纪律编码为 AI 代理读取与更新的持久性 Markdown 文件，将相同的方法带给任何 AI 编码代理。

flowchart LR
    A[用户请求] --> B[初始化计划]
    B --> C[创建 PLAN.md]
    C --> D[创建 PROGRESS.md]
    D --> E[创建 SCRATCHPAD.md]
    E --> F{执行任务}
    F --> G[更新 PROGRESS.md]
    G --> H[更新 SCRATCHPAD.md]
    H --> I{任务完成？}
    I -->|否| F
    I -->|是| J[最终化 PLAN.md]
    J --> K[提交结果]

安装与设置

Planning-with-Files 解决了哪些问题？

即使拥有大型上下文窗口，AI 编码代理仍面临几个基本挑战。当对话历史超过模型容量时会发生上下文窗口溢出。在长时间会话中，代理可能偏离原始目标，导致任务焦点丢失。跟踪进度的困难意味着代理可能重做已完成的工作或遗漏需求。缺乏持久性表示会话结束时所有规划上下文都会丢失。Planning-with-Files 通过将规划状态外部化为跨会话持续存在且能在上下文窗口重置后存活的文件，解决了所有这些问题。

sequenceDiagram
    participant Agent as AI 代理
    participant Plan as PLAN.md
    participant Progress as PROGRESS.md
    participant Scratch as SCRATCHPAD.md
    participant User as 用户

    User->>Agent: 复杂任务请求
    Agent->>Plan: 创建任务分解
    Agent->>Progress: 初始化跟踪
    loop 每步骤
        Agent->>Plan: 读取当前计划
        Agent->>Progress: 更新状态
        Agent->>Scratch: 记录观察
        Scratch-->>Agent: 回忆上下文
        Agent->>User: 报告进度
        User->>Agent: 反馈/审查
        Agent->>Progress: 调整计划
    end
    Agent->>User: 任务完成，附摘要

哪些 AI 编码工具支持此系统？

该系统主要为 Claude Code 设计，可作为技能使用斜杠命令调用。它也通过 cursorrules 配置支持 Cursor IDE。计划文件格式刻意保持供应商中立——相同的 Markdown 文件可与任何 AI 编码助手搭配使用，并可通过 Agents SDK 集成到自定义代理框架中。文件格式为纯 Markdown，因此人类也可以读取与编辑。

使用文件进行规划的理念是什么？

理念很直接：AI 代理应该以人类可读的格式外部化其规划状态。通过使用 Markdown 文件而非专有数据库格式或工具特定存储，计划变得可检查、可编辑，并且可在人类与 AI 之间共享。这创造了一个透明的协作模型，双方都能看到当前工作状态、了解已完成的事项，并就下一步达成共识。它还支持有趣的工作流，例如在执行开始前审查代理的计划，或让多个代理通过共享计划文件进行协调。

常见问题

什么是 Planning-with-Files？ 它是一个为 AI 编码代理设计的持久性 Markdown 规划系统，使用三个文件（PLAN.md、PROGRESS.md、SCRATCHPAD.md）来管理复杂任务。

3 文件系统如何运作？ PLAN.md 存放任务分解与策略，PROGRESS.md 跟踪每个任务的实时状态，SCRATCHPAD.md 存储工作记忆与中间推理。

如何安装？ 通过 claude add skill othmanadi/planning-with-files 安装为 Claude Code 技能，或手动克隆仓库并为你的 AI 工具配置。

兼容哪些 AI 工具？ 专为 Claude Code 设计，也可通过 cursorrules 与 Cursor IDE 搭配使用，以及通过 Agents SDK 程序化集成。

它解决了哪些问题？ AI 编码代理的上下文窗口溢出、任务焦点丢失、进度跟踪困难，以及跨会话的持久性缺乏。

延伸阅读

• Planning-with-Files GitHub 仓库
• Claude Code 文档
• Manus AI 官方网站
• Agents SDK 文档
• Cursor AI 官方网站