反模式技能 — 交付真實的程式碼,而不是裝飾品
此技能用於檢測並防止最常見的反模式,這些反模式會讓軟體看起來未完成或不專業。
禁止的反模式(零容忍)
UI/UX 反模式
❌ 禁止使用:
- 「即將推出」的章節或標籤
- 非功能性的按鈕(必須可用或移除)
- 未連結任何提交動作的表單
- 生產環境元件中的硬編碼假資料
- 假裝是動態的靜態表格
- 無效的連結(href="#")
- 「施工中」的橫幅
- 永遠設定為 false 的功能旗標
- 沒有清楚說明的已停用輸入框
- 沒有提供有用訊息的空狀態
- 實際上沒有分頁功能的分頁元件
- 實際上沒有搜尋功能的搜尋欄
- 總是返回相同結果的篩選器
- 當使用者要求「一個網站」時,只給出單一登陸頁面(必須是多頁面)
- 在撰寫 CSS 之前沒有定義色彩調色板
- 隨機的十六進位顏色,缺乏有文件的設計系統
- 跨頁面顏色不一致(不同的藍色、不同的間距)
- 網站中任何地方使用表情符號(請使用 Lucide/Heroicons/Phosphor 的 SVG 圖示)
- 區塊之間彼此緊貼(內容區塊之間沒有間距)
- 頁尾直接貼在內容上方的區塊(沒有呼吸空間)
- 導覽列有超過 7 個頂層項目(顯得雜亂且壓迫)
- 服務項目沒有個別的詳細頁面(只有 /services,沒有 /services/web-design)
- 產品項目沒有個別的詳細頁面(只有 /products,沒有 /products/[slug])
- 通用的服務描述(每個服務只有 2-3 行是不夠的)
✅ 必須符合:
- 每個可見的按鈕都觸發一個實際的事件處理器,否則就移除
- 每個表單都有連接到 API 呼叫的真實 onSubmit 處理器
- 每個列表都從真實的資料來源載入,並顯示載入狀態
- 每個連結都導航到真實的目的地
- 空狀態說明原因並建議下一個動作
- 錯誤狀態顯示來自伺服器的真實錯誤訊息
- 載入狀態在實際的非同步操作期間出現
- 多頁面網站包含獨立路由(首頁、關於、服務、聯絡我們、產品)
- 專業的 6 色調色板(--color-primary, secondary, accent, bg, surface, text)
- 所有頁面一致的設計系統
- 零表情符號 — 使用 SVG 圖示(Lucide, Heroicons, Phosphor)
- 區塊間距:區塊之間最少 80px 內距
- 頁尾:最少 128px 上方內距(絕不觸及上方內容)
- 導覽列:最多 7 個項目,群組使用下拉選單,次要連結放在頁尾
- 服務:列表頁面 + 每個服務的個別詳細頁面
- 產品:列表頁面 + 每個產品的個別詳細頁面
- 每個服務詳細頁面需包含:描述、流程、交付物、定價、常見問題、行動呼籲
- 每個產品詳細頁面需包含:圖庫、規格、定價、評論、相關產品
網站架構反模式
❌ 禁止使用(當使用者說「建立一個網站」時):
- 只建立一個 index.html 檔案
- 將所有內容放在一個可滾動的頁面中
- 使用錨點連結(#about, #services)而不是獨立頁面
- 當它只是一個登陸頁面時,稱之為「網站」
- 各區塊/頁面之間沒有導覽選單
- 沒有跨頁面共用的頁首/頁尾
- 每個頁面沒有獨特的中繼標題/描述
✅ 必須符合:
- 每個區塊都有獨立的路由/頁面(例如 /about, /services, /contact)
- 連結所有頁面的導覽選單
- 共用的頁首 + 頁尾元件
- 每個頁面都有獨特的 <title> 和 <meta description>
- 所有頁面之間一致的色彩調色板和排版
- 任何「網站」請求最少要有 5 個頁面(首頁、關於、服務、產品/作品集、聯絡我們)
程式碼反模式
❌ 禁止使用:
- return []; // TODO: implement
- throw new Error('Not implemented');
- // placeholder
- 假裝是 API 回應的硬編碼陣列
- 空的函式本體
- 默默地吞掉錯誤的 catch 區塊
- 生產環境中被註解掉的程式碼
- 沒有命名常數的魔術數字
- 複製貼上的程式碼(違反 DRY 原則)
- 上帝函式(超過 100 行)
- 深度巢狀的回呼(超過 3 層)
- 在迴圈中產生的 N+1 資料庫查詢
✅ 必須符合:
- 每個函式都有真實、可運作的實作
- 每個錯誤都妥善處理並提供使用者回饋
- 常數有命名且有文件說明
- 程式碼符合 DRY 原則 — 將共用邏輯抽出
- 函式功能單一且少於 40 行
N+1 查詢檢測
❌ 禁止使用(N+1):
// 這會為每個使用者觸發 1 次查詢 = N+1 問題
for (const user of users) {
const orders = await db.query('SELECT * FROM orders WHERE user_id = ?', [user.id]);
}
✅ 必須使用(批次):
// 這總共只觸發 1 次查詢
const userIds = users.map(u => u.id);
const orders = await db.query(
'SELECT * FROM orders WHERE user_id IN (?)',
[userIds]
);
// 然後在記憶體中分組
const ordersByUser = groupBy(orders, 'user_id');
SQL 反模式
❌ 禁止使用:
SELECT * FROM users -- 不使用 SELECT *
WHERE name LIKE '%" + input + "%' -- SQL 注入
ORDER BY RAND() -- 效能殺手
HAVING COUNT(*) > 0 -- 改用 WHERE
WHERE YEAR(created_at) = 2024 -- 破壞索引使用
✅ 必須使用:
SELECT id, name, email FROM users -- 明確指定欄位
WHERE name LIKE ? -- 參數化查詢
ORDER BY id DESC LIMIT 20 -- 確定性排序
WHERE created_at >= '2024-01-01' -- 對索引友善
AND created_at < '2025-01-01'
驗證檢查清單
在任何交付物被標記為完成之前:
通用項目
- 任何地方都沒有「即將推出」或「施工中」
- 所有按鈕皆有功能或已移除
- 所有表單都提交到真實的端點
- 所有列表都從真實資料來源載入
- 生產環境路徑中沒有硬編碼的展示資料
- 沒有 N+1 查詢(檢查每個包含查詢的迴圈)
- 沒有未關聯議題的 TODO 註解
- 錯誤狀態處理真實的錯誤
- 載入狀態在實際操作期間顯示
設計與 UI 反模式
- 網站中任何地方零表情符號(僅使用 SVG 圖示)
- 區塊之間最少有 80px 內距(不彼此緊貼)
- 頁尾最少有 128px 上方內距(不貼在內容上)
- 主導覽列最多 7 個頂層項目
- 次要連結放在頁尾,而非主導覽列
- 服務項目有各自的詳細頁面(不僅是列表頁)
- 產品項目有各自的詳細頁面(不僅是列表頁)
- 每個服務詳細頁面包含:描述、流程、交付物、行動呼籲
- 每個產品詳細頁面包含:圖庫、規格、定價、評論
- 交替的區塊背景以提供視覺區隔
SEO 反模式(適用於網站專案)
- 每個頁面都有獨特的
<title>和<meta name="description"> - 每個頁面都有 Open Graph 標籤(og:title, og:description, og:image)
- 每個頁面都有 JSON-LD 結構化資料(
<script type="application/ld+json">) - 非首頁的每個頁面都有 BreadcrumbList 結構化資料
- 沒有重複的 JSON-LD 區塊(改用
@id引用) - 沒有缺少
robots.txt或sitemap.xml - 沒有缺少
alt文字的圖片 - 每個頁面都有標準網址(canonical URL)
- 沒有缺少
<html lang="xx">屬性 - 每個頁面不超過一個
<h1>
何時不使用
在以下情況請勿使用此技能:
- 進行一般程式碼品質審查(請使用 code-review 技能進行更廣泛的分析)
- 設計資料庫綱要(請使用 database-design 技能進行綱要規劃)
- 撰寫應用程式商業邏輯(請使用 domain-driven 技能完成完整模組)
- 審查 API 端點實作(請使用 api-design 技能處理端點模式)
- 執行安全稽核(請使用 security-auditor 技能進行漏洞分析)
- 分析部署配置(請使用 deployment 技能處理 CI/CD 管線)
- 審查 Git 工作流程或版本控制(請使用 git-workflow 技能處理分支/提交)
- 撰寫 SQL 查詢(請使用 sql-best-practices 技能進行查詢最佳化)
- 設計多頁面網站佈局(請使用 design-system 技能處理專業 UI/UX)
- 審查現有程式碼以進行重構(請使用 refactoring 技能進行安全轉換)