/ 目錄 / 演練場 / planning-with-files
● 社群 OthmanAdi ⚡ 即開即用

planning-with-files

作者 OthmanAdi · OthmanAdi/planning-with-files

強制 Claude 使用磁碟上的 Markdown 檔案作為持久記憶體——task_plan.md、findings.md、progress.md——而不是在情境重置時遺失狀態。

一個實作 Manus AI 三檔案規劃模式的 Claude Code 技能。安裝後,Claude 會在開始多步驟工作前自動寫入 task_plan.md,將發現記錄到 findings.md,並在整個工作階段中持續更新 progress.md。基準測試顯示,多步驟任務的通過率從未安裝時的 6.7% 提升至 96.7%。最適合跨越 3 個以上步驟或需要大量工具呼叫的工作。

為什麼要用

核心特性

即時演示

實際使用效果

planning-with-files-skill.replay ▶ 就緒
0/0

安裝

選擇你的客戶端

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "planning-with-files-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/OthmanAdi/planning-with-files",
        "~/.claude/skills/planning-with-files"
      ],
      "_inferred": true
    }
  }
}

開啟 Claude Desktop → Settings → Developer → Edit Config。儲存後重啟應用。

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "planning-with-files-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/OthmanAdi/planning-with-files",
        "~/.claude/skills/planning-with-files"
      ],
      "_inferred": true
    }
  }
}

Cursor 使用與 Claude Desktop 相同的 mcpServers 格式。專案級設定優先於全域。

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "planning-with-files-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/OthmanAdi/planning-with-files",
        "~/.claude/skills/planning-with-files"
      ],
      "_inferred": true
    }
  }
}

點擊 Cline 側欄中的 MCP Servers 圖示,然後選 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "planning-with-files-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/OthmanAdi/planning-with-files",
        "~/.claude/skills/planning-with-files"
      ],
      "_inferred": true
    }
  }
}

格式與 Claude Desktop 相同。重啟 Windsurf 生效。

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "planning-with-files-skill",
      "command": "git",
      "args": [
        "clone",
        "https://github.com/OthmanAdi/planning-with-files",
        "~/.claude/skills/planning-with-files"
      ]
    }
  ]
}

Continue 使用伺服器物件陣列,而非映射。

~/.config/zed/settings.json
{
  "context_servers": {
    "planning-with-files-skill": {
      "command": {
        "path": "git",
        "args": [
          "clone",
          "https://github.com/OthmanAdi/planning-with-files",
          "~/.claude/skills/planning-with-files"
        ]
      }
    }
  }
}

加入 context_servers。Zed 儲存後熱重載。

claude mcp add planning-with-files-skill -- git clone https://github.com/OthmanAdi/planning-with-files ~/.claude/skills/planning-with-files

一行命令搞定。用 claude mcp list 驗證,claude mcp remove 移除。

使用場景

實戰用法: planning-with-files

執行跨多天的重構而不失去進度脈絡

👤 使用 Claude Code 進行遷移或大型重構的工程師 ⏱ ~30 min intermediate

何時使用: 當你正在拆解一個單體架構、遷移框架,或進行任何需要超過一個工作階段才能完成的工作時。

前置條件
  • 將技能複製到 ~/.claude/skills/planning-with-files — git clone https://github.com/OthmanAdi/planning-with-files ~/.claude/skills/planning-with-files
步驟
  1. 明確使用技能來啟動工作
    We're migrating the auth module from JWT to session cookies. Use the planning-with-files skill to map this out before you start.✓ 已複製
    → Claude 在碰觸程式碼前先寫入包含各階段的 task_plan.md
  2. 讓 Claude 執行;可跨天暫停與恢復
    Pick up where we left off — read progress.md and continue.✓ 已複製
    → Claude 重新讀取計畫並確切知道下一個階段為何
  3. 查看 findings.md 中的意外發現
    Summarize findings.md — anything that changed the original plan?✓ 已複製
    → 列出若無記錄將會遺失的各項發現

