planning-with-files

Planning with Files

像 Manus 一樣工作：使用持久化的 Markdown 檔案作為你在「磁碟上的工作記憶體」。

FIRST: Restore Context (v2.2.0)

在執行任何操作之前，先檢查規劃檔案是否存在並讀取它們：

1. 若 task_plan.md 存在，立即讀取 task_plan.md、progress.md 與 findings.md。
2. 接著檢查是否有來自先前工作階段未同步的上下文：

# Linux/macOS — 自動偵測 Skill 目錄（外掛環境或預設安裝路徑）
SKILL_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/skills/planning-with-files}"
$(command -v python3 || command -v python) "${SKILL_DIR}/scripts/session-catchup.py" "$(pwd)"

# Windows PowerShell
& (Get-Command python -ErrorAction SilentlyContinue).Source "$env:USERPROFILE\.claude\skills\planning-with-files\scripts\session-catchup.py" (Get-Location)

若追趕報告（catchup report）顯示有未同步的上下文：

1. 執行 git diff --stat 查看實際的程式碼變更
2. 讀取目前的規劃檔案
3. 根據追趕報告與 git diff 更新規劃檔案
4. 隨後繼續執行任務

Important: Where Files Go

• 範本 位於 ${CLAUDE_PLUGIN_ROOT}/templates/
• 你的規劃檔案 放置於你的專案目錄中

位置	放置內容
Skill 目錄 (${CLAUDE_PLUGIN_ROOT}/)	範本、腳本、參考文件
你的專案目錄	task_plan.md、findings.md、progress.md

Quick Start

在進行任何複雜任務之前：

1. 建立 task_plan.md — 參考 templates/task_plan.md
2. 建立 findings.md — 參考 templates/findings.md
3. 建立 progress.md — 參考 templates/progress.md
4. 在做決策前重新讀取計畫 — 在注意力視窗中重新聚焦目標
5. 在每個階段後更新 — 標記完成、記錄錯誤

附註： 規劃檔案應放在專案根目錄，而非 Skill 的安裝資料夾。

The Core Pattern

Context Window = RAM (易失、受限)
Filesystem = 磁碟 (持久、無限)

→ 任何重要的內容都必須寫入磁碟。

File Purposes

檔案	用途	何時更新
task_plan.md	階段、進度、決策	每個階段完成後
findings.md	研究、新發現	任何新發現之後
progress.md	工作階段紀錄、測試結果	貫穿整個工作階段

Critical Rules

1. Create Plan First

切勿在沒有 task_plan.md 的情況下啟動複雜任務。此原則不可妥協。

2. The 2-Action Rule

「每執行 2 次檢視/瀏覽/搜尋操作後，立即將關鍵發現儲存至文字檔中。」

這能防止視覺/多模態資訊遺失。

3. Read Before Decide

在做出重大決策之前，請閱讀計畫檔案。這能確保目標始終保持在注意力視窗內。

4. Update After Act

完成任何階段後：

• 標記階段狀態：in_progress → complete
• 記錄遇到的任何錯誤
• 註記新建立/修改的檔案

5. Log ALL Errors

將所有錯誤記錄在計畫檔案中。這有助於累積知識並防止重複犯錯。

## 遇到的錯誤
| 錯誤 | 嘗試次數 | 解決方案 |
|-------|---------|------------|
| FileNotFoundError | 1 | 建立預設設定檔 |
| API timeout | 2 | 新增重試邏輯 |

6. Never Repeat Failures

if action_failed:
    next_action != same_action

追蹤你嘗試過的做法。改變應對策略。

7. Continue After Completion

當所有階段皆已完成，但使用者要求額外的工作時：

• 在 task_plan.md 中新增階段（例如：Phase 6、Phase 7）
• 在 progress.md 中記錄新的工作階段條目
• 照常繼續執行規劃工作流程

The 3-Strike Error Protocol

第 1 次嘗試：診斷與修復
  → 仔細閱讀錯誤訊息
  → 找出根本原因
  → 套用針對性修復

第 2 次嘗試：替代方案
  → 出現相同錯誤？嘗試不同方法
  → 不同的工具？不同的函式庫？
  → 絕不重複完全相同的失敗操作

第 3 次嘗試：全面重新思考
  → 質疑假設
  → 搜尋解決方案
  → 考量是否更新計畫

失敗 3 次後：回報給使用者
  → 解釋你嘗試過的做法
  → 分享具體的錯誤訊息
  → 尋求指引

Read vs Write Decision Matrix

情況	行動	原因
剛寫入檔案	不要讀取	內容仍在上下文記憶中
檢視了圖片/PDF	立即寫入發現	多模態資訊遺失前轉為文字
瀏覽器傳回資料	寫入檔案	螢幕截圖無法持久化
啟動新階段	讀取計畫/發現	若上下文過時則重新定焦
發生錯誤	讀取相關檔案	需要當前狀態以進行修復
間隔後恢復工作	讀取所有規劃檔案	恢復工作狀態

