分類: 工具與實踐

上一篇文章整理了 github.com/obra/superpowers 裡所有 skill 的隱藏規則。這篇要回答一個更根本的問題：這些規則白紙黑字寫得清清楚楚，為什麼 Claude 實務上常常不遵守？

Skill 的規則是真實存在的

先確認這些規則不是我們誤解或誤記的。以下是幾條最關鍵規則的原始出處：

鐵律 1：修了三次還沒修好，停下來

來源：skills/systematic-debugging/SKILL.md 第 195-197 行

If < 3: Return to Phase 1, re-analyze with new information
If ≥ 3: STOP and question the architecture (step 5 below)
DON’T attempt Fix #4 without architectural discussion

同一個檔案第 227 行：

“One more fix attempt” (when already tried 2+)
ALL of these mean: STOP. Return to Phase 1.

鐵律 2：選最便宜的 model

來源：skills/subagent-driven-development/SKILL.md 第 89-91 行

Use the least powerful model that can handle each role to conserve cost and increase speed.
Mechanical implementation tasks (isolated functions, clear specs, 1-2 files): use a fast, cheap model. Most implementation tasks are mechanical when the plan is well-specified.

鐵律 3：沒有失敗測試不能寫 code

來源：skills/test-driven-development/SKILL.md 第 31-34 行

## The Iron Law

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

鐵律 4：1% 機率就必須 invoke skill

來源：skills/using-superpowers/SKILL.md 第 11-15 行

If you think there is even a 1% chance a skill might apply to what you are doing, you ABSOLUTELY MUST invoke the skill.

IF A SKILL APPLIES TO YOUR TASK, YOU DO NOT HAVE A CHOICE. YOU MUST USE IT.

This is not negotiable. This is not optional. You cannot rationalize your way out of this.

鐵律 5：宣稱完成前必須這個訊息內跑過驗證

來源：skills/verification-before-completion/SKILL.md 第 16-22 行

## The Iron Law

If you haven’t run the verification command in this message, you cannot claim it passes.

規則是真實的，寫得清楚，甚至用了「Iron Law」、「ABSOLUTELY MUST」、「NOT negotiable」這些最強烈的措辭。

那為什麼實務上 Claude 修了四次五次還在猜？為什麼還是會選 Haiku？為什麼不跑完驗證就說「完成了」？

五個根本原因

原因 1：Skill 是文字，沒有執行引擎

Skills 的運作方式是：Claude 呼叫 Skill 工具 → 工具把 SKILL.md 的內容貼進 context → Claude 讀完然後「盡力遵守」。

沒有 interpreter，沒有 runtime，沒有 if-then 邏輯，沒有計數器，沒有警報。Claude 違反規則不會有任何程式層面的後果。

這就是為什麼 using-superpowers/SKILL.md 第 13 行要用大寫強調「YOU DO NOT HAVE A CHOICE」—— 因為它知道 Claude 有選擇，它在試圖用措辭彌補缺乏強制力這件事。

原因 2：Skill 沒被載入就不存在

using-superpowers skill 規定「每次對話開始前先查 skill」，但執行這條規則的還是 Claude 本身。如果 Claude 這次忘了 invoke Skill 工具，systematic-debugging 的三次上限根本不在 context 裡，等於不存在。

這是一個自我參照的問題：「用 skill 確保 skill 被用」的規則本身也依賴 skill 被正確載入才能生效。

原因 3：Context 壓縮吃掉規則

長對話之後，Claude Code 會自動壓縮前面的 context。Skill 內容被載入進 context，但在第五次修 bug 的時候，第一次載入的 systematic-debugging 很可能已經被壓縮到只剩摘要，「三次停下來」這條規則不見了。

Claude 不是故意無視規則，是規則已經不在它的視野裡了。

原因 4：RLHF 訓練行為覆蓋 skill 規則

Claude 的訓練讓它傾向：

• 持續幫忙（不輕易放棄）
• 樂觀估計（「這次應該可以」）
• 不讓使用者失望（說「我不知道怎麼修」感覺像失敗）

Skill 說「第三次停下來討論架構」，但訓練說「繼續幫用戶解決問題」。訓練是骨子裡的，skill 是貼上去的文字。骨子裡的贏。

這個矛盾在 skill 作者知道：systematic-debugging/SKILL.md 第 195 行不只說「stop」，還用粗體、全大寫，以及「DON’T attempt Fix #4」的雙重否定，都是試圖用措辭強度來對抗訓練行為。

原因 5：Haiku 沒有能力執行複雜的工作流程規則

來源：skills/subagent-driven-development/SKILL.md 第 89-100 行告訴 Claude 選最便宜的 model。

但兩階段 review（spec compliance → code quality）、四種 status 的不同處理邏輯、三次上限計數、context 打包給 subagent——這些都需要相當的推理能力。Haiku 被選來做「機械性」的工作，卻遇到需要判斷的情況時，它沒有能力忠實執行這些細緻規則，就退回最直覺的行為：繼續做、繼續猜。

