程式碼健康 MCP（CodeScene）
針對 AI 輔助編碼的結構化可維護性回饋。補充風格/lint 技能（coding-standards、plankton-code-quality），提供設計層級的健康評分與回歸門檻。
上游來源： codescene-oss/codescene-mcp-server
套件： @codescene/codehealth-mcp（透過 npx 使用 stdio）
安全性與邊界
選擇性啟用（ECC）： mcp-configs/mcp-servers.json 中的 codescene 區塊僅為範本。ECC 插件安裝不會自動啟用捆綁的 MCP 伺服器。僅在需要時才將該項目複製到您的設定檔中。您可以透過 ECC_DISABLED_MCPS=codescene,... 在 ECC 安裝/同步時排除它。
憑證： 無內建令牌。請自行設定 CS_ACCESS_TOKEN（請參閱上游儲存庫中的 getting-a-personal-access-token.md）。切勿將令牌提交到儲存庫。
工具讀取的內容： 當被呼叫時，工具會分析本地儲存庫中您指定的檔案和 git 狀態（您傳遞的路徑，以及用於 analyze_change_set 的分支上下文）。它們不會自動執行。對於獨立模式，請遵循上游隱私文件：codescene-mcp-server README 和 CodeScene 政策。請勿將此技能用於您不希望被分析的機密、憑證或路徑。
如果 MCP 無法使用（離線、令牌錯誤、伺服器崩潰）： 請勿虛構程式碼健康分數。請告知使用者該檢查已跳過。僅在使用者明確同意下才繼續進行。當 MCP 當機時，優先使用 lint/測試/驗證循環來進行關卡檢查。一旦伺服器重新連線，再重新啟用檢查。
使用時機
- 使用者要求審查程式碼品質、重構檔案，或檢查 AI 變更是否降低了可維護性
- 在編輯熱點、舊有模組或不熟悉的檔案之前
- 在提交或拉取請求之前需要可維護性的安全防護
- 在大型 AI 生成差異之後 — 驗證程式碼健康未惡化
- 與
verification-loop、tdd-workflow或/quality-gate搭配使用，作為結構化檢查（非取代測試/lint）
啟用時機
與上方「使用時機」相同 — 此標題是 ECC 用於技能自動啟用的依據。
運作方式
1. 連接 MCP 伺服器
將 mcp-configs/mcp-servers.json 中的 codescene 項目複製到您的工具 MCP 設定檔中。
Claude Code (~/.claude.json → mcpServers)：
"codescene": {
"command": "npx",
"args": ["-y", "@codescene/codehealth-mcp"],
"env": {
"CS_ACCESS_TOKEN": "YOUR_CS_ACCESS_TOKEN_HERE"
}
}
專案範圍： 將相同區塊合併到儲存庫根目錄的 .mcp.json 中。
令牌設定文件記錄在上游儲存庫中（連結如上）。對於下列四個工具，獨立模式不需要付費的 CodeScene 平台帳戶。重新啟動工作階段，並在依賴分數之前確認 codescene 伺服器已連線。
2. 僅呼叫獨立工具
| 工具 | 使用時機 |
|---|---|
code_health_review | 修改前進行完整的結構分析 |
code_health_score | 每次變更後快速取得數值分數（差異檢查） |
pre_commit_code_health_safeguard | 阻止引入程式碼健康廻歸的提交 |
analyze_change_set | 開啟 PR 前進行分支層級檢查 |
請勿呼叫僅限平台的工具（例如全儲存庫的技術債熱點清單）。請勿參考 delta_analysis — 獨立模式中無法使用。
3. 解讀分數（1–10）
| 範圍 | 含義 | 代理行為 |
|---|---|---|
| 9.0–10.0 | 綠色 — 健康 | 較安全地擴充；但仍偏好垂直切割 |
| 4.0–8.9 | 黃色 — 有債 | 謹慎處理；不要順便重構 |
| 1.0–3.9 | 紅色 — 嚴重債 | 僅限於狹窄的範圍 |
4. 執行回饋循環
在觸碰檔案之前
- 在目標路徑上執行
code_health_review。 - 記錄基線分數和列出的程式碼異味。
- 規劃能解決任務的最小變更。
根據分數決定範圍：低於 5 — 僅進行最小差異；5–7 — 不做廣泛重構；高於 7 — 重構較安全，但每次編輯後仍需驗證。
每次變更之後
- 在同一檔案上執行
code_health_score。 - 與
code_health_review的基線分數進行比較。 - 如果分數惡化，請先修正再繼續。絕不要在心得分數低於初始值時標記任務完成。
在每次提交前 — 在儲存庫路徑上執行 pre_commit_code_health_safeguard。
在 PR 前 — 針對基底分支（例如 main）執行 analyze_change_set。
範例
範例：Flask 可維護性改善
在 pallets/flask 上，一個僅使用獨立工具的代理循環：
- 在目標模組上執行
code_health_review（基線 4.82） - 針對列出的異味進行有目標的重構
- 每次編輯後執行
code_health_score - 提交前執行
pre_commit_code_health_safeguard - PR 前執行
analyze_change_set
結果：程式碼健康 4.82 → 9.1（僅使用免費獨立令牌）。
範例：AGENTS.md 強制區塊
貼入專案的 AGENTS.md 或 CLAUDE.md：
## 程式碼健康（CodeScene MCP）
在修改任何檔案之前：執行 `code_health_review`，記錄分數和問題。
- 分數低於 5：有問題的範圍 — 嚴格限縮變更範圍。
- 分數 5–7：警告範圍 — 不做廣泛重構。
每次變更後：執行 `code_health_score` 以驗證差異。
- 如果分數惡化：先修正再繼續；如果分數下降，絕不宣告完成。
在每次提交前：執行 `pre_commit_code_health_safeguard`。
在 PR 前：執行 `analyze_change_set`。
範例：反模式 vs 正確循環
# 錯誤：先編輯，後檢查
[未經 code_health_review 的大規模重構]
# 錯誤：忽略分數下降
"測試通過" → 在程式碼健康下降時標記任務完成
# 錯誤：在紅色分數檔案（低於 5）上進行廣泛重構
跨模組的順便清理
# 正確：審查 → 小變更 → 分數 → 提交防護 → analyze_change_set
與 ECC 搭配
| ECC 技能/流程 | Code Health MCP 角色 |
|---|---|
coding-standards | 風格/命名；Code Health = 結構/複雜度 |
plankton-code-quality | 寫入時 lint/格式化；Code Health = 編輯前/後的結構關卡 |
verification-loop / /quality-gate | 在「完成」前加入結構惡化檢查 |
security-review | 安全性 vs 可維護性 — 在相關時兩者皆用 |
tdd-workflow | 測試通過 ≠ 設計健康 — 在重構後檢查分數 |
情境提示： ECC 建議保持低 MCP 數量。在進行實質編輯時啟用 codescene；不需要時則停用。
相關技能
coding-standards— 基本慣例plankton-code-quality— 寫入時的 lint/格式化鉤子verification-loop— 建置/測試/lint 關卡tdd-workflow— 測試先行開發security-review— 安全性檢查清單documentation-lookup— 透過 Context7 查詢函式庫文件（正交功能）