Communitygithub.com

Omar-Obando/qwen-orchestrator

在程式碼交付前,自動偵測並防止硬編碼資料、非功能性的 UI 元素、佔位符程式碼、N+1 查詢及其他常見的開發反模式。

qwen-orchestrator 是什麼?

這個技能(Skill)專門用於在軟體開發過程中,自動檢測並阻止最常見的反模式,確保交付的程式碼是完整、專業且可運行的。它涵蓋了 UI/UX、網站架構、程式碼品質、SQL 查詢以及 N+1 效能問題等多個面向。對於開發者或使用 AI 代理(如 Claude Code、Cursor)的團隊來說,這個技能可以在生成或審查程式碼時,強制執行最佳實踐,例如禁止「即將推出」的佔位符、非功能性的按鈕、以及簡單的單頁式登陸頁面。該技能要求所有元件都必須有實際功能、所有表單都必須連接到真實的 API、所有列表都必須從真實資料來源載入,並且嚴格執行一致的設計系統和頁面數量。它支援任何能夠引用 Markdown 技能檔案的 AI 代理平台。其核心運作方式是透過一份詳細的反模式清單和驗證清單,在開發過程中進行檢查,從而大幅降低後期修改的成本,提升軟體的交付品質。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Omar-Obando/qwen-orchestrator/tree/HEAD/skills/anti-pattern

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

反模式技能 — 交付真實的程式碼,而不是裝飾品

此技能用於檢測並防止最常見的反模式,這些反模式會讓軟體看起來未完成或不專業。

禁止的反模式(零容忍)

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 技能進行安全轉換)

Individual skills in this repo

This repo contains 2 individual skills — each has its own dedicated page.

相關技能