Claude Code 專案失敗的根本原因

大多數 Claude Code 專案的失敗並非源自提示詞品質不佳，而是來自架構漂移、治理不力、不安全的預設設定，以及缺乏驗證機制。為了解決這些深層問題，作者基於其文章《You Don't Know Claude Code》推出了「Claude Health」——一個系統性審計工具，針對 Claude Code 配置的全層架構進行檢測。

六層框架診斷法

Claude Health 採用六層框架進行全面審計：

• CLAUDE.md（主配置檔）
• rules/（規則層）
• skills/（技能層）
• hooks/（鉤子層）
• subagents（子 Agent）
• verifiers（驗證器）

該工具會自動偵測專案複雜度（簡單 / 標準 / 複雜），並根據專案規模調整檢查標準，避免對小型專案不必要的規範要求。

檢查涵蓋面

Claude Health 的檢查清單相當細緻，涵蓋 CLAUDE.md 的訊號雜訊比與內容冗長度、rules 的語言特定規則配置缺口、skills 的 token 計數與自動觸發策略，以及安全相關的多個維度——包括提示注入、資料外洩、具破壞性的指令、硬編碼認證、混淆技術和安全覆蓋繞過。此外還檢查 hooks 的模式欄位完整性、MCP（Model Context Protocol）伺服器計數及其 token 成本、allowedTools 中的危險或陳舊指令、提示快取中的動態時戳與模型切換問題，以及三層防禦（CLAUDE.md + 技能 + Hook 是否共同覆蓋關鍵規則）的有效性。

優先級分類報告

工具輸出結果分為三個優先等級，明確指示修復順序：

• 嚴重：須立即修復，包括規則違反、危險權限、快取破壞模式、MCP 開銷超過 12.5%，以及技能安全問題（提示注入、資料外洩等）
• 結構性：應盡快修復，涵蓋內容配置錯誤、缺失 hooks、單層關鍵規則、技能品質問題（內容冗長、參考斷裂）
• 漸進式：可選改進，包括上下文衛生習慣、HANDOFF.md 採用、技能頻率優化、技能溯源（符號連結來源、版本追蹤）

實際執行方式

使用者可透過全域安裝（npx skills add tw93/claude-health -a claude-code -s health -g -y）或專案級安裝，在 Claude Code 中執行 /health 指令或直接告訴 Claude「Run a health check on my Claude Code config」。工具會自動檢測專案類型並執行兩個平行診斷 Agent，最終輸出優先順序清單，指導使用者從最迫切的問題開始修復。

這套工具反映了一個重要認知：Claude Code 的成敗取決於系統化的架構、明確的治理框架和多層防禦機制，而非單純的提示詞調優。