Claude Code Plugin 設計拆解：從 zenbu-powers 偷到的 5 個架構模式

TL;DR

- 本文解決:Claude Code 玩家想自己長大 ~/.claude/,有沒有現成範本可參考?

- 推薦給:已經在用 Claude Code、會手寫 skill / agent / hook 的工程師

- 讀完你會知道:zenbu-powers 的 5 個值得偷的設計模式、哪些可以直接抄、為什麼不建議整包安裝

最近在研究 Claude Code Plugin 生態,被一個叫 zenbu-powers 的 repo 吸住三個小時。它在 GitHub 上 0 stars、1 fork,完全不紅,但翻完整個專案後我直接把兩個設計搬進自己的 ~/.claude/CLAUDE.md。

這篇就講為什麼一個沒人按星的 plugin 值得寫一篇文章,以及哪 5 個設計模式可以直接抄回家。

📌 目錄

🧠 zenbu-powers 是什麼

簡單講:台灣 zenbu org 內部用的 Claude Code Plugin,GitHub 上是 zenbuapps/zenbu-powers,作者 j7-dev,License MIT。

幾個基本事實先攤開:

你(使用者)
    ↓
Orchestrator(Claude 主窗口)
    ├─→ 22 個 Agent(WordPress / React / NestJS / 審查 / DevOps / 文件)
    └─→ 150 個 Skill(流程心法 / 框架知識 / Library 參考)

主窗口被定位成「不下場實作的協調者」,負責拆任務、派 agent、整合報告;真正寫 code 的是 sub-agent。Skill 則是被動載入的知識庫,只有被 Claude 判斷需要時才讀進來。

技術棧偏 WordPress / React + Refine + Ant Design / NestJS,加上一套自家發明的 AIBDD(AI Behavior-Driven Development)三語言整合測試套件,涵蓋 TypeScript / PHP / C#。

跟 obra/superpowers 是什麼關係?作者自己 README 講白:zenbu-powers 是 superpowers 的超集,把 systematic-debugging、finishing-branch、tdd-workflow 的 verification-gate、SessionStart hook 架構整套搬過來,再疊上自己 org 的技術棧。所以兩個不要同時裝,會打架。

⚖️ vs superpowers vs 自建 ~/.claude 比較

⭐ 值得偷的 5 個設計模式

我從整個 repo 翻出 5 個可以單獨抽出來、不用整包裝的設計。

1. SessionStart Hook 注入 Orchestrator 心法

每次 Claude Code session 啟動、/clear、/compact 時,自動把一份「主窗口應該怎麼工作」的長文塞進 context。

實作藏在 hooks/session-start(bash 寫的),核心動作三步:

# 1. 讀 skills/using-zenbu-powers/SKILL.md
using_zp_content=$(cat "${PLUGIN_ROOT}/skills/using-zenbu-powers/SKILL.md")
# 2. JSON-escape(用純 bash parameter substitution,比 Python jq 快很多)
using_zp_escaped=$(escape_for_json "$using_zp_content")
# 3. 依平台輸出對應格式
# Cursor → additional_context
# Claude Code → hookSpecificOutput.additionalContext
# Copilot CLI → additionalContext

為什麼值得偷: 你不用每次新開 session 都重講「請當 orchestrator、不要動手實作、優先派 sub-agent」,這些紀律寫一次注入一次,Claude 第一個回應之前就知道規則。

怎麼自己抄: 在 ~/.claude/skills/ 開一個 meta-skill(例:using-bob-rules/SKILL.md),寫一個 SessionStart hook 把它讀出來、escape、塞 hookSpecificOutput.additionalContext,設定 ~/.claude/settings.json 讓 hook 啟動。

2. Stop Hook + acceptance-evaluator + round_count 防無限迴圈

這個是整包最值得偷的東西。

hooks/hooks.json 註冊 Stop hook,每次主 agent 結束 → 自動 dispatch 一個 acceptance-evaluator sub-agent,做意圖對齊驗收。Evaluator 檢查產出是否真的滿足使用者原始需求,沒過就回 {"ok": false, "reason": "..."} 讓主 orchestrator 繼續修。

