OthmanAdi/planning-with-files

Persistent file-based planning for AI coding agents and long-running tasks. Crash-proof markdown plans, session recovery after /clear and compaction, per-turn re-injection against context rot, deterministic completion gate. Manus-style. Claude Code, Codex, Cursor, Kiro, OpenCode and 60+ agents via the Agent Skills standard.

解決的問題

AI 編程代理經常面臨易失性記憶體的問題，當上下文窗口重置時（例如透過 /clear 命令或當機），關鍵的任務計劃和研究結果會遺失。這會導致目標偏移、重複錯誤，以及使用者在會話重置後需要手動重新說明目標。

工作原理

該專案實現了一種「三文件模式」，將檔案系統視為代理工作記憶體的持久化磁碟。對於每個複雜的任務，代理會建立並維護三個特定的 Markdown 檔案：

  • task_plan.md：追蹤階段與進度核取方塊。
  • findings.md：儲存研究筆記與決策。
  • progress.md：會話日誌與測試結果。

為了確保這些檔案得到使用，該專案為各種 AI 代理（如 Claude Code、Cursor 和 GitHub Copilot）提供了生命週期鉤子，在每一輪開始時將計劃重新注入代理的上下文，提醒代理撰寫更新，並在允許代理停止之前驗證完成情況。

適用對象

使用 AI 編程代理（如 Claude Code、Cursor 或 Pi）的開發者，他們正在處理超出 LLM 上下文窗口限制的長期、多步驟任務。

亮點

  • 持久化記憶體：在上下文清除、當機和會話重置後依然存在。
  • 廣泛的相容性：透過 Agent Skills 標準支援 18 個以上平台上的 60 多個代理。
  • 生命週期自動化：使用鉤子使計劃注入與更新成為機械化的過程，而非選擇性操作。
  • 會話恢復：自動偵測先前的會話數據，幫助代理從當前階段恢復工作。
  • 驗證：包含 SHA-256 鎖定機制，以防止計劃內容被篡改。