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 官方網站