# Recommendation Principles

產出建議時的硬性規則。規範「架構建議 / 效能優化建議 / 安全性強化建議」段落的內容邊界。報告若違反任一條，應**直接移除該建議**而非保留。

## 產出前必須驗證

| 項目 | 具體檢查 |
|---|---|
| **假設驗證** | 建議涉及的函式 / 模組 / 抽象層 **必須真實存在於當前程式碼**。禁止基於「可能有」「通常會有」「未來可能加入」的結構提建議。 |
| **根因判斷** | 所提問題必須在 `issues` JSON 中有對應條目，或能明確指出來源檔案與行號。禁止提出「整體架構需重構」這類無錨點建議。 |
| **可執行性** | 每條建議附 before/after 程式碼或具體檔案清單。禁止「建議使用更好的模式 / 更清晰的結構」這類模糊語言。 |

## 禁止產出的建議類型

| 反模式 | 說明 | 例外 |
|---|---|---|
| **包裝既有抽象** | 既有 `dataclass` / `NamedTuple` / `TypedDict` / `Enum` 已是 factory 或常數集合，禁止再建議 `make_X()` / `build_X()` helper | 該型別初始化有**超過 3 個欄位需計算或驗證**時才考慮 |
| **補文件為目的** | 禁止「為所有函式補 docstring」「補齊模組說明」這類規模性建議 | 函式隱含非顯而易見的 WHY（隱藏約束、workaround、reference issue）才逐一列出 |
| **預測性優化** | 禁止「未來專案規模增大時」「若支援更多語言時」「為日後擴充預留」這類建議（快取、增量分析、plugin 架構、抽象層） | 觀察到的 metric 已超標（例：`total_lines > 100000` 且 `max_function_length > 200`）才提 |
| **裝飾性重構** | 禁止「拆成更多小函式提高可讀性」「統一輸出契約」當目前已一致時 | 有具體指標佐證（巢狀 > 3、行數 > 50、同函式承擔 3 種以上責任）才提 |
| **測試基礎建設擴張** | 禁止泛泛建議「補測試」；若專案已有測試框架才提具體 fixture 建議 | 偵測到 heuristic 規則檔（regex / pattern matching）且無對應測試，可提「對該檔案補真/假陽性 fixture」 |
| **嚴重度膨脹** | Heuristic 偵測（pattern / entropy）一律標註「需人工確認」，不得升級為 Critical 以吸引注意 | AST 層級確定性偵測才用 Critical / High |

## 零建議是合法輸出

若分析結果 `issue_counts` 全為 0 且未觀察到具體超標 metric，**架構建議 / 效能 / 安全** 三段允許各自寫「目前未觀察到需處理事項」。禁止為了填滿段落製造建議。

**進一步**：若三段**皆**為「未觀察到需處理事項」，觸發 No-Op 條件 → **不產檔**（見 SKILL.md「No-Op 條件」）。

## 自我檢查（產出報告前必跑一次）

1. 每條建議是否指向**實際存在**的檔案 / 函式 / 行號？
2. 每條建議移除後，專案是否真的變差？若刪掉沒有可觀察的損失，就是廢話。
3. 建議是否用到「未來 / 可能 / 若」這類推測性詞彙？用到即重寫或刪除。
4. 建議是否只是重述既有 dataclass / enum / 標準庫能力？是即刪除。
