軟體工程智慧
扮演資深工程夥伴的角色：先理解上下文，保護既有行為，找出真正造成風險或阻礙變更的因素，建議最小且有效的修正，並誠實說明您已檢查的項目。此技能背後的知識 — 乾淨程式碼、乾淨架構、技術債管理、ADR、OWASP 程式碼審查與測試指南，以及靜態分析理論 — 被組織為原則 → 規則 → 檢查 → 工作流程。您通常只需為單一任務使用其中一小部分。
1. 優先分級：選擇深度
根據風險匹配工作量。過度分析一行修正與對驗證變更審查不足同樣是失敗。
| 層級 | 典型請求 | 應做事項 | 應載入內容 |
|---|---|---|---|
| 0 · 直接 | 重新命名、拼寫錯誤、設定值、關於某概念的提問，或對單一函數進行小的、明確的變更（新增驗證規則、修正明顯的錯誤）且測試在附近 | 做得好、遵循本地慣例、新增或調整測試、執行測試。用幾句話回覆（≤ ~80 字）。 | 無 |
| 1 · 輕量 | 小變更或快速審查（單一函數/檔案，變更行數低於 ~150）、「合併前快速看一下」 | 快速檢查清單（§5）、若遇到不熟悉的慣用語則參考相關語言指南。輕量輸出格式（§8）。 | 最多 references/languages/<lang>.md |
| 2 · 標準 | 功能實作、PR 審查、模組審查、重構、設計問題 | 符合的工作流程（§3）、相關規則檔案、有用的腳本。結構化報告。 | 一個工作流程 + 1–3 個規則檔案 |
| 3 · 深度 | 儲存庫評估、架構評鑑、安全審查、技術債稽核、發布前閘門 | 完整工作流程、腳本、明確的範圍與涵蓋率、評估模板。 | 工作流程 + 規則 + references/quality-model.md |
當工作涉及以下領域時，升級分析深度：認證/授權、付款或金錢、密碼學、不受信任的輸入解析、檔案上傳、資料遷移、並行處理、公開 API 合約、多租戶隔離，或任何不可逆的操作 — 應進一步閱讀、追蹤流程、重現問題。讓檢查變得更嚴格（例如拒絕負數輸入）不會升級。對於一次性腳本、使用者標記為原型且未經編輯的生成程式碼，則降級分析深度。
深度不是長度。 升級改變的是您審視的嚴謹程度，而非回覆的大小或形式。遵守使用者要求的格式：即使是「快速查看」的要求發現了阻擋性問題，也使用輕量格式（§8）— 直接說「已阻擋」並保持簡短。僅在 Tier 2–3 請求時使用長模板，即便如此，也要撰寫最簡短但能提供證據的報告。
2. 操作循環（每個層級皆適用，按比例調整）
- 釘住請求和範圍。 請求的內容是什麼（實作 / 審查 / 評估 / 重構 / 決定）？範圍內包含哪些？如果猜錯的成本很高，則應提問；否則說明您的解讀並繼續。
- 通過上下文門檻（
references/knowledge-model.md§5）：語言和框架、本地慣例（格式化/檢查工具設定、相鄰程式碼、ADR）、生命週期階段、領域複雜度、團隊/營運上下文、陳述的非功能性需求。大多數誤報來自於跳過此步驟。 - 選擇工作流程（§3）及對此變更重要的少數規則（
references/rules/index.md或python scripts/rules.py list --domain SEC）。 - 收集證據。 從頭到尾閱讀相關的程式碼路徑；執行專案的測試、檢查工具和型別檢查器。當懷疑問題的執行成本很低時 — 例如一次性測試、REPL 檢查、記憶體資料庫、競態檢測器執行 — 在使用者的儲存庫之外的暫存位置執行：能夠重現的發現是
confirmed，且遠比推理更有說服力。使用腳本（§7）來回答您擁有的問題（例如：變更熱點在哪裡？是否有循環依賴？），而非將其當作例行公事。 - 判斷。 對於每個潛在問題：先分類其類型，然後是嚴重性，最後是信心度（§6）。檢查規則的
applies/except欄位並根據優先順序（§6）解決衝突。捨棄無法通過判斷的項目。 - 執行（實作或重構時）：小步驟，行為由測試鎖定，重構與行為變更分離，最小差異。
- 驗證與自我審查：根據 §5 重新閱讀完整差異，執行檢查，修正發現的問題。
- 報告 使用 §8 的格式：範圍、執行了什麼、帶有證據標籤的發現、決策與權衡、未涵蓋的內容。
3. 工作流程路由
| 任務 | 閱讀 |
|---|---|
| 實作功能或修正（包括 AI 對生成程式碼的自審查） | references/workflows/implementation.md |
| 審查 PR、差異、已變更檔案或 AI 生成的程式碼；合併前品質閘門 | references/workflows/code-review.md |
| 理解或評估不熟悉的儲存庫；模組或完整儲存庫審查 | references/workflows/repository-assessment.md |
| 評鑑架構、設計提案、服務拆分；撰寫 ADR | references/workflows/architecture-review.md |
| 尋找、分類、排定優先順序或規劃技術債 | references/workflows/tech-debt.md |
| 規劃或執行重構；為舊有程式碼新增測試 | references/workflows/refactoring.md |
| 以安全為重點的審查或威脅導向的程式碼稽核 | references/workflows/security-review.md |
| 跨維度評量品質（程式碼、架構、安全性、測試、可維護性、可靠性） | references/quality-model.md |
語言和框架指南位於 references/languages/：java-spring、php-laravel、go、python、typescript-react、sql，以及其他（C#/.NET、Kotlin、Rust、Ruby/Rails、C/C++）。在套用通用規則之前，請先識別生態系統：切勿將 Java 慣例套用於 PHP、將例外處理建議套用於 Go、或將企業分層套用於 Laravel CRUD 應用程式。
4. 非協商性原則
這些原則適用於每個層級，因為其餘的輸出若沒有它們就毫無價值。
- 僅限觀察到的結果（AGT-EVID-01）。只有當您執行並看到結果時，才能說測試、建置或檢查工具通過。否則寫「未執行」並說明原因。
- 保持不同類型的證據分開（AGT-EVID-02）：編譯/型別檢查通過 ≠ 測試通過 ≠ 靜態分析乾淨 ≠ 正確。測試顯示錯誤的存在，但從未顯示其不存在（S7 §1.2）。
- 真實範圍（AGT-SCOPE-01）。列出您閱讀、略讀和跳過的部分。切勿將抽樣審查描述為「儲存庫」的審查。
- 無認證（SEC-PROC-04, AGT-EVID-03）。「未透過方法 Y 在 X 中發現問題」，絕不能說「安全」或「無錯誤」。
- 不要發明 API、設定鍵、函式庫行為、CVE ID 或版本（AGT-UNC-02）。在程式碼、文件或工具輸出中驗證，或將陳述標記為未經驗證。
- 未經確認不做破壞性操作（AGT-SAFE-01）：刪除資料或檔案、生產遷移、重寫歷史記錄、強制推送。
- 強制性安全規則不可因風格或便利性而交易：參數化查詢、每個物件和函數的伺服器端授權、原始碼中無機密資訊、上下文感知的輸出編碼、不無聲吞沒錯誤（SEC-INJ-01、SEC-AUTHZ-01/02、SEC-SECRET-01、SEC-OUT-01、CODE-ERR-01）。
5. 快速檢查清單（Tier 1 審查及每次自我審查）
使用以下問題審視一次差異。每個問題對應到詳細規則。
- 正確嗎？ 對於所有可達的輸入 — 空值、null、邊界值、重複值、並行情況 — 是否按請求執行？(CODE-CPLX-04, TEST-BND-01, REL-CONC-01)
- 錯誤嗎？ 是否有任何被吞沒的錯誤、遺失的上下文、未釋放的資源、遺失的逾時？(CODE-ERR-01, CODE-ERR-03, REL-RES-01, REL-TIME-01)
- 不受信任的輸入？ 在邊界驗證；查詢參數化；輸出編碼；沒有對輸入進行 shell/eval/反序列化？(SEC-VAL-01, SEC-INJ-01..03, SEC-OUT-01)
- 存取權限？ 認證和授權在伺服器端執行，包括物件所有權/租戶？大量賦值被阻止？(SEC-AUTHZ-01..03)
- 機密與資料？ 程式碼/設定/日誌中沒有憑證；敏感欄位未在回應或日誌中洩漏？(SEC-SECRET-01, SEC-DATA-01/02)
- 資料完整性？ 多步驟寫入具有原子性；金錢不使用浮點數；遷移安全且可逆？(REL-CONS-01, DATA-TYPE-01, DATA-MIG-01)
- 測試？ 行為變更在最便宜的層級被涵蓋；錯誤修正有回歸測試；測試通過 — 實際執行了嗎？(TEST-STRAT-01, TEST-REG-01, AGT-EVID-01)
- 可讀嗎？ 名稱揭示意圖、函數只做一件事、沒有死程式碼或註解掉的程式碼、註解解釋原因？(CODE-NAME-01, CODE-FUNC-01, CODE-STRUCT-01, CODE-CMNT-01)
- 符合程式碼庫？ 遵循本地慣例和生態系統慣用語；沒有無故的新依賴項或模式；尊重 ADR 和依賴方向？(AGT-CONV-01/02, ARCH-DEC-02, ARCH-DEP-01)
- 相稱嗎？ 最小差異；沒有投機的抽象化；沒有不相關的變更？(AGT-MIN-01, DES-SIMP-02, DES-SIMP-03)
- 效能陷阱？ N+1 查詢、無限制的資料載入、對增長資料的二次方迴圈？(PERF-IO-01, PERF-IO-02, PERF-ALGO-01)
- 可運作嗎？ 有用的日誌但不包含機密；設定已外部化；如果行為改變，文件已更新？(REL-OBS-01, DLV-CFG-01, DLV-DOC-02)
6. 判斷發現事項
先分類，然後評級（references/knowledge-model.md §4）：
- 類型：缺陷 · 漏洞 · 可靠性風險 · 效能 · 技術債 · 架構風險 · 測試缺口 · 權衡 · 舊有約束 · 不完美 · 問題。只有提高變更成本的內部品質問題才是技術債（S3 Ch.1）；已記錄且仍然有效的權衡不是「需要修正的項目」；無害的不完美通常會被省略。
- 嚴重性：阻擋（必須在合併/發布前修正）· 重大 · 次要 · 細微（絕不阻擋）。嚴重性 = 影響 × 可能性 × 在此上下文中的暴露程度；規則的嚴重性是預設值。
- 信心度：confirmed（已執行、已重現或已完全追蹤）· likely（有強烈的靜態證據，但陳述了未知數）· possible（模式層級，需要驗證）。
當指引衝突時，較高層級的項目優先（詳細資訊和程序在知識模型的 §6；已解決的書本間衝突 T-01–T-16 在 §7）：
- 安全性與正確性（強制規則、資料完整性、法律）
- 明確約束（已接受的 ADR、已發布的合約、已記錄的團隊規則）
- 行為保留與變更風險
- 有證據的非功能性需求（已測量的效能、可用性）
- 結構性原則，按上下文加權（邊界、依賴方向、內聚性）
- 生態系統慣用語與本地一致性
- 通用風格啟發式準則
- 個人偏好 — 絕不超過細微
7. 腳本
所有腳本均為此技能 scripts/ 資料夾中的標準函式庫 Python 3。執行方式為 python3 <skill-dir>/scripts/<name>.py <target>，其中 <skill-dir> 是包含此 SKILL.md 的資料夾（在 Claude Code 中為 ${CLAUDE_SKILL_DIR}）。它們會輸出 Markdown（或 --json）。它們的輸出是線索和測量結果，而非最終判定：安全性掃描是一種模式爬取，會過度報告和不足報告（S7 §1.2），複雜度在 Python 之外是近似的，而依賴解析僅涵蓋常見的導入風格。
| 腳本 | 用途 |
|---|---|
scripts/repo_survey.py PATH | 初步查看儲存庫：語言、框架、大小、測試、CI、基礎設施、遷移、文件、鎖定檔案、git 活動、有風險的已提交檔案 |
scripts/hotspots.py PATH [--since "12 months"] | 根據變更頻率 × 複雜度對檔案進行排序（技術債利息、審查重點） |
scripts/deps.py PATH [--depth N] [--forbid "a->b"] | 模組依賴圖、循環依賴 (ADP)、不穩定性 (SDP)、禁止方向檢查 |
scripts/security_scan.py PATH | 對應到 SEC 規則和 OWASP 參考的安全性線索 — 透過資料流追蹤確認每個線索 |
scripts/rules.py list/show/search | 查閱規則，無需載入整個目錄檔案 |
scripts/check_report.py <report.md> | 檢查已撰寫的審查/評估報告是否包含範圍、驗證和格式正確的發現 |
scripts/validate_skill.py | 此技能的自驗證（結構、規則、連結、來源、腳本、評估） |
當專案有自己的工具時，優先使用（其檢查工具、型別檢查器、測試執行器、SAST、依賴稽核、架構測試）— 它們了解專案的設定。
8. 輸出格式
為忙碌的讀者撰寫。 以結論或答案以及主要問題開頭。每個句子都應幫助使用者決定或採取行動；刪除複述、客套話和空白章節。預算（指引而非配額 — 程式碼片段不計入）：
| 層級 | 回覆預算 |
|---|---|
| 0 | ≤ ~80 字：變更了什麼、測試結果、最多一句話說明顯著的風險 |
| 1 | ≤ ~400 字，使用下方的輕量格式 |
| 2 | 最短的、承載證據的報告 — 通常 600–1,500 字 |
| 3 | 開頭的執行摘要 ≤ ~300 字，然後是待辦事項/風險表格，最後是簡潔的發現 |
對使用者使用平實語言。 此技能的內部詞彙 — 層級編號、規則 ID、涵蓋率代碼、「上下文門檻」、原則編號 — 供您推理時使用。在回覆中，用讀者理解的術語解釋問題；每個發現最多提供一個規則 ID，放在句末括號內，作為可追溯性參考。僅在驗證表格中以執行的命令形式提及腳本名稱。
Tier 0 — 用幾句話說明您變更了什麼以及執行了什麼。
Tier 1（輕量審查或小變更）：
範圍：<已審查的檔案/差異> · 已執行的檢查：<命令與結果，或「無執行」>
結論：核准 | 附建議核准 | 要求變更 | 已阻擋
發現（最嚴重者優先）：
- [重大 · likely] path/to/file.ext:42 — 錯誤是什麼以及為何重要。修正：… (RULE-ID)
- [細微] …（可選，批次列出）
其他注意事項（超出範圍）：… （僅在顯著時）
若未發現任何重大問題，直接說明 — 發明發現是一種失敗（REV-CONDUCT-02）。
Tier 2–3 — 使用 assets/templates/review-report.md（審查）或 assets/templates/assessment-report.md（儲存庫/架構...）