前端開發技能
資深、務實、可投入生產環境的前端工程。目標始終是產出可運作、可維護、高效能的程式碼，而非純粹的學術正確性。
技術棧偵測
在進行任何操作之前，先從上下文辨識技術棧。如果不清楚，請提問。然後載入對應的參考檔案。
| 技術棧 | 載入檔案 |
|---|---|
| React（不含 GraphQL） | references/react.md |
| React + GraphQL/Relay | references/react-graphql.md |
| Angular | references/angular.md |
| TypeScript（所有技術棧） | references/typescript.md（與技術棧檔案一同載入） |
除非專案明確僅使用 JS，否則務必額外載入 references/typescript.md。
通用原則
無論使用何種技術棧，皆適用以下原則。請勿跳過。
架構
- 積極分離關注點：UI 渲染、業務邏輯、資料擷取與副作用應存在於不同層級。元件不應包含 fetch 呼叫、原始 API 字串或業務規則。
- 按功能、而非類型組織程式碼：優先採用
features/user-profile/結構，將元件、鉤子、測試與樣式放在一起，而非頂層的components/、hooks/、tests/資料夾。根據應用程式的複雜度調整結構規模，不要為小型應用過度設計。 - 組合優於繼承：透過組合小型、專注的元件來建構 UI。避免深層的元件繼承層級。
- 不要過早抽象化：先重複撰寫兩次之後再進行抽象。基於單一用例的抽象通常是錯誤的。
元件設計
- 元件應只做一件事。如果一個元件有一個以上的變更原因，請將其拆分。
- 區分呈現型元件（純 UI，無副作用）與容器/智慧型元件（資料、邏輯、協調）。
- Props 介面應明確且具備型別。不得使用
any、object或{}作為型別。 - 表單預設使用受控元件。
效能（不可協商的基準）
Core Web Vitals 目標（以真實使用者第 75 百分位數測量）：
- LCP ≤ 2.5 秒（載入）
- INP ≤ 200 毫秒（互動性 — 於 2024 年 3 月取代 FID）
- CLS ≤ 0.1（視覺穩定性）
通用效能規則：
- 絕不要以長時間的同步任務阻塞主執行緒
- 預設對路由與大型元件進行延遲載入
- 為所有圖片與多媒體設定明確尺寸（防止 CLS）
- 對 LCP 圖片使用
fetchpriority="high" - 延遲載入非關鍵的第三方腳本
- 避免版面抖動（批次處理 DOM 讀取/寫入）
- 啟用 bfcache 資格：避免使用
unload監聽器，避免不必要的no-store
設計系統與代碼
- 將設計代碼（顏色、間距、排版、圓角、陰影）定義為事實來源 — 絕不在元件中硬編碼數值
- 使用 CSS 自訂屬性（
--color-primary）或代碼系統（Style Dictionary、Tailwind 設定），使主題集中管理 - 以 Atomic Design 作為心智模型：原子 → 分子 → 有機體 → 模板 → 頁面。不必強制使用這些名稱，但請以此層級思考
- 在 Storybook 中記錄元件，以利隔離、可發現性與視覺回歸測試
- 無障礙性不可妥協：至少符合 WCAG 2.1 AA 標準。每個互動元素都需要鍵盤支援、焦點管理，以及當語意化 HTML 不足時使用 ARIA
API 整合
- 絕不要直接從元件呼叫 API。應使用資料層：自訂鉤子、服務或查詢函式庫
- 明確處理所有三種狀態：載入中、錯誤、成功 — 絕不要假設一切順利
- 在變動操作中使用樂觀更新以提升使用者感知效能
- 在邊界處驗證 API 回應（Zod、io-ts 或同等方案）— 不要信任外部資料的結構
- 集中管理 API 基礎 URL 與驗證權杖注入 — 絕不要分散在各元件中
測試策略
三層式方法：
- 單元測試：純函式、工具函式、自訂鉤子（Jest / Vitest）
- 元件測試：渲染行為、使用者互動、狀態變更（Testing Library — 測試行為，而非實作）
- 端到端測試：僅測試關鍵使用者流程（Playwright 或 Cypress）
規則：
- 從使用者角度測試行為，而非內部實作
- 在邏輯上不使用快照 — 它們很脆弱。僅在預期的視覺回歸測試中使用快照
- 目標是對業務邏輯有高覆蓋率，而非樣板程式碼
- 將測試檔案與其測試的程式碼放在一起：
Button.test.tsx與Button.tsx相鄰
程式碼導覽 (tsserver)
一般基於 LSP 的文字搜尋工作流程位於 dev-standards 技能（「程式碼導覽」）中。TypeScript 特定注意事項：
LSP 工具會針對 TS/TSX 路由到 tsserver。單一檔案操作在冷啟動時是可靠的：documentSymbol、hover、goToDefinition。
注意 — tsserver 會惰性建立索引（與 gopls 不同）。 對冷伺服器執行的跨檔案查詢（findReferences/workspaceSymbol）可能會少算：它只知道已載入其專案的檔案，並傳回一個看似完整但其實不完整的結果（例如僅有宣告）。防範方式：
- 將可疑的低參考計數視為未經驗證。
- 從使用端（有匯入該符號的檔案）查詢
findReferences，而不僅在宣告處查詢 — 這會強制載入專案圖譜。 - 對於「這個東西還有在使用嗎？」的決策（移除死碼、安全重新命名），請使用
grep確認 — 在此情況下少算可能很危險。
工具預設值（2025 年）
- 打包工具：Vite（新專案預設）；大型企業已使用 Webpack 5 的設定則繼續使用
- 程式碼檢查：ESLint +
@typescript-eslint+ Prettier（格式化與檢查分離） - 套件管理器：偏好使用 pnpm 管理 monorepo；npm 或 yarn 亦可接受
- Monorepo：Nx 或 Turborepo 用於多套件工作區
- CI：每個 PR 都應執行型別檢查、程式碼檢查、測試與建置。絕不能合併失敗的流水線。
輸出模式
產出成果時，請遵循以下指引：
元件程式碼：包含型別、處理邊界情況、遵循參考檔案中該技術棧的模式。在空間允許的情況下，同時提供元件及其測試。
架構 / 檔案結構：先顯示目錄樹，然後解釋原因。應有明確立場 — 提供一個好的結構，而非一系列選項。
效能審計：依嚴重程度（重大 / 警告 / 資訊）列出發現。每個發現需包含：問題為何、為何重要、如何修復。
設計系統設定：先定義代碼結構，然後是基礎元件，最後是文件設定。
API 整合：展示特定技術棧的資料層模式，然後是消費該資料的元件。
測試：將測試與被測試的程式碼一起展示。遵循 AAA（安排 / 執行 / 斷言）原則。
搭配技能
此技能涵蓋工程層面。對於視覺美學 — 字體選擇、色彩系統、動態設計、空間構成以及避免常見的 AI 美學 — 請交由 frontend-design 技能處理。在需要兩者的任務上（例如「建立一個看起來很棒的儀表板」），請同時使用兩種技能：frontend-dev 負責架構與程式碼品質，frontend-design 負責視覺方向。
參考檔案
在產出特定技術棧的成果前，請先閱讀這些檔案：
references/typescript.md— TypeScript 嚴格模式、模式、常見陷阱references/react.md— React 19、Next.js、鉤子、狀態管理、渲染策略references/react-graphql.md— Relay、共置片段、React 中的 GraphQL 模式references/angular.md— Angular v22、Signals、獨立元件、無 zoneless、NgRx