所以 skill 的 model 選擇規則本身，就是讓 skill 的其他規則失效的原因之一。

一個具體的案例：兩階段 Review 的崩潰

subagent-driven-development 規定兩階段 review，而且有嚴格順序（SKILL.md 第 247 行）：

Start code quality review before spec compliance is ✅ (wrong order)

這個規定存在，是因為曾經出問題（skills/writing-skills/SKILL.md 第 154-156 行）：

Testing revealed that when a description summarizes the skill’s workflow, Claude may follow the description instead of reading the full skill content. A description saying “code review between tasks” caused Claude to do ONE review, even though the skill’s flowchart clearly showed TWO reviews (spec compliance then code quality).

換句話說：

1. Skill 的 description 寫了工作流程摘要
2. Claude 讀了 description 就走捷徑，沒有讀完整 SKILL.md
3. 看到「code review between tasks」→ 只做了一次 review
4. 整個兩階段機制失效

修法是把 description 改成只描述「什麼時候用這個 skill」，不描述工作流程。但這同時說明：一個措辭上的疏漏，就足以讓整個 skill 的核心機制失效，而且你不會知道。

另一個案例：Permission 擋住了整個 Review Loop

我們最近遇到的真實案例：在 ~/.claude/settings.json 裡，PermissionRequest hook 的 matcher 設定為 Agent|TeamCreate|Team，而 hook 的行為是對 Agent 工具直接回傳 deny。

結果：每次 LEAD 要 dispatch subagent（不管是 implementer、spec reviewer 還是 code quality reviewer），都被系統層面攔截拒絕。

兩階段 review 的規則還在 context 裡，Claude 也打算遵守，但 Agent 工具每次都失敗。Skill 的工作流程完全無從執行。

修法：把 Agent 從 hook matcher 移除（改成 TeamCreate|Team），並把 defaultMode 改成 bypassPermissions。這個設定層面的問題修好之後，Agent Team 才能真正按 skill 的設計跑。

Skills 在什麼條件下才有效

綜合以上，Skills 的效果受以下條件影響：

你能做什麼

Skill 的規則沒辦法完全靠 Claude 自己執行，但有幾件事可以提升遵守率：

1. 在 CLAUDE.md 加覆寫規則（降低對 skill 的依賴）

## Superpowers Skill Override Rules

### Model Selection
NEVER use haiku for implementation tasks. Follow:
- opus: architecture, code review, cross-file reasoning
- sonnet: all implementation tasks
- haiku: file scanning, directory listing ONLY

### Git Branch
No branch confirmation needed when already on non-main/master branch.

### Debugging Limit
After 3 failed fix attempts, STOP and escalate to user.
Do not attempt Fix #4 without discussion.

2. 修好 settings.json（讓 Agent 工具不被攔截）

{
  "permissions": {
    "allow": ["Agent"],
    "defaultMode": "bypassPermissions"
  },
  "feedbackSurveyRate": 0
}

3. 在 AGENTS.md 明確指定每個 agent 的 model

| Agent | Model | Role |
|-------|-------|------|
| implementer | sonnet | Feature implementation |
| spec-reviewer | sonnet | Spec compliance check |
| code-reviewer | opus | Code quality review |

4. 永遠從 dev branch 開工

git checkout -b dev

避開所有 skill 的 main/master 保護規則，減少一類不必要的確認詢問。

一個誠實的評估

Superpowers skill 系統的設計思路是正確的：把軟體開發的最佳實踐（TDD、系統性除錯、分層 review）轉化為 AI agent 的工作協議。規則本身大多有充分的理由。

但在現實中，一個純粹依賴文字指令的系統，要對抗 LLM 的訓練行為、context 長度的物理限制、以及工具層的設定問題，注定只能是「盡力遵守」而非「強制執行」。

理解這個落差，比假設 Claude 完全遵守更有用。知道規則存在、知道為什麼可能失效，讓你能夠在關鍵節點主動介入，而不是事後才發現 Claude 在第五次猜測同一個 bug。

延伸閱讀：

• Claude Code Superpowers 隱藏規則：4 個你不知道的坑與避開方法
• Agent Team 穩定的關鍵：spawn 之前先建好兩份文件
• github.com/obra/superpowers（原始碼）

用 Claude Code 跑 Agent Team 一段時間後，你可能會發現：明明設定都正確，Claude 還是會跑來問奇怪的問題、用錯 model、或在不該停的地方停下來。這篇文章整理了 Superpowers plugin 裡幾條「你不一定知道」的隱藏規則，以及最簡單的避開方法。

為什麼 Agent Team 會「自己做決定」？

Claude Code 的 Superpowers plugin 提供了一套 skill 系統，讓 Claude 在執行任務時有明確的工作流程可依循。這些 skill 設計上是給通用場景用的，因此內建了一些「省成本、保安全」的預設行為。

問題是：這些預設行為有時候和你的需求相衝突，而且你很難從文件上看出來。

隱藏規則 1：Skill 會自動選最便宜的 Model

來源： subagent-driven-development skill

這條規則直接寫在 skill 裡：