關鍵設計是 round_count 上限:

{
  "hooks": [{
    "type": "agent",
    "prompt": "讀 ${HOME}/.claude/data/zenbu-loop-state.json 取本 session round_count。
              若 >= 3,回 {ok: true, reason: '3 輪驗收上限已達'} 升級給用戶。
              否則 dispatch evaluator → PASS 重置 count、FAIL count++ 寫回 state file"
  }]
}

為什麼值得偷: 解決一個很常見的痛點 ── agent 寫完跟你說「完成了」,結果根本沒滿足需求,你還要自己抓。Evaluator 自動補這道驗收,3 輪沒過才升級給人,既不會無限燒 token、又不會把爛產出直接丟出來。

Stop hook 還含一個必看細節: 帶 stop_hook_active flag 防無限迴圈,因為 hook 自己 dispatch 的 sub-agent 結束時也會觸發 Stop,沒擋會炸。

3. 自主決策授權 + 三類窄門

寫在 using-zenbu-powers/SKILL.md,直接抄一段(我有改寫過,原文更長):

規則: 遇到多個合理方案時,orchestrator 必須自己選一個並推進,不得把選擇題丟回給用戶。決策 heuristic(依優先順序):與既有架構/慣例一致 → 可逆性高 → 最小驚訝 → 保守(blast radius 低)→ 資訊充足者勝。

例外只有三類「窄門」(暫停問用戶才合法):

為什麼值得偷: 一般 Claude 的預設行為偏「禮貌詢問」,動不動丟兩三個選項給你選,打斷思路。這套規則明確切割「自己決」跟「先問」的邊界,事後在報告補 trade-off,讓你保留 informed override 權但不被中斷。

4. 任務分級(輕量自評 vs 重量必走 evaluator)

不是所有任務都要走完整驗收 loop。zenbu-powers 切兩級:

為什麼值得偷: 解決 over-engineering 跟 under-engineering 同時發生的問題 ── 改個錯字也要 evaluator 太煩、改 schema 不審又危險。用任務體質決定流程粒度。

5. Polyglot Hook Wrapper(cmd.exe / bash 共用)

這個比較工程小巧,但很妙。hooks/run-hook.cmd 同一個檔案,Windows cmd.exe 跟 macOS / Linux bash 都能解析:

• Windows 端 → cmd 讀檔頭 batch 指令、自動偵測 Git Bash 跑
• macOS / Linux → bash 直接跳過 batch 段執行 shell 邏輯

為什麼值得偷: 如果你會把自己的 plugin 分享給跨平台同事,這個 wrapper pattern 直接套。如果你只在 mac 上跑(像我),用不到,但規避 heredoc bug 那招值得記。

🔥 我自己偷了哪些、改寫進 CLAUDE.md

實際做了什麼:把上面 #3 跟 #4 改寫成更貼合自己 workflow 的版本,加進 ~/.claude/CLAUDE.md 約 30 行。原本 zenbu-powers 是「全部自主」哲學,但我跟 Claude 是有人在線、隨時 push 回的協作模式,設計層還是要丟選項給我選,所以改寫成「三層決策權」:

## 決策權分層
層級
範圍
行為
實作層
命名、檔案位置、import 順序、helper 抽不抽
自己決定,事後補 trade-off
設計層
技術選型、資料模型、API 形狀、UI 流程
給 2-3 選項 + trade-off + 推薦
業務層
密碼、發外部訊息、不可逆動作
一定先問
卡關升級規則
同一個問題嘗試 3 次仍無進展 → 停下升級給我,不要無限重試。
重量任務 self-review
跨 ≥3 檔 / 跨層 / 含不可逆操作 / 用戶含「驗收 / 不能出包」關鍵詞
→ 交付前自己先掃一輪(邏輯、邊界、是否破壞既有測試)再回報

