Code Health 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 安裝/同步時使用 ECC_DISABLED_MCPS=codescene,... 將其排除。
憑證： 不包含隨附的 Token。請自行設定 CS_ACCESS_TOKEN（請參閱上游儲存庫中的 getting-a-personal-access-token.md）。切勿將 Token 提交至儲存庫。
工具讀取的內容： 呼叫時，工具會分析本地儲存庫中您指定的檔案和 git 狀態（您傳入的路徑，以及 analyze_change_set 的分支上下文）。它們不會自行執行。對於獨立模式，請遵循上游隱私文件：codescene-mcp-server README 和 CodeScene 政策。請勿將此技能用於您不希望被分析的機密、憑證或路徑。
如果 MCP 無法使用（離線、Token 錯誤、伺服器崩潰）： 請勿自行編造 Code Health 分數。告知使用者該檢查已被跳過。僅在獲得使用者明確同意後才繼續。當 MCP 無法使用時，建議使用 lint/測試/驗證循環作為關卡。一旦伺服器重新連線，再重新啟用檢查。
使用時機
- 使用者要求審查程式碼品質、重構檔案，或檢查 AI 更改是否降低了可維護性
- 在編輯熱點、遺留模組或不熟悉的檔案之前
- 在需要可維護性保護的提交或拉取請求之前
- 在大型代理產出差異之後——驗證 Code Health 沒有回歸
- 與
verification-loop、tdd-workflow或/quality-gate搭配使用，作為結構性檢查（非測試/lint 的替代品）
啟用時機
與上述使用時機相同——此標題是 ECC 用於技能自動啟動的依據。
運作方式
1. 連接 MCP 伺服器
將 mcp-configs/mcp-servers.json 中的 codescene 項目複製到您的 harness 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 中。
Token 設定在 upstream 儲存庫中已有文件說明（連結如上）。對於下面列出的四個工具，獨立模式不需要付費的 CodeScene 平台帳戶。在依賴分數之前，請重新啟動會話並確認 codescene 伺服器已連線。
2. 僅呼叫獨立工具
| 工具 | 使用時機 |
|---|---|
code_health_review | 在修改檔案之前進行完整的結構性分析 |
code_health_score | 每次變更後快速取得數值分數（差異檢查） |
pre_commit_code_health_safeguard | 阻止引入 Code Health 回歸的提交 |
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
結果：Code Health 4.82 → 9.1（僅使用免費獨立 Token）。
範例：AGENTS.md 強制區塊
貼入專案 AGENTS.md 或 CLAUDE.md：
## Code Health (CodeScene MCP)
修改任何檔案前：執行 `code_health_review`，記錄分數和問題。
- 分數低於 5：有問題的範圍——嚴格限定變更範圍。
- 分數 5–7：警告範圍——不做廣泛重構。
每次變更後：執行 `code_health_score` 以驗證差異。
- 如果分數回歸：在繼續前修復；如果分數下降，切勿宣稱完成。
每次提交前：執行 `pre_commit_code_health_safeguard`。
PR 前：執行 `analyze_change_set`。
範例：反模式 vs 正確循環
# 錯誤：先編輯，後檢查
[未使用 code_health_review 的大型重構]
# 錯誤：忽略分數下降
"測試通過" → 在 Code Health 降低的情況下將任務標記為完成
# 錯誤：對紅色分數檔案（低於 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 查詢函式庫文件（正交功能）