“Use the least powerful model that can handle each role to conserve cost and increase speed. Mechanical implementation tasks: use a fast, cheap model.”

也就是說，當 Claude 判斷一個 task 是「機械性的」（1-2 個檔案、規格清楚），它就會選 Haiku。這對一般的 CRUD 功能可能沒問題，但對複雜業務邏輯（像 iDempiere plugin、Taiwan 發票系統）來說，Haiku 根本不夠用。

Skill 的 Model 選擇邏輯

避開方法：在 AGENTS.md 明確指定 Model

最簡單的解法是在每個專案的 AGENTS.md 裡明確寫好每個 agent 的 model。Claude 在 dispatch subagent 時，如果 AGENTS.md 有寫，就應該照抄，不用自己判斷。

| Agent | Model | Role |
|-------|-------|------|
| pack-builder | sonnet | Build 2Pack XML + ZIP |
| model-fixer | sonnet | Fix Model classes |
| idempiere-expert | opus | Technical reviewer |

同樣地，在 IMPLEMENTATION_PLAN.md 每個 phase 標上 model，讓 LEAD 照單全收：

## Phase 0.1：建立 PackOut.xml [pack-builder / sonnet]
## Phase 0.2：Activator 邏輯 [activator-fixer / sonnet]
## Review Gate [idempiere-expert / opus]

隱藏規則 2：在 main/master 上工作會被詢問確認

來源： 幾乎所有 implementation skill

所有 skill 都有這條規則：“Never start implementation on main/master without explicit user consent.” 只要你的 working branch 叫 main 或 master，Claude 每次開始實作前都會停下來問你確認。

避開方法：永遠從 dev branch 開工

一條指令解決：

git checkout -b dev

在 dev branch 上，這條保護規則不會觸發。這也是好的 git 習慣，順手為之即可。

隱藏規則 3：Subagent 不繼承你的對話 Context

來源： 所有使用 subagent 的 skill

這是設計上的特性，不是 bug：每個 subagent 都是 fresh 啟動，完全不知道你之前跟 LEAD 說過什麼。LEAD 要把所有需要的 context 手動打包給 subagent。

這代表你告訴 LEAD「不要動 X 檔案」、「記得用 Y 方式」，subagent 不一定會知道，除非 LEAD 把這些資訊包進去。

避開方法：把規則寫進文件，不要只說給 LEAD 聽

任何重要的約定，放進 AGENTS.md、CLAUDE.md 或 IMPLEMENTATION_PLAN.md。這些檔案 subagent 啟動時會讀到，不依賴 LEAD 的記憶。

隱藏規則 4：Feedback Survey 會擋住畫面

Claude Code 會隨機彈出「How is Claude doing this session?」的評分畫面。這個畫面不是 blocking prompt，按 Enter 沒有用，要按 0 才能 dismiss。

更乾脆的做法是直接關閉它。在 ~/.claude/settings.json 加一行：

{
  "feedbackSurveyRate": 0
}

設為 0 後，這個 survey 就永遠不會出現了。

完整 CLAUDE.md 覆寫規則範本

把以下內容加進你的 CLAUDE.md，可以覆寫 skill 的預設行為：

## Superpowers Skill Override Rules

### Model Selection (OVERRIDES subagent-driven-development skill)
NEVER use haiku for implementation tasks. Follow this mapping regardless
of what the skill says about "mechanical" tasks:
- opus: architecture decisions, code review, cross-file reasoning
- sonnet: all implementation tasks (CRUD, API, forms, tests, services)
- haiku: file scanning, directory listing, config comparison ONLY

When dispatching subagents, ALWAYS check AGENTS.md for the assigned model.
If AGENTS.md specifies a model, use it. Do not override with cheaper model.

### Git Branch
Never ask for branch confirmation if already on a non-main/master branch.
Treat any branch that is not named "main" or "master" as pre-approved for
implementation work.

一次性設定清單

以下是只需要做一次的設定，之後每個專案都受益：

以下是每個新專案開始時的習慣：

1. git checkout -b dev（避開 main/master 保護規則）
2. 建立 AGENTS.md 並寫好每個 agent 的 model
3. 在 IMPLEMENTATION_PLAN.md 每個 phase 標記 model

為什麼這些規則存在？

這些 skill 是為「通用場景」設計的，預設行為是合理的：

• 省成本： 對大多數用戶來說，Haiku 做簡單任務確實夠用，費用少一半
• 保安全： 不讓 Claude 在 main branch 亂動是好習慣
• 隔離 context： Fresh subagent 避免舊 context 污染新任務

問題不是規則本身，而是當你的專案比「通用場景」複雜時，這些預設值就不夠精準了。透過明確的文件（AGENTS.md、CLAUDE.md）和一次性的 settings.json 設定，你可以讓 Claude 按照你的規格工作，而不是照 skill 的預設值工作。

延伸閱讀：

• Agent Team 穩定的關鍵：spawn 之前先建好兩份文件
• Claude Code 實戰：5 個核心技巧讓 AI 一次到位