Superpowers + PlanningWithFiles：4 個衝突點拆解，別讓兩個好工具互相打架
整理版優先睇
Superpowers 同 PlanningWithFiles 點樣分工先唔會打架：4 個衝突拆解 + 協作方案
呢篇文章係由術哥（ShugeX）寫嘅，佢係一個專注 AI 編程嘅技術實踐者。佢發現好多朋友同時用 Superpowers 同 PlanningWithFiles 兩個 Claude Code 插件嘅時候，成日撞到 agent 精神分裂嘅問題——一個 hook 叫佢先讀 plan，另一個叫佢先調 skill。佢翻曬兩個項目嘅源碼，結論係呢個唔係 bug，而係結構性衝突，因為兩個工具嘅設計哲學根本唔同。
PlanningWithFiles 嘅核心係用文件系統嚟做持久化記憶，透過 task_plan.md、findings.md、progress.md 三個檔案追蹤進度，每次工具調用前都會注入 task_plan 嘅內容。Superpowers 就係一套完整嘅開發流程框架，將寫 code 拆成 7 步標準流程，每個步驟都要先檢查對應嘅 skill 先可以行動。兩者都用 hook 高頻注入指令，結果就造成 agent 行為混亂。
最後術哥提出嘅解決方案係唔強行合併兩個系統，而係分工協作：PlanningWithFiles 管全局進度同跨 session 記憶，Superpowers 管實現細節同 code 質量。透過喺 PwF 嘅 task_plan.md 入面引用 Superpowers plan 嘅路徑嚟做橋接，令到兩個系統各司其職，互補唔打架。佢強調呢個方法唔係銀彈，但係成本低過收益嘅務實做法。
- 兩個工具衝突嘅根源係設計哲學唔同：PwF 管進度記憶，Superpowers 管開發流程，硬砌會令 agent 行為不可預測。
- 核心衝突點有四個：雙 Hook 系統 Context 競爭、雙任務追蹤唔同步、Plan 文件角色衝突、writing-plans 唔兼容 PwF task_plan 格式。
- 解決方法係分工協作：PwF 做項目經理（管全局進度），Superpowers 做技術負責人（管實現細節），唔好強行整合。
- 橋接方式係喺 PwF 嘅 task_plan.md 每個 Phase 入面加一條 🔗 Superpowers Plan 路徑引用，等 agent 知道嗰個 Phase 嘅實現細節喺邊。
- 實行上要注意同步要靠自律、Context 仍然會膨脹、Stop hook 可能誤判，建議喺 task_plan 加備註標記跨 session 嘅 Phase。
PlanningWithFiles GitHub 倉庫
PlanningWithFiles 嘅官方源碼同文件，用嚟管理 AI 嘅持久化記憶同任務追蹤。
Superpowers GitHub 倉庫
Superpowers 嘅官方源碼同文件，提供子代理驅動開發流程框架。
橋接版 task_plan.md 模板
示範點樣喺 PwF 嘅 task_plan.md 引用 Superpowers plan 路徑，實現雙系統協作。具體內容可參考文中示例。
點解兩個好工具會互相打架？
羣裡面有朋友問：有冇 Superpowers + PlanningWithFiles 配合使用嘅文章？呢個問題幾好。兩個工具單獨用都唔錯——PlanningWithFiles 俾 AI 加咗持久化記憶，Superpowers 俾 AI 套咗一套嚴格嘅開發流程。但係一齊裝嘅時候，你會發現 agent 成日精神分裂：一個 hook 叫佢先讀 plan，另一個 hook 叫佢先調 skill。
術哥翻曬兩個項目嘅源碼之後，得出一個結論：呢個唔係 bug，係結構性衝突。兩個工具嘅設計哲學唔同，硬湊埋一齊用，註定互相干擾。但係都唔係冇得解。先講清楚問題喺邊，再講點樣分工。
拆解 PlanningWithFiles：文件式工作記憶
PlanningWithFiles 嘅核心思路可以用一句話概括：把文件系統當磁盤，把上下文窗口當 RAM。AI 嘅上下文窗口有容量限制，傾偈記錄一長就唔記得嘢。PwF 嘅解法係將任務計劃、研究發現、操作進度全部寫成 Markdown 文件存落嚟。新 session 開始時，自動讀取呢啲文件，瞬間恢復記憶。
佢用嘅係三文件模式：task_plan.md 追蹤階段同進度（核心文件）、findings.md 儲存研究同發現（知識庫）、progress.md 記錄會話日誌同測試結果（操作日記）。其中 task_plan.md 係靈魂，將任務拆成 3-7 個 Phase，每個 Phase 有狀態標記（pending / in_progress / complete），仲有 checklist 同決策記錄。
Hook 注入機制方面，PwF 配咗 4 個生命週期鈎子：UserPromptSubmit 時注入 task_plan.md 內容；PreToolUse 每次調用工具前重讀 task_plan.md；PostToolUse 提醒更新進度；Stop 時驗證所有階段係咪完成。關鍵係PreToolUse，每次 agent 調用工具之前，呢個 hook 都會將 task_plan.md 嘅頭 30-50 行塞入上下文，等於每次動手之前貼一張便籤提醒你大目標。
拆解 Superpowers：子代理驅動開發框架
Superpowers 嘅定位同 PwF 完全唔同。佢係一個完整嘅軟件開發方法論框架，將 AI 寫 code 呢件事拆成 7 步標準流程：brainstorming → using-git-worktrees → writing-plans → subagent-driven-development → test-driven-development → requesting-code-review → finishing-a-development-branch。
核心隱喻好有意思：佢將 AI agent 當成一個熱情但缺乏判斷力嘅初級工程師。所以每一步都需要明確嘅指令同嚴格嘅審查。佢嘅 plan 文件喺 docs/superpowers/plans/ 目錄，同 PwF 嘅 task_plan 完全唔同——Superpowers plan 係實現藍圖，裏面係精確嘅文件路徑、完整 code、測試用例、提交命令，每個任務粒度係 bite-sized（2-5 分鐘），唔準有 placeholder（TBD、TODO）。
觸發機制方面，Superpowers 有個using-superpowers skill，要求 agent 喺任何行動前先檢查並調用對應嘅 skill，呢個唔係建議，係強制工作流。審查機制係雙階段嘅：先係 spec compliance（規格合規），再係 code quality（代碼質量）。寫完 code 唔係終點，仲要過兩道審查關。
四個衝突點逐個拆解
- 1 雙 Hook 系統嘅 Context 競爭：兩個工具都用 hook 注入指令，Superpowers 要求「follow skill exactly」，PwF 要求「read plan before decisions」。agent 每次操作前同時收到兩套指令，結果 Context 膨脹、指令衝突、優先級混亂。尤其係 PreToolUse 每次工具調用都觸發，令 agent 行為不可預測。
- 2 雙任務追蹤系統唔同步：兩套獨立追蹤系統——Superpowers plan 喺 docs/superpowers/plans/*.md，PwF task_plan 喺項目根目錄。任務粒度（極細 vs 粗）、狀態機制（TodoWrite 易失 vs Phase status 持久化）完全唔同，同一個任務喺兩個文件各有一份，狀態永遠對唔上。Stop hook 仲會因為睇唔到 Superpowers 嘅進度而誤判。
- 3 Plan 文件角色衝突：Superpowers plan 面向初級工程師，教佢每一步點樣寫 code；PwF task_plan 面向注意力管理，記錄你喺邊、該做乜。兩者同時存在時，agent 需要喺兩個源文件之間來回切換，注意力分散。
- 4 writing-plans 唔會以 PwF task_plan 為骨架：呢個係最根本嘅衝突。Superpowers writing-plans 有嚴格格式要求（精確路徑、完整 code、驗證步驟、bite-sized、TDD 循環），而 PwF task_plan 組織邏輯寬鬆好多（Phase 級 checklist、唔要求精確 code、關注位置唔係做法）。writing-plans 唔會用 PwF 嘅 task_plan 做骨架，結果兩套 plan 永遠平行，唔會交叉。
落地方案：分工協同，唔做強行整合
術哥提出嘅解決方案思路好簡單：唔嘗試合併兩個系統，而係讓各自做擅長嘅事。PwF 管全局進度，Superpowers 管實現細節。具體做法係：PwF 嘅 task_plan.md 只記錄 Phase 級進度、關鍵決策、錯誤日誌，唔寫具體 code；Superpowers 嘅 plan 記錄精確實現步驟、完整 code、測試用例，唔管進度追蹤。
橋接嘅關鍵係喺 task_plan.md 每個 Phase 引用 Superpowers plan 文件路徑。文中俾咗一個示例：每個 Phase 下面加一行 `🔗 Superpowers Plan: ...`，等 agent 知道呢個 Phase 嘅實現細節喺邊。狀態同步方面，Superpowers 每完成一個 task，手動（或透過自訂 hook）更新 task_plan.md 對應 Phase 嘅 checklist。
# Task Plan: 用戶認證模塊
## Phase 1: 數據庫模型設計 [in_progress]
> 🔗 Superpowers Plan: docs/superpowers/plans/2026-05-07-user-auth.md#task-1-3
- [x] 設計 User 表結構
- [x] 設計 Session 表結構
- [ ] 編寫遷移腳本
**決策記錄**: 使用 UUID 作為主鍵，避免 ID 枚舉攻擊
## Phase 2: 認證 API 實現 [pending]
> 🔗 Superpowers Plan: docs/superpowers/plans/2026-05-07-user-auth.md#task-4-8
- [ ] POST /auth/register
- [ ] POST /auth/login
- [ ] POST /auth/logout
- [ ] JWT Token 簽發與驗證
## Phase 3: 前端集成 [pending]
> 🔗 Superpowers Plan: docs/superpowers/plans/2026-05-07-user-auth.md#task-9-12
- [ ] 登錄頁面
- [ ] 註冊頁面
- [ ] Token 存儲（localStorage）
## Errors Encountered
| Error | Context | Resolution |
|-------|---------|------------|
| - | - | - |- 1 brainstorming 階段 → 正常用 Superpowers 嘅蘇格拉底式提問
- 2 brainstorming 完成 → 手動創建 PwF 嘅 task_plan.md（Phase 級別）
- 3 writing-plans 階段 → 正常用 Superpowers 生成精確 plan
- 4 writing-plans 完成 → 喺 task_plan.md 每個 Phase 寫入 plan 路徑引用
- 5 執行階段 → Superpowers 嘅 skill 驅動實現，PwF 嘅 hook 驅動進度提醒
- 6 每完成一個 Superpowers task → 更新 task_plan.md 對應 Phase 嘅 checklist
- 7 session 結束 → PwF 嘅 Stop hook 驗證整體完成度
- 8 session 恢復 → PwF 嘅 hook 自動注入進度，Superpowers 讀取 plan 繼續
注意事項：呢個方案唔係銀彈。同步要靠自律——Superpowers 完成一個 task 後，agent 未必記得更新 task_plan.md，要喺 hook 或 skill 加提醒；Context 仍然會膨脹，但至少指令唔衝突；PwF 嘅 Stop hook 可能誤判，建議喺 task_plan.md 加備註標記跨 session 嘅 Phase。
🚩 2026 年「術哥無界」系列實戰文檔 X 篇原創計劃 第 105 篇，AI 編程最佳實戰「2026」系列第 30
大家好，歡迎嚟到 術哥無界 | ShugeX ｜ 運維有術。
我是術哥，一個專注 AI 編程、AI 智能體、Agent Skills、MCP、雲原生、AIOps、Milvus 向量數據庫嘅技術實踐者同開源佈道者！
Talk is cheap, let's explore。無界探索，有術而行。
圖 1：Superpowers + PlanningWithFiles 衝突全景
說明：本文內容係根據 Superpowers（obra/superpowers）同 PlanningWithFiles（OthmanAdi/planning-with-files）嘅源碼分析整理出嚟，包括 README、SKILL.md、hooks 配置等第一手官方材料。文入面嘅配置模板同參數建議只係參考，實際效果請以你嘅業務數據同環境測試結果為準。如果有實際使用經驗，歡迎喺評論區分享交流。
羣入面有朋友問：有冇 Superpowers + PlanningWithFiles 配合使用嘅文章？
呢個問題幾好。兩個工具單獨用都唔錯——PlanningWithFiles 俾 AI 加咗持久化記憶，Superpowers 俾 AI 套咗套嚴格嘅開發流程。但係一齊裝嘅時候，你會發現 agent 成日精神分裂：一個 hook 叫佢先讀 plan，另一個 hook 叫佢先調 skill。
翻曬兩個項目嘅源碼之後，我得咗一個結論：呢個唔係 bug，係結構性衝突。兩個工具嘅設計哲學唔同，硬係夾埋一齊用，註定互相干擾。
但係都唔係冇辦法解。先講清楚問題喺邊，再講點樣分工。
1. 拆解 PlanningWithFiles - 文件式工作記憶
PlanningWithFiles 嘅核心思路可以用一句話概括：將文件系統當做磁碟，將上下文視窗當做 RAM。
AI 嘅上下文視窗有容量限制，傾偈記錄一長就會忘事。PlanningWithFiles 嘅解法係將任務計劃、研究發現、操作進度全部寫成 Markdown 文件儲低。新對話開始時，自動讀取呢啲文件，瞬間恢復記憶。
三文件模式
task_plan.md → 追蹤階段和進度（核心文件）
findings.md → 存儲研究和發現（知識庫）
progress.md → 會話日誌和測試結果（操作日記）
task_plan.md 係靈魂。佢將任務拆成 3-7 個 Phase，每個 Phase 有狀態標記（pending / in_progress / complete），仲有 checklist 同決策記錄。呢個文件解決嘅核心問題係：agent 喺任何時候都知道自己喺邊、要搞乜。
Hook 注入機制
PlanningWithFiles 配咗 4 個生命週期鈎：
關鍵在 PreToolUse。每次 agent 調用工具之前，呢個 hook 都會將 task_plan.md 嘅頭 30-50 行塞入上下文。相當於喺你每次動手之前，先貼張 memo 提醒你唔好唔記得大目標。
幾個值得留意嘅特性
Session Recovery（v2.2.0+）：新對話自動還原之前嘅進度，唔使重複解釋 Hash Attestation（v2.37.0）：SHA-256 哈希鎖定 task_plan.md，防止內容被篡改或者注入 並行計劃（v2.36.0）： .planning/YYYY-MM-DD-<slug>/目錄隔離，支援多個計劃並行推進
圖 2：PlanningWithFiles 三文件透過 4 個 Hook 同 Agent 上下文互動
2. 拆解 Superpowers - 子代理驅動開發
Superpowers 嘅定位唔同。佢係一個完整嘅軟件開發方法論框架，將 AI 寫程式呢件事拆成 7 步標準流程：
1. brainstorming → 蘇格拉底式提問，從粗糙想法提煉設計方案
2. using-git-worktrees → 創建隔離工作空間
3. writing-plans → 將設計拆解為 bite-sized 任務（每步 2-5 分鐘）
4. subagent-driven-development → 子代理執行計劃
5. test-driven-development → RED-GREEN-REFACTOR 循環
6. requesting-code-review → 代碼審查
7. finishing-a-development-branch → 分支收尾
核心隱喻好有趣：佢將 AI agent 當做一個好熱心但缺乏判斷力嘅初級工程師。所以每一步都需要明確嘅指令同嚴格嘅審查。
Plan 檔案嘅角色
Superpowers 嘅 plan 檔案路徑係 docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md。
同 PlanningWithFiles 嘅 task_plan 完全唔同。Superpowers 嘅 plan 係實現藍圖 —裏面係精確嘅檔案路徑、完整程式碼、測試用例、提交命令。每個任務粒度係 bite-sized（2-5 分鐘），唔準有 placeholder（TBD、TODO），每個任務自帶 TDD 循環。
一句話區分：
Superpowers plan = 點樣將磚砌成牆 PwF task_plan = 牆砌到邊度，出咗咩問題
Skill 觸發機制
Superpowers 有個 using-superpowers skill，要求 agent 喺任何行動之前先檢查並調用對應嘅 skill。呢個唔係建議，係強制工作流程。
佢嘅審查機制係雙階段：先係 spec compliance（規格合規），再係 code quality（程式碼質素）。寫完程式碼唔係終點，仲要過兩關審查。
圖 3：Superpowers 7 步工作流程——由 brainstorming 到 branch 收尾
3. 協同攻堅 - 點解配合唔好
呢個係文章嘅核心部分。我逐個拆解兩個工具嘅衝突點。
衝突 1：雙 Hook 系統嘅 Context 競爭
兩個工具都用 hook 向 agent 上下文塞指令。
Superpowers 嘅 using-superpowers 要求 agent 喺任何行動之前先檢查 skill，然後按 skill 嘅指令行動。原文係：follow skill exactly。
PlanningWithFiles 嘅 PreToolUse 喺每次工具調用之前注入 task_plan.md 嘅內容。原文係：read plan before decisions。
問題嚟喇。agent 每次操作之前會同時收到兩套指令注入。後果：
Context 膨脹：兩個系統嘅指令疊加，食咗上下文視窗 指令衝突：一個話先調 skill，一個話先讀 plan 優先次序混亂：agent 唔知應該聽邊個先
呢個唔係偶爾出現嘅問題。PreToolUse 係每次工具調用都會觸發。Superpowers 嘅 skill 檢查都係每次行動之前都要做。兩套指令以極高頻率疊加，agent 嘅行為就變得好難預測。
衝突 2：雙任務追蹤系統唔同步
兩套獨立嘅追蹤系統，互相唔溝通。
| 檔案位置 | docs/superpowers/plans/*.md | task_plan.md |
| 任務粒度 | ||
| 狀態機制 |
同一個任務喺兩個檔案各有一份，狀態永遠對唔上。
更麻煩嘅係 Stop hook。PlanningWithFiles 嘅 Stop hook 會喺 agent 嘗試停止嗰陣驗證 task_plan.md 嘅完成度。但任務嘅實際執行進度喺 Superpowers 嘅 plan 檔案度。PwF 檢查自己嘅 task_plan 話 Phase 2 仲未完成，但 Superpowers 已經將 Phase 2 拆成 15 個 bite-sized task 而且全部做曬。
衝突 3：Plan 檔案角色衝突
前面講咗，兩個 plan 檔案解決嘅問題唔一樣：
Superpowers plan 面向初級工程師，話畀佢知每一步點樣寫程式碼 PwF task_plan 面向注意力管理，記錄你喺邊、要做乜
當兩者同時存在嘅時候，agent 需要喺兩個來源檔案之間來回切換。Superpowers 話按 plan 寫程式碼，PwF 話先睇 task_plan 確認你喺邊。兩套系統爭奪 agent 嘅注意力。
衝突 4：writing-plans 唔會以 PwF task_plan 做骨架
呢個衝突係最根本嘅。
Superpowers 嘅 writing-plans skill 有嚴格嘅格式要求：
每個任務必須包含精確嘅檔案路徑、完整程式碼、驗證步驟 任務粒度係 bite-sized（2-5 分鐘） 唔準有 placeholder（TBD、TODO 等） 每個任務有完整嘅 TDD 循環
PwF 嘅 task_plan 組織邏輯鬆好多：
Phase 級別嘅 checklist 唔要求精確程式碼 更關注你喺邊而唔係你點樣做
writing-plans 唔會以 PwF 嘅 task_plan 做骨架 —佢自己有結構化標準。PwF 嘅 Phase checklist 太粗，唔符合 writing-plans 嘅輸入要求。
結果就係：兩套 plan 檔案平行存在，永遠唔會交匯。你寫你嘅藍圖，我記我嘅進度，各自為政。
衝突全景圖
圖 4：4 個衝突點嚴重程度同影響範圍
4. 落地方案 - 分工協同，唔好強行整合
講咗咁多問題，解決方案嘅思路其實好簡單：唔好嘗試合併兩個系統，等各自做擅長嘅嘢。
核心思路：PwF 管全局進度，Superpowers 管實現細節。
具體做法
1. PwF 管全局
task_plan.md 淨係記錄 Phase 級進度、關鍵決策、錯誤日誌。唔好寫具體程式碼，唔好寫實現細節。
2. Superpowers 管實現
plan 檔案記錄精確嘅實現步驟、完整程式碼、測試用例。唔理進度追蹤，淨係管點樣做。
3. 橋接規則
在 task_plan.md 嘅每個 Phase 入面引用 Superpowers plan 檔案路徑。agent 透過呢個路徑知道呢個 Phase 對應嘅實現細節喺邊。
4. 狀態同步
Superpowers 每完成一個 task，手動（或者透過自訂 hook）更新 task_plan.md 對應 Phase 嘅狀態。
task_plan.md 示例
下面係一個橋接版嘅 task_plan.md 結構：
# Task Plan: 用戶認證模塊
## Phase 1: 數據庫模型設計 [in_progress]
> 🔗 Superpowers Plan: docs/superpowers/plans/2026-05-07-user-auth.md#task-1-3
- [x] 設計 User 表結構
- [x] 設計 Session 表結構
- [ ] 編寫遷移腳本
**決策記錄**: 使用 UUID 作為主鍵，避免 ID 枚舉攻擊
## Phase 2: 認證 API 實現 [pending]
> 🔗 Superpowers Plan: docs/superpowers/plans/2026-05-07-user-auth.md#task-4-8
- [ ] POST /auth/register
- [ ] POST /auth/login
- [ ] POST /auth/logout
- [ ] JWT Token 簽發與驗證
## Phase 3: 前端集成 [pending]
> 🔗 Superpowers Plan: docs/superpowers/plans/2026-05-07-user-auth.md#task-9-12
- [ ] 登錄頁面
- [ ] 註冊頁面
- [ ] Token 存儲（localStorage）
## Errors Encountered
| Error | Context | Resolution |
|-------|---------|------------|
| - | - | - |
留意每個 Phase 下面嘅 🔗 Superpowers Plan 行。呢個係橋接嘅關鍵—agent 知道呢個 Phase 嘅實現細節喺 Superpowers plan 嘅邊啲 task 度。
Superpowers plan 橋接示例
Superpowers plan 檔案本身唔需要改動。佢保持原有嘅精確格式：
# Plan: 用戶認證模塊
## Task 1: 創建 User 模型
File: `src/models/user.py`
Duration: ~3 minutes
` ` `python
import uuid
from datetime import datetime
from sqlalchemy import Column, String, DateTime
from src.db.base import Base
class User(Base):
__tablename__ = "users"
id = Column(String, primary_key=True, default=lambda: str(uuid.uuid4()))
email = Column(String, unique=True, nullable=False, index=True)
password_hash = Column(String, nullable=False)
created_at = Column(DateTime, default=datetime.utcnow)
` ` `
Verify: `pytest tests/models/test_user.py -v`
## Task 2: 創建 Session 模型
...
工作流程全貌
1. brainstorming 階段 → 正常使用 Superpowers 的蘇格拉底式提問
2. brainstorming 完成 → 手動創建 PwF 的 task_plan.md（Phase 級別）
3. writing-plans 階段 → 正常使用 Superpowers 生成精確 plan
4. writing-plans 完成 → 在 task_plan.md 每個 Phase 中寫入 plan 路徑引用
5. 執行階段 → Superpowers 的 skill 驅動實現，PwF 的 hook 驅動進度提醒
6. 每完成一個 Superpowers task → 更新 task_plan.md 對應 Phase 的 checklist
7. session 結束 → PwF 的 Stop hook 驗證整體完成度
8. session 恢復 → PwF 的 hook 自動注入進度，Superpowers 讀取 plan 繼續
圖 5：PwF 同 Superpowers 橋接架構—Plan 路徑引用打通雙系統
注意事項
老實講，呢個方案唔係銀彈。有幾個位要留意：
同步靠自律：Superpowers 完成一個 task 之後，agent 唔一定記得去更新 task_plan.md。需要喺 hook 或 skill 入面加提醒 Context 仍然會膨脹：PwF 嘅 PreToolUse hook 照常注入，Superpowers 嘅 skill 照常載入。但至少指令唔會衝突喇—一個管進度，一個管實現 PwF 嘅 Stop hook 可能誤判：佢淨係睇 task_plan.md 嘅完成度。如果同步做得唔好，會喺唔應該停嘅時候叫停。建議喺 task_plan.md 入面加備註，標記邊啲 Phase 係跨 session 嘅
你喺項目入面同時用過兩個或以上嘅 Claude Code 插件嗎？遇過類似嘅衝突嗎？歡迎喺評論區傾下。
總結
Superpowers 同 PlanningWithFiles 唔係互斥，係互補。但係互補嘅前提係分工明確。
PlanningWithFiles 擅長管理全局進度同跨 session 記憶，Superpowers 擅長管理程式碼質素同實現流程。等 PwF 做 project manager，等 Superpowers 做 tech lead，透過 plan 路徑引用做橋接，係目前成本低過收益嘅協同方式。
唔建議強行整合。兩個工具嘅設計哲學唔同，硬要統一格式或者合併 hook，只會製造更多問題。接受兩個系統平行存在呢個事實，將精力放喺橋接同同步上，先係務實嘅做法。
講到底，好嘅工具組合唔係 1+1=2，而係各自管好各自，唔好互相添亂。
相關資源
PlanningWithFiles GitHub 倉庫：https://github.com/OthmanAdi/planning-with-files
Superpowers GitHub 倉庫：https://github.com/obra/superpowers
你身邊有同事都喺用 AI 編程助手做開發？轉發畀佢哋睇下呢個拆解。關於插件協同，你踩過啲咩坑？評論區傾下。
好喇，多謝你睇完我篇文章，如果鍾意可以點讚轉發俾需要嘅朋友，我哋下一期再見！請繼續留意！
掃碼關注，獲取更多 AI 工具嘅實戰經驗同最佳實踐。唔好錯過每一篇乾貨！
🚩 2026 年「術哥無界」系列實戰文檔 X 篇原創計劃 第 105 篇，AI 編程最佳實戰「2026」系列第 30
大家好，歡迎來到 術哥無界 | ShugeX ｜ 運維有術。
我是術哥，一名專注於 AI 編程、AI 智能體、Agent Skills、MCP、雲原生、AIOps、Milvus 向量數據庫的技術實踐者與開源佈道者！
Talk is cheap, let's explore。無界探索，有術而行。
圖 1：Superpowers + PlanningWithFiles 衝突全景
說明：本文內容基於 Superpowers（obra/superpowers）和 PlanningWithFiles（OthmanAdi/planning-with-files）的源碼分析整理而成，包括 README、SKILL.md、hooks 配置等第一手官方素材。文中的配置模板和參數建議僅供參考，實際效果請以你的業務數據和環境測試結果為準。如果有實際使用經驗，歡迎在評論區分享交流。
羣裏有朋友問：有沒有 Superpowers + PlanningWithFiles 配合使用的文章？
這個問題挺好。兩個工具單獨用都不錯——PlanningWithFiles 給 AI 加了持久化記憶，Superpowers 給 AI 套了一套嚴格的開發流程。但一起裝的時候，你會發現 agent 經常精神分裂：一個 hook 告訴它先讀 plan，另一個 hook 告訴它先調 skill。
翻了一遍兩個項目的源碼之後，我得出一個結論：這不是 bug，是結構性衝突。兩個工具的設計哲學不同，硬湊在一起用，註定互相干擾。
但也不是沒法解。先說清楚問題在哪，再說怎麼分工。
1. 拆解 PlanningWithFiles - 文件式工作記憶
PlanningWithFiles 的核心思路可以用一句話概括：把文件系統當磁盤，把上下文窗口當 RAM。
AI 的上下文窗口有容量限制，聊天記錄一長就忘事。PlanningWithFiles 的解法是把任務計劃、研究發現、操作進度全部寫成 Markdown 文件存下來。新會話開始時，自動讀取這些文件，瞬間恢復記憶。
三文件模式
task_plan.md → 追蹤階段和進度（核心文件）
findings.md → 存儲研究和發現（知識庫）
progress.md → 會話日誌和測試結果（操作日記）
task_plan.md 是靈魂。它把任務拆成 3-7 個 Phase，每個 Phase 有狀態標記（pending / in_progress / complete），還有 checklist 和決策記錄。這個文件解決的核心問題是：agent 在任何時候都知道自己在哪、該幹嘛。
Hook 注入機制
PlanningWithFiles 配了 4 個生命週期鈎子：
關鍵在 PreToolUse。每次 agent 調用工具之前，這個 hook 都會把 task_plan.md 的頭 30-50 行塞進上下文。相當於在你每次動手之前，先貼一張便籤提醒你別忘了大目標。
幾個值得關注的特性
Session Recovery（v2.2.0+）：新會話自動恢復之前的進度，不需要重複解釋 Hash Attestation（v2.37.0）：SHA-256 哈希鎖定 task_plan.md，防止內容被篡改或注入 並行計劃（v2.36.0）： .planning/YYYY-MM-DD-<slug>/目錄隔離，支持多個計劃並行推進
圖 2：PlanningWithFiles 三文件通過 4 個 Hook 與 Agent 上下文交互
2. 拆解 Superpowers - 子代理驅動開發
Superpowers 的定位不一樣。它是一個完整的軟件開發方法論框架，把 AI 寫代碼這件事拆成了 7 步標準流程：
1. brainstorming → 蘇格拉底式提問，從粗糙想法提煉設計方案
2. using-git-worktrees → 創建隔離工作空間
3. writing-plans → 將設計拆解為 bite-sized 任務（每步 2-5 分鐘）
4. subagent-driven-development → 子代理執行計劃
5. test-driven-development → RED-GREEN-REFACTOR 循環
6. requesting-code-review → 代碼審查
7. finishing-a-development-branch → 分支收尾
核心隱喻很有意思：它把 AI agent 當成一個熱情但缺乏判斷力的初級工程師。所以每一步都需要明確的指令和嚴格的審查。
Plan 文件的角色
Superpowers 的 plan 文件路徑是 docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md。
和 PlanningWithFiles 的 task_plan 完全不同。Superpowers 的 plan 是實現藍圖 - 裏面是精確的文件路徑、完整代碼、測試用例、提交命令。每個任務粒度是 bite-sized（2-5 分鐘），不允許 placeholder（TBD、TODO），每個任務自帶 TDD 循環。
一句話區分：
Superpowers plan = 怎麼把磚砌成牆 PwF task_plan = 牆砌到哪了，出了什麼問題
Skill 觸發機制
Superpowers 有個 using-superpowers skill，要求 agent 在任何行動前先檢查並調用對應的 skill。這不是建議，是強制工作流。
它的審查機制是雙階段的：先是 spec compliance（規格合規），再是 code quality（代碼質量）。寫完代碼不是終點，還得過兩道審查關。
圖 3：Superpowers 7 步工作流——從 brainstorming 到 branch 收尾
3. 協同攻堅 - 為什麼配合不好
這是文章的核心部分。我逐個拆解兩個工具的衝突點。
衝突 1：雙 Hook 系統的 Context 競爭
兩個工具都用 hook 往 agent 上下文裏塞指令。
Superpowers 的 using-superpowers 要求 agent 在任何行動前先檢查 skill，然後按 skill 的指令行動。原文是：follow skill exactly。
PlanningWithFiles 的 PreToolUse 在每次工具調用前注入 task_plan.md 的內容。原文是：read plan before decisions。
問題來了。agent 每次操作前會同時收到兩套指令注入。後果：
Context 膨脹：兩個系統的指令疊加，吃掉上下文窗口 指令衝突：一個說先調 skill，一個說先讀 plan 優先級混亂：agent 不知道先聽誰的
這不是偶爾出現的問題。PreToolUse 是每次工具調用都觸發。Superpowers 的 skill 檢查也是每次行動前都要做。兩套指令以極高的頻率疊加，agent 的行為就變得不可預測。
衝突 2：雙任務追蹤系統不同步
兩套獨立的追蹤系統，互不通信。
| 文件位置 | docs/superpowers/plans/*.md | task_plan.md |
| 任務粒度 | ||
| 狀態機制 |
同一個任務在兩個文件裏各有一份，狀態永遠對不上。
更麻煩的是 Stop hook。PlanningWithFiles 的 Stop hook 會在 agent 嘗試停止時驗證 task_plan.md 的完成度。但任務的實際執行進度在 Superpowers 的 plan 文件裏。PwF 檢查自己的 task_plan 說 Phase 2 還沒完成，但 Superpowers 已經把 Phase 2 拆成了 15 個 bite-sized task 並且全做完了。
衝突 3：Plan 文件角色衝突
前面說過，兩個 plan 文件解決的問題不一樣：
Superpowers plan 面向初級工程師，告訴它每一步怎麼寫代碼 PwF task_plan 面向注意力管理，記錄你在哪、該幹嘛
當兩者同時存在時，agent 需要在兩個源文件之間來回切換。Superpowers 說按 plan 寫代碼，PwF 說先看 task_plan 確認你在哪。兩套系統爭奪 agent 的注意力。
衝突 4：writing-plans 不會以 PwF task_plan 為骨架
這個衝突是最根本的。
Superpowers 的 writing-plans skill 有嚴格的格式要求：
每個任務必須包含精確的文件路徑、完整代碼、驗證步驟 任務粒度是 bite-sized（2-5 分鐘） 不允許 placeholder（TBD、TODO 等） 每個任務有完整的 TDD 循環
PwF 的 task_plan 組織邏輯要寬鬆得多：
Phase 級別的 checklist 不要求精確代碼 更關注你在哪而不是你怎麼做
writing-plans 不會以 PwF 的 task_plan 為骨架 - 它有自己的結構化標準。PwF 的 Phase checklist 太粗，不滿足 writing-plans 的輸入要求。
結果就是：兩套 plan 文件平行存在，永遠不交叉。你寫你的藍圖，我記我的進度，各幹各的。
衝突全景圖
圖 4：4 個衝突點嚴重程度與影響範圍
4. 落地方案 - 分工協同，不做強行整合
說了這麼多問題，解決方案的思路其實很簡單：不試圖合併兩個系統，讓各自做擅長的事。
核心思路：PwF 管全局進度，Superpowers 管實現細節。
具體做法
1. PwF 管全局
task_plan.md 只記錄 Phase 級進度、關鍵決策、錯誤日誌。不寫具體代碼，不寫實現細節。
2. Superpowers 管實現
plan 文件記錄精確的實現步驟、完整代碼、測試用例。不管進度追蹤，只管怎麼做。
3. 橋接規則
在 task_plan.md 的每個 Phase 中引用 Superpowers plan 文件路徑。agent 通過這個路徑知道這個 Phase 對應的實現細節在哪。
4. 狀態同步
Superpowers 每完成一個 task，手動（或通過自定義 hook）更新 task_plan.md 對應 Phase 的狀態。
task_plan.md 示例
下面是一個橋接版的 task_plan.md 結構：
# Task Plan: 用戶認證模塊
## Phase 1: 數據庫模型設計 [in_progress]
> 🔗 Superpowers Plan: docs/superpowers/plans/2026-05-07-user-auth.md#task-1-3
- [x] 設計 User 表結構
- [x] 設計 Session 表結構
- [ ] 編寫遷移腳本
**決策記錄**: 使用 UUID 作為主鍵，避免 ID 枚舉攻擊
## Phase 2: 認證 API 實現 [pending]
> 🔗 Superpowers Plan: docs/superpowers/plans/2026-05-07-user-auth.md#task-4-8
- [ ] POST /auth/register
- [ ] POST /auth/login
- [ ] POST /auth/logout
- [ ] JWT Token 簽發與驗證
## Phase 3: 前端集成 [pending]
> 🔗 Superpowers Plan: docs/superpowers/plans/2026-05-07-user-auth.md#task-9-12
- [ ] 登錄頁面
- [ ] 註冊頁面
- [ ] Token 存儲（localStorage）
## Errors Encountered
| Error | Context | Resolution |
|-------|---------|------------|
| - | - | - |
注意每個 Phase 下面的 🔗 Superpowers Plan 行。這是橋接的關鍵 - agent 知道這個 Phase 的實現細節在 Superpowers plan 的哪些 task 裏。
Superpowers plan 橋接示例
Superpowers plan 文件本身不需要改動。它保持原有的精確格式：
# Plan: 用戶認證模塊
## Task 1: 創建 User 模型
File: `src/models/user.py`
Duration: ~3 minutes
` ` `python
import uuid
from datetime import datetime
from sqlalchemy import Column, String, DateTime
from src.db.base import Base
class User(Base):
__tablename__ = "users"
id = Column(String, primary_key=True, default=lambda: str(uuid.uuid4()))
email = Column(String, unique=True, nullable=False, index=True)
password_hash = Column(String, nullable=False)
created_at = Column(DateTime, default=datetime.utcnow)
` ` `
Verify: `pytest tests/models/test_user.py -v`
## Task 2: 創建 Session 模型
...
工作流全貌
1. brainstorming 階段 → 正常使用 Superpowers 的蘇格拉底式提問
2. brainstorming 完成 → 手動創建 PwF 的 task_plan.md（Phase 級別）
3. writing-plans 階段 → 正常使用 Superpowers 生成精確 plan
4. writing-plans 完成 → 在 task_plan.md 每個 Phase 中寫入 plan 路徑引用
5. 執行階段 → Superpowers 的 skill 驅動實現，PwF 的 hook 驅動進度提醒
6. 每完成一個 Superpowers task → 更新 task_plan.md 對應 Phase 的 checklist
7. session 結束 → PwF 的 Stop hook 驗證整體完成度
8. session 恢復 → PwF 的 hook 自動注入進度，Superpowers 讀取 plan 繼續
圖 5：PwF 和 Superpowers 橋接架構——Plan 路徑引用打通雙系統
注意事項
說實話，這個方案不是銀彈。有幾個坑需要知道：
同步靠自律：Superpowers 完成一個 task 後，agent 不一定記得去更新 task_plan.md。需要在 hook 或 skill 中加入提醒 Context 仍然會膨脹：PwF 的 PreToolUse hook 照常注入，Superpowers 的 skill 照常加載。但至少指令不會衝突了 - 一個管進度，一個管實現 PwF 的 Stop hook 可能誤判：它只看 task_plan.md 的完成度。如果同步沒做好，會在不該停的時候叫停。建議在 task_plan.md 中加入備註，標記哪些 Phase 是跨 session 的
你在項目中同時用過兩個以上的 Claude Code 插件嗎？遇到過類似的衝突嗎？歡迎在評論區聊聊。
總結
Superpowers 和 PlanningWithFiles 不是互斥的，是互補的。但互補的前提是分工明確。
PlanningWithFiles 擅長管理全局進度和跨 session 記憶，Superpowers 擅長管理代碼質量和實現流程。讓 PwF 做項目經理，讓 Superpowers 做技術負責人，通過 plan 路徑引用做橋接，是目前成本低於收益的協同方式。
不建議強行整合。兩個工具的設計哲學不同，硬要統一格式或合併 hook，只會製造更多問題。接受兩個系統平行存在這個事實，把精力放在橋接和同步上，才是務實的做法。
說到底，好的工具組合不是 1+1=2，而是各管各的，互不添亂。
相關資源
PlanningWithFiles GitHub 倉庫：https://github.com/OthmanAdi/planning-with-files
Superpowers GitHub 倉庫：https://github.com/obra/superpowers
你身邊有同事也在用 AI 編程助手做開發？轉發給他們看看這個拆解。關於插件協同，你踩過什麼坑？評論區聊聊。
好啦，謝謝你觀看我的文章，如果喜歡可以點贊轉發給需要的朋友，我們下一期再見！敬請期待！
掃碼關注，獲取更多 AI 工具的實戰經驗和最佳實踐。不錯過每一篇乾貨！