沒偷的東西: Stop hook + evaluator 那套(設計 #2)。為什麼?我現有 Stop hook 已經有 mempalace-stop-quiet.sh 跟 line-dispatch.sh,硬塞 evaluator 進去要先想清楚順序跟 race condition,先擱著,有空再做。

整包安裝?完全不考慮。 跟我現有 150+ skills 大量重名(tdd-workflow、brainstorming、systematic-debugging...),衝突率太高。

⚠️ 不建議整包安裝的 3 個理由

老實講出來,免得有人看完上面就 claude plugin install:

理由 1:技術棧不合

zenbu-powers 重心是 WordPress / PHP / Refine + Ant Design / NestJS。如果你寫 Java / Go / Rust / Python 後端,150 個 skill 裡能用的不到 30 個,其他都在硬碟上吃位子。

雖然 README 說「skill 是被動載入,不影響 context」,但 agent 命名(wordpress-master、nestjs-master)會誘導 Claude 往這些方向想,容易產生不貼合的建議。

理由 2:Skill 命名衝突

如果你已經裝過 obra/superpowers、或自己寫過 tdd-workflow、brainstorming、systematic-debugging 這種通用流程 skill,會跟 zenbu-powers 重名。Claude 拿到兩個同名 skill 行為不一致,結果就是不穩定。

作者自己 README 也明說兩個不要並存。

理由 3:文件同步不嚴謹

最直接的證據:README 開頭寫 v3.3.1,但 plugin.json 寫 v3.11.3。中間 8 個 minor 版本沒在 README 反映。

不是說作者懶,有專門開 docs(readme): commit 修文件,但只在重大改版才更新一次。如果你照 README 的 skill / agent 清單去用,會跟實際目錄對不上。

要參考設計哲學沒問題,要照清單操作就直接讀 agents/ 跟 skills/ 目錄,不要信 README。

❓ 常見問題

zenbu-powers 跟 superpowers 差在哪?要選哪個?

zenbu-powers 是 superpowers 的超集,把 superpowers 的核心方法論(systematic-debugging、finishing-branch、tdd-workflow verification-gate、SessionStart hook)整套搬過來,再疊上 zenbu org 的 WordPress / React / NestJS 技術棧。兩個不要並存會打架。如果你寫 WordPress 多 → zenbu-powers;如果你只想要核心心法 → superpowers。

我不寫 WordPress / PHP,還用得到 zenbu-powers 嗎?

整包不建議裝(理由見上)。但單獨偷某些設計模式完全可以,例如 SessionStart 注入心法、Stop hook + evaluator、自主決策授權。我自己就只偷了兩個改寫進 CLAUDE.md,沒裝整包。

怎麼只偷它的設計模式不裝整包?

gh repo clone zenbuapps/zenbu-powers /tmp/zenbu-powers 下來當參考,看 hooks/、skills/using-zenbu-powers/SKILL.md 兩個目錄就夠。把要的設計手抄進你自己的 ~/.claude/CLAUDE.md 或 ~/.claude/skills/,不要直接 plugin install。

SessionStart hook 注入會吃掉很多 context 嗎?

using-zenbu-powers/SKILL.md 本身約 200-400 行(含 references),escape 後塞進 hookSpecificOutput.additionalContext。會吃 context,但只在 SessionStart / clear / compact 觸發,平時不會重複。如果你 context 已經很緊,可以拆成精簡版只保留核心紀律,把詳細 reference 改成「需要時再讀檔案」的引用模式。

為什麼 stars 是 0 還值得寫?

Stars 反映「多少人發現這 repo」,不直接反映設計品質。zenbu-powers 是台灣團隊內部 plugin,沒做行銷推廣,但設計成熟度、hook 工程細節、Orchestrator 心法的條理遠超過很多上千 star 的 dotfiles repo。stars 只是 popularity proxy,不是 quality proxy。

🔗 延伸資源

• zenbuapps/zenbu-powers GitHub
• obra/superpowers(被致敬的源頭)
• Claude Code 官方 Plugin 文件
• 本站相關文章:Claude Code 是什麼?完整介紹
• 我自己改寫進 CLAUDE.md 的版本見上面〈我自己偷了哪些〉那段