The 5-Question Reboot Test

如果你能回答以下問題，說明你的上下文管理非常穩固：

問題	答案來源
我現在在哪？	task_plan.md 中的當前階段
我要往哪裡去？	剩餘的階段
目標是什麼？	計畫中的目標宣告
我學到了什麼？	findings.md
我做了什麼？	progress.md

When to Use This Pattern

適用於：

• 多步驟任務（3 個步驟以上）
• 研究任務
• 建置/建立專案
• 跨多個工具呼叫的任務
• 任何需要條理組織的工作

略過於：

• 簡單的提問
• 單一檔案的修改
• 快速查詢

Templates

複製這些範本即可開始：

• templates/task_plan.md — 階段追蹤
• templates/findings.md — 研究紀錄
• templates/progress.md — 工作階段日誌

Scripts

用於自動化的輔助腳本：

• scripts/init-session.sh — 初始化規劃檔案。傳入名稱引數時，會在 .planning/YYYY-MM-DD-<slug>/ 下建立獨立計畫以支援平行任務工作流程。不傳引數時，會在專案根目錄寫入 task_plan.md（舊版模式，向下相容）。
• scripts/set-active-plan.sh — 切換當前計畫指標（.planning/.active_plan）。傳入計畫 ID 進行切換；無引數執行則顯示當前計畫。
• scripts/resolve-plan-dir.sh — 解析當前計畫目錄。優先檢查 $PLAN_ID 環境變數，其次檢查 .planning/.active_plan，再者依 mtime 取得最新的計畫目錄，最後退回專案根目錄（舊版）。由 hook 在內部呼叫。
• scripts/check-complete.sh — 驗證當前計畫中的所有階段是否皆已完成。
• scripts/session-catchup.py — 在 /clear 後從先前的工作階段恢復上下文（v2.2.0）。
• scripts/attest-plan.sh（與 .ps1）— 使用 SHA-256 證明鎖定當前的 task_plan.md 內容（v2.37.0）。若檔案內容偏離驗證雜湊值，hook 將拒絕插入計畫內容。使用 --show 印出儲存的雜湊值，--clear 移除證明。請參閱 /plan-attest 命令。

Parallel task workflow

在同一儲存庫中同時處理多個任務時：

# 啟動任務 A
./scripts/init-session.sh "Backend Refactor"
# → .planning/2026-01-10-backend-refactor/task_plan.md

# 在第二個終端機啟動任務 B
./scripts/init-session.sh "Incident Investigation"
# → .planning/2026-01-10-incident-investigation/task_plan.md

# 切換當前計畫
./scripts/set-active-plan.sh 2026-01-10-backend-refactor

# 或將終端機固定至特定計畫
export PLAN_ID=2026-01-10-backend-refactor

每個工作階段皆從其獨立的計畫目錄讀取。Hook 會自動解析正確的計畫。

• scripts/session-catchup.py — 從先前的工作階段恢復上下文（v2.2.0）。針對 OpenCode（v2.38.0+），會讀取位於 ${XDG_DATA_HOME:-~/.local/share}/opencode/opencode.db 的新 SQLite 資料庫，而非舊版的 JSON 樹。

Claude Code Turn-Loop Integration (v2.38.0+)

Claude Code 在 2026 年 5 月推出了三個新的 turn-loop 原語：/loop (v2.1.72)、/goal (v2.1.139) 以及 PreCompact hook 事件。v2.38.0 將規劃工作流程整合至這三者中。

Install scope: plugin vs skill-only (v2.42.0 clarification)

並非所有安裝路徑都會提供本節中的所有功能。存在兩種不同的安裝途徑：

安裝途徑	你會獲得的內容	/plan-goal、/plan-loop 是否可用？
/plugin marketplace add OthmanAdi/planning-with-files 後執行 /plugin install	SKILL.md、腳本、範本，加上 commands/ 資料夾	是，提供 /plan-goal 與 /plan-loop
npx skills add OthmanAdi/planning-with-files（或 ClawHub）	僅包含 SKILL.md、腳本、範本	否，請參考下方的手動備用方案

PreCompact hook 已註冊於 SKILL.md frontmatter 中，兩種途徑皆適用。/plan-goal 與 /plan-loop 斜線命令位於儲存庫根目錄的 commands/ 下，僅有外掛途徑會將其複製至 ~/.claude/plugins/marketplaces/。僅安裝 Skill 的途徑會存放在 ~/.claude/skills/planning-with-files/，不會包含 commands/。

這兩個斜線命令亦帶有 disable-model-invocation: true，這意味著模型不會自動觸發它們，需由你手動輸入。根據已知的 Claude Code 行為（anthropics/claude-code issues #26251, #41417），部分工作階段會解讀 `disable-model-invocat