結果: 一個能在情境重置後存活的重構,並留有可實際審閱的稽核軌跡。

注意事項
  • 技能被用於微不足道的單行修改,徒增額外負擔 — 告訴 Claude「skip planning-with-files, this is a one-shot fix」
搭配使用: filesystem · git

進行研究調查並產生持久性的發現文件

👤 使用 Claude 進行多來源研究的任何人 ⏱ ~45 min beginner

何時使用: 當你需要 Claude 從多個來源蒐集資訊並加以整合時。

步驟
  1. 從一個研究問題開始
    Research how modern rate-limiters handle burst traffic. Use planning-with-files — I want findings.md to build up over the session.✓ 已複製
    → Claude 在搜尋過程中逐步寫入 findings.md
  2. 最後要求進行整合
    Now synthesize findings.md into a 1-page brief.✓ 已複製
    → 簡報以持久記錄的筆記為基礎,而非憑空生成

結果: 一份可重複使用的發現文件,以及以該文件為依據的簡報。

注意事項
  • findings.md 充斥著雜訊而不斷膨脹 — 指示 Claude 在每個階段的邊界處只保留有價值的資訊
搭配使用: firecrawl · fetch

組合

與其他 MCP 搭配,撬動十倍槓桿

planning-with-files-skill + filesystem

技能負責寫入 Markdown 檔案;filesystem MCP 讓 Claude 可以在同一個工作階段中編輯程式碼

Use planning-with-files to plan, then apply the fixes to the repo via filesystem.✓ 已複製
planning-with-files-skill + git

在每個階段的邊界提交 progress.md 和 findings.md,以便在不同機器上都有持久的工作軌跡

End of phase — commit the 3 planning files with a message summarizing what's done.✓ 已複製

工具

此 MCP 暴露的能力

工具輸入參數何時呼叫成本
create_plan task description 任何具有 3 個以上步驟的任務開始時 0 — local file write
log_finding discovery text 每次研究發現值得記錄的內容時 0
update_progress step completed 每次重要的工具呼叫或階段完成後 0
resume_session none 在同一工作目錄中開始任何後續工作階段時 0

成本與限制

運行它的成本

API 配額
None
每次呼叫 Token 數
適中——三個檔案在重新讀取時會消耗 token,通常每個不超過 2k
費用
免費——技能純粹由提示詞和 hook 腳本組成
提示
讓 Claude 定期整理 progress.md,避免在長期專案中無限增長。

安全

權限、密鑰、影響範圍

憑證儲存: 無需憑證——技能純粹由提示詞和本機檔案操作組成
資料出站: 無——所有狀態都保存在工作目錄的磁碟上

故障排查

常見錯誤與修復

Claude ignores the skill and doesn't create task_plan.md

在提示詞中直接指名:「use the planning-with-files skill」。確認複製的檔案已存放於 ~/.claude/skills/planning-with-files。

驗證: ls ~/.claude/skills/planning-with-files/SKILL.md
Hooks not firing between tool calls

檢查 SKILL.md 的 frontmatter 是否完整;若複製不完整請重新安裝。

驗證: head ~/.claude/skills/planning-with-files/SKILL.md
The 3 files get committed to git accidentally

將 task_plan.md、findings.md、progress.md 加入 .gitignore。

驗證: git check-ignore task_plan.md

替代方案

planning-with-files 對比其他方案

替代方案何時用它替代權衡
skillforge你想要一個能建立其他技能的技能,而不僅僅是規劃目標不同——skillforge 用於建立技能;planning-with-files 用於執行任務
Native TodoWrite tool輕量的情境內待辦事項已足夠,且不需要跨工作階段的持久性免費,但在情境重置時會消失

更多

資源

📖 閱讀 GitHub 上的官方 README

🐙 查看未解決的 issue

🔍 瀏覽全部 400+ MCP 伺服器和 Skills