code-quality

name	code-quality
description	務實的編碼標準與程式碼審查指南。涵蓋命名、函式、反模式、審查清單及 AI 特定的審查模式。取代 clean-code + code-review-checklist。
allowed-tools	Read, Write, Edit, Glob, Grep
version	1
priority	CRITICAL

程式碼品質 — 標準與審查

關鍵技能 — 保持簡潔、直接、以解決方案為導向。

---

核心原則

原則	規則
SRP	單一職責 — 每個函式/類別只做一件事
DRY	不要重複自己 — 提取重複，重用
KISS	保持簡單 — 最簡單且能運作的方案
YAGNI	你不會需要它 — 不建置未使用的功能
童子軍	讓程式碼比你發現時更乾淨

---

命名規則

元素	慣例
變數	揭示意圖：userCount 而非 n
函式	動詞 + 名詞：getUserById() 而非 user()
布林值	問句形式：isActive、hasPermission、canEdit
常數	SCREAMING_SNAKE：MAX_RETRY_COUNT

規則： 如果你需要註解來解釋名稱，那就重新命名它。

---

函式規則

規則	說明
小	最多 20 行，理想 5-10 行
一件事	做一件事，做好它
一個層級	每個函式一個抽象層級
少參數	最多 3 個參數，偏好 0-2 個
無副作用	不意外地修改輸入

---

程式碼結構

模式	應用
守衛子句	邊界案例提前回傳
扁平 > 巢狀	避免深層巢狀（最多 2 層）
組合	小函式組合在一起
共置	保持相關程式碼靠近

---

程式碼審查清單

正確性

• 程式碼做了該做的事
• 邊界案例已處理
• 錯誤處理到位
• 沒有明顯的 bug

安全性

• 輸入已驗證和清理
• 沒有 SQL/NoSQL 注入漏洞
• 沒有 XSS 或 CSRF 漏洞
• 沒有寫死的秘密或敏感憑證
• AI 特定： 防護 Prompt 注入（如適用）
• AI 特定： 輸出在用於關鍵接收點前已清理

效能

• 沒有 N+1 查詢
• 沒有不必要的迴圈
• 適當的快取
• 已考慮打包大小影響

測試

• 新程式碼有單元測試
• 邊界案例已測試
• 測試可讀且可維護

文件

• 複雜邏輯有註解
• 公開 API 已記錄
• README 已更新（如需要）

---

AI 與 LLM 審查模式（2025）

邏輯與幻覺

• 思維鏈： 邏輯是否遵循可驗證的路徑？
• 邊界案例： AI 是否考慮了空狀態、逾時和部分失敗？
• 外部狀態： 程式碼是否對檔案系統或網路做了安全的假設？

Prompt 工程審查

// ❌ 程式碼中模糊的 prompt
const response = await ai.generate(userInput);

// ✅ 結構化且安全的 prompt
const response = await ai.generate({
  system: "You are a specialized parser...",
  input: sanitize(userInput),
  schema: ResponseSchema
});

---

反模式

❌ 模式	✅ 修復
每行都註解	刪除顯而易見的註解
為一行程式碼建立 helper	內聯程式碼
為 2 個物件建立 Factory	直接實例化
只有 1 個函式的 utils.ts	把程式碼放在使用處
"首先我們匯入..."	直接寫程式碼
深層巢狀	守衛子句
魔術數字	具名常數
上帝函式	按職責拆分
any 型別	正確的型別
過長函式（100+ 行）	小而專注的函式

---

審查評論指南

// 阻擋性問題使用 🔴
🔴 BLOCKING: 此處有 SQL 注入漏洞

// 重要建議使用 🟡
🟡 SUGGESTION: 考慮使用 useMemo 提升效能

// 小建議使用 🟢
🟢 NIT: 偏好 const 而非 let 用於不可變變數

// 問題使用 ❓
❓ QUESTION: 如果 user 為 null 這裡會怎樣？

---

AI 編碼風格

情境	行動
使用者要求功能	直接撰寫
使用者回報 bug	修復它，不要解釋
沒有明確需求	詢問，不要假設

---

🔴 編輯任何檔案前（先思考！）

問題	原因
什麼匯入了這個檔案？	它們可能會壞掉
這個檔案匯入了什麼？	介面變更
什麼測試覆蓋了這裡？	測試可能會失敗
這是共用元件嗎？	多處受影響

🔴 規則： 在同一個任務中編輯該檔案 + 所有相依的檔案。 🔴 絕不留下壞掉的匯入或遺漏的更新。

---

🔴 完成前自我檢查（強制）

檢查	問題
✅ 目標達成？	我做了使用者要求的事嗎？
✅ 檔案已編輯？	我修改了所有必要的檔案嗎？
✅ 程式碼能用？	我測試/驗證了變更嗎？
✅ 沒有錯誤？	Lint 和 TypeScript 通過了嗎？
✅ 沒有遺漏？	有邊界案例被遺漏嗎？

🔴 規則： 如果任何檢查失敗，在完成前修復它。

---

總結

做	不做
直接寫程式碼	寫教學
讓程式碼自我文件化	加上顯而易見的註解
立即修復 bug	先解釋修復方法
內聯小東西	建立不必要的檔案
清楚地命名	使用縮寫
保持函式小	撰寫 100+ 行的函式

記住：使用者要的是能用的程式碼，不是程式設計課。