評代碼庫

多階深度代碼庫評審，附嚴重度等級與結構化輸出。於單一協調之過程中涵蓋架構、安全、代碼品質與 UX／無障礙。生按優先級排之發現表，可直接藉 create-github-issues 技能轉為 GitHub 議題。

適用時機

• 全項目或子項目評審（非 PR 範圍）
• 新代碼庫上手——建構心智模型，知何存在與何需注意
• 持續開發後之定期健檢
• 跨架構、安全、代碼品質與 UX 之發布前品質閘
• 輸出宜直接饋議題建立或衝刺計畫時

輸入

• 必要：target_path ——擬評之代碼庫或子項目根目錄
• 選擇性：
  • scope ——擬跑之階段：full（預設）、security、architecture、quality、ux
  • output_format —— findings（僅表）、report（敘述）、both（預設）
  • severity_threshold ——納入之最低嚴重度：LOW（預設）、MEDIUM、HIGH、CRITICAL

步驟

步驟一：盤點

清點代碼庫以立範圍並識評審標的。

1. 按語言／類型計文件數：find target_path -type f | sort by extension
2. 度每語言之總行數
3. 識測試目錄並估測試覆蓋（有測試之文件 vs 無測試之文件）
4. 檢依賴狀態：鎖文件存在、過時依賴、已知漏洞
5. 注建構系統、CI／CD 配置與文件狀態
6. 將盤點記為報告之開段

預期： 事實清冊——文件數、語言、測試之有無、依賴健康。尚無判斷。

失敗時： 若目標路徑為空或不可達，停而報。若特定子目錄不可達，註之並以可得者續。

步驟二：架構評審

評結構健康：耦合、重複、資料流、關注點分離。

1. 繪模組／目錄結構並識主要架構模式
2. 檢代碼重複——跨文件之重複邏輯、複貼模式
3. 評耦合——單一功能修改須改幾文件
4. 評資料流——層間（UI、邏輯、資料）有清界否？
5. 識死代碼、未用之匯出與孤兒文件
6. 檢一致模式——代碼庫遵其自身慣例否？
7. 為每發現評：CRITICAL、HIGH、MEDIUM 或 LOW

預期： 含嚴重度等級與文件引用之架構發現清單。常見發現：模式分派重複、缺抽象層、循環依賴。

失敗時： 若代碼庫過小不宜架構評審（< 5 文件），註之並跳至步驟三。架構評審需足夠之代碼以有結構。

步驟三：安全稽核

識安全漏洞與防禦編碼之缺。

1. 掃注入向量：HTML 注入（innerHTML）、SQL 注入、命令注入
2. 檢認證與授權模式（若適用）
3. 評錯誤處理——錯被無聲吞否？錯訊洩內部否？
4. 對已知 CVE 稽核依賴版本
5. 檢硬編之機密、API 鑰或憑證
6. 評 Docker／容器安全：root 用戶、暴露之埠、構建機密
7. 檢 localStorage／sessionStorage 之敏感資料儲存
8. 為每發現評：CRITICAL、HIGH、MEDIUM 或 LOW

預期： 含嚴重度、受影響文件與補救指南之安全發現清單。CRITICAL 發現含注入漏洞與洩漏之機密。

失敗時： 若無安全相關之代碼存在（純文件項目），註之並跳至步驟四。

步驟四：代碼品質

評可維護性、可讀性與防禦編碼。

1. 識魔數與宜成具名常數之硬編值
2. 檢跨代碼庫之一致命名慣例
3. 找系統邊界缺輸入驗證
4. 評錯誤處理模式——一致否？提供有用訊息否？
5. 檢註解掉之代碼、TODO／FIXME 標記與未完之實作
6. 評測試品質——測試是測行為抑或實作細節？
7. 為每發現評：CRITICAL、HIGH、MEDIUM 或 LOW

預期： 聚焦可維護性之品質發現清單。常見發現：魔數、不一致模式、缺護衛。

失敗時： 若代碼庫為生成或縮小，註之並調期望。生成代碼有異於手寫代碼之品質標準。

步驟五：UX 與無障礙（若有前端）

評使用者體驗與無障礙合規。

1. 檢互動元素之 ARIA 角色、標籤與地標
2. 驗鍵盤導航——所有互動元素可藉 Tab 達否？
3. 測焦點管理——面板開／閉時焦點邏輯移否？
4. 檢響應式設計——於常見斷點測（320px、768px、1024px）
5. 驗色對比合 WCAG 2.1 AA 標準
6. 檢螢幕閱讀器相容——動態內容變更被宣告否？
7. 為每發現評：CRITICAL、HIGH、MEDIUM 或 LOW

預期： 含 WCAG 引用（適用時）之 UX／a11y 發現清單。若無前端存在，本步產「N/A——未測得前端代碼」。

失敗時： 若有前端代碼但不能渲染（缺構建步），靜態稽核源代碼並註執行時測試不可。

步驟六：發現綜合

將所有發現編入按優先級排之摘要。

1. 將各階發現併為單一表
2. 按嚴重度排序（CRITICAL 先，繼 HIGH、MEDIUM、LOW）
3. 每嚴重度內按主題（安全、架構、品質、UX）分組
4. 每發現含：嚴重度、階段、文件、一行描述、建議之修
5. 出考量修復間依賴之建議修復順
6. 摘要：按嚴重度之總發現數、前 3 優先、估之工作量

預期： 含 #、Severity、Phase、File(s)、Finding、Fix 欄之發現表。考量發現間依賴之修復順建議（如「加測試前先重構架構」）。

失敗時： 若無發現產出，此本身為發現——或代碼庫格外潔淨，或評審過淺。重檢至少一階作更深察。

驗證

• 所有所求之階段已完成（或明略並附理由）
• 每發現有嚴重度等級（CRITICAL／HIGH／MEDIUM／LOW）
• 每發現引至少一文件或目錄
• 發現表按嚴重度排序
• 修復順建議考量發現間之依賴
• 摘要含按嚴重度之總計
• 若 output_format 含 report，敘述段伴表

與 Rest 之尺度

評審階段之間，用 /rest 為關卡——尤於需異分析角度之第二至五階之間。關卡息（短、過渡）防一階之動量偏倚下一階。指南見 rest 技能之「Scaling Rest」段。

常見陷阱

• 煮海：評大代碼庫之每行產噪。聚焦高影響區：入口、安全邊界、架構接縫
• 嚴重度膨脹：非每發現皆 CRITICAL。將 CRITICAL 留予可利用之漏洞與資料喪失風險。多數架構問題為 MEDIUM
• 見木不見林：個別代碼品質問題重於系統模式。若魔數現於 20 文件，乃一架構發現而非 20 品質發現
• 略盤點：盤點（步驟一）似官僚但防評不存在之代碼或漏整目錄
• 階段滲流：架構評審中之安全發現，或安全稽核中之品質發現。為正確階段註之而非混關注——產更潔之發現表

相關技能

• security-audit-codebase — 評代碼庫之安全階段揭複雜漏洞時之深度安全稽核
• review-software-architecture — 對特定子系統之詳細架構評審
• review-ux-ui — 越第五階所涵之全面 UX／無障礙稽核
• review-pull-request — 對個別變更之 diff 範圍評審
• clean-codebase — 實作此評審所識之代碼品質修復
• create-github-issues — 將發現表轉為已追蹤之 GitHub 議題