planning-with-files 是什麼、怎麼安裝和使用：把計劃寫進文件、/clear 後不丟的規劃 Skill

本文根據 OthmanAdi/planning-with-files 倉庫 README 和 Claude Code 官方文檔整理，資料核對於 2026-10-10。README 裏的效果對比來自項目自己的測量，本文不作為結論引用。

是什麼

編程智能體跑長任務時最常見的事故是「失憶」：上下文窗口被 /clear、自動壓縮或一次崩潰清空，它就忘了做到哪一步，甚至忘了目標是什麼。planning-with-files 的思路很樸素，README 用一句話概括——上下文窗口是內存（易失、有限），文件系統是硬碟（持久、無限），重要的東西都寫到硬碟上。README 說明這個模式參考了 Manus 公開描述過的做法：用 Markdown 文件當作磁盤上的「工作記憶」。

和多數智能體自帶的待辦清單不同（那份清單活在上下文裏），它把計劃放在項目目錄的文件裏，並通過生命週期 Hooks 在每一輪把計劃重新注入，所以它自稱「智能體沒法無視的規劃技能」。

截至 2026-10-10，GitHub 顯示該倉庫約 2.7 萬 Star、2,300 Fork，最近一次推送在 2026-10-06。

包含哪些 Skill

核心是一個技能 planning-with-files，圍繞三個文件工作：

• task_plan.md：階段和勾選框，是 /clear 之後的恢復點；
• findings.md：調研筆記和決策，邊做邊追加；
• progress.md：會話日誌和測試結果。

並行任務會改用獨立目錄 .planning/日期-名稱/，裏面是同樣的三個文件。這些文件是純 Markdown，預設被 gitignore。

技能給智能體定的幾條規矩（README 的 Key Rules）：沒有 task_plan.md 不開工；每做兩次查看或瀏覽操作就儲存一次發現；所有錯誤都記錄；不重複失敗過的做法。

倉庫還提供：

• 本地化版本：planning-with-files-zh（簡體中文）以及阿拉伯語、德語、西班牙語等版本；
• 斜槓命令（Claude Code 插件方式才有）：/plan 或 /pwf 創建三個文件並開始，/status 一眼看當前階段，/plan-doctor 自檢 Hook 是否真的在工作；
• 長任務保護（可選）：門控模式下，還有階段未完成時不讓智能體提前宣佈「做完了」；對計劃內容做 SHA-256 校驗，被意外改寫時拒絕注入並提示。

怎麼安裝

命令均來自 README。

Claude Code 插件方式（技能、Hooks、斜槓命令全都帶上）：

text
/plugin marketplace add OthmanAdi/planning-with-files
/plugin install planning-with-files@planning-with-files

其他智能體，一條命令（通過 Agent Skills 標準裝到 60 多種智能體）：

bash
npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g

想用簡體中文版，把技能名換成 planning-with-files-zh：

bash
npx skills add OthmanAdi/planning-with-files --skill planning-with-files-zh -g

Pi：pi install npm:planning-with-files。Hermes Agent、OpenCode 等有各自的原生插件，命令見 README。README 沒有提供 claude.ai 網頁版的安裝方式。

README 特別提醒兩種方式的差別：npx skills add 只帶技能、腳本和模板，Hooks 依賴技能元數據裏的聲明，可能因為沒接受項目信任等原因悄悄不生效；而 Hooks 正是它區別於普通規劃提示詞的關鍵。在意這一點就用插件方式，並用 /plan-doctor 驗證。

怎麼用

• 開始一個多步驟任務：輸入 /plan（插件方式），或直接說「plan this task」。它會先創建三個文件、寫下階段，再開始幹活；遇到多步驟任務時技能也會自己觸發。
• 中途清空上下文：放心輸入 /clear。下一輪 Hooks 會從項目文件裏讀回當前計劃，智能體從正在進行的階段繼續，而不是從頭摸索。
• 配合 Claude Code 的計劃模式：README 說二者是前後兩個階段——先在計劃模式裏設計並批准方案，然後讓智能體把方案按階段寫進 task_plan.md，再切回正常模式執行。
• 任務結束後：三個文件是「工作記憶」，不會自動歸檔，下個任務會覆蓋。值得保留的結論要自己挪進代碼、提交資訊或文檔。

適合誰 / 不適合誰

適合：

• 讓智能體跑幾十分鐘到幾小時長任務的人（重構、遷移、調研型任務）；
• 經常因為上下文壓縮或 /clear 導致智能體跑偏的開發者；
• 多個智能體或子智能體協作、需要一份共享進度的場景。

不適合：

• 幾分鐘就能完成的小改動——建三個文件純屬負擔；
• 不希望項目目錄裏多出規劃文件的倉庫（雖然預設 gitignore）；
• 想要需求澄清、測試、評審等完整流程的人，它只管「計劃別丟」。

注意事項

• 許可證：MIT。
• 維護狀態：活躍（最近推送 2026-10-06）。
• Hooks 每輪都會執行：插件會註冊多個生命週期 Hook（README 寫 Claude Code 插件是 6 個），每輪對話都會運行腳本、把計劃內容注入上下文，帶來少量延遲和 token 開銷。安裝前在插件詳情裏看清 Hook 列表。
• 讀取本地會話記錄需要顯式開啟：README 說明自動恢復只讀項目裏的規劃文件；讀取同一項目的本地會話記錄是單獨的顯式操作，且不含聯網上載。輸出一旦放進上下文，仍會隨對話發給你配置的模型服務。
• 計劃文件可能含敏感資料：調研發現和錯誤日誌會原樣寫進 Markdown，注意不要把密鑰、內部地址寫進去，也不要誤提交。
• 安全：倉庫含腳本和 Hooks，屬於會執行代碼的技能；從作者倉庫安裝，團隊使用前通讀 SKILL.md 與 scripts 目錄。
• 不同安裝方式功能不同：見上文，技能方式沒有斜槓命令。