前端工程師：框架元件與 Design System

這行的痛點

前端工程師找 Claude Code／Codex CLI 幫忙寫元件，最常見的失望不是「它寫不出程式碼」，而是「它寫出的程式碼跟團隊現況對不上」——用了團隊已經棄用的 Svelte 4 舊語法、生出一個跟設計系統脫節的按鈕變體、或是每次開新對話都要重新解釋一次你們的目錄慣例。這一章處理的正是「對不上」這件事，分成兩個互補的切面。

第一個切面是「程式碼語意對不對」：CLAUDE.md／AGENTS.md 分層設定、Skills 治理、框架官方整合（例如 Svelte 5 的 runes 語法），解決的是「Claude 有沒有照著你們團隊的規則寫」。第二個切面是「視覺元件對不對」：Storybook MCP、shadcn/ui 三件套，解決的是「Claude 有沒有用你們已經有的元件庫，而不是自己發明一套」。兩者常常同時出問題——一個元件可能語法正確、測試也過，但用錯了按鈕樣式；也可能視覺上跟設計稿一致，底層寫法卻跟團隊慣例脫節，之後還得花更多時間重構。

這章不重複「網頁設計達人」篇處理過的視覺判斷（配色、版面、UX 流程），焦點放在「工程面怎麼讓 AI 生成的東西跟現有系統對齊」——這是前端工程師實際維護一個活的、持續演進的程式碼庫時每天都要面對的問題，而不是一次性的專案啟動決策。

動手前的準備

• 先確認專案已經有 Storybook（或至少有雛形的元件庫）——Storybook MCP、shadcn/ui 三件套都假設你已經有基礎環境，不是從零建置 Storybook 的教學。
• Claude Code 的安裝與基本斜線指令用法，先看 Claude Code 基礎教學；若要對照 Codex CLI 的部分，先看 Codex CLI 基礎教學了解 config.toml 設定方式。
• 若工作流要串 Figma 相關 MCP，先確認 Figma 帳號權限——部分工作流要求 Figma 帳號與 Claude 帳號使用同一組信箱，否則授權會卡住。
• 外掛、MCP 與社群套件不是必要安裝項。先確認來源、版本、會讀取的資料與要求的權限，並在測試專案驗證；API key 不進版控、不貼進對話。若必須放寬網路或寫入範圍，只限目前專案的必要目錄與必要時間，不要擴到整個使用者資料夾或正式環境。
• 檢查 Node.js／npm 版本：部分社群工具（如本章提到的社群 plugin）要求 Node.js ≥ 20、npm ≥ 10，並需要 ANTHROPIC_API_KEY 或 CLAUDE_CODE_OAUTH_TOKEN。
• 團隊若已有命名慣例文件（design token 命名、元件目錄結構），先整理好——這是 CLAUDE.md、Skills、Storybook MCP 都要餵給 AI 的「地基」，地基本身混亂，AI 只會忠實複製這份混亂。

場景一：CLAUDE.md 分層治理

多數團隊導入 Claude Code 寫 React／React Native 元件時，第一個踩到的坑不是程式碼品質，而是「每次開新對話都要重新解釋一次技術堆疊」——用 TanStack Query 還是 Redux、只寫函式元件還是允許類別元件、測試要用 Vitest 還是 Jest。Cars24 工程部落格、WithStack 與 Coding Dunia 三篇實戰文章不約而同得出同一套解法：把這些決策寫進分層的 CLAUDE.md，而不是每次口頭交代。GitHub 上也有現成範本可以直接參考（MuhammadUsmanGM/claude-code-best-practices 儲存庫的 claude-md-react.md），結構是 Commands → Architecture → Component Conventions → State Management → Testing → TypeScript → Git → Do NOT 清單。

這不只是省事——作者自估「精心製作的 CLAUDE.md」能減少約 70% 的錯誤架構建議；搭配 TDD 循環後，QA 回報的新元件 bug 數量下降約 60%（皆為作者自述數字，非官方稽核）。企業級的佐證可以看 Anthropic 官方 HubSpot 客戶故事：導入 Claude Code 後行銷團隊的網頁開發生產力提升 40%，客服技術排查時間從 3–5 天壓縮到 1 小時內。

Claude Code 怎麼做

1. 執行 claude /init 掃描專案骨架，取得初版 CLAUDE.md 草稿。
2. 架構師手動補強技術堆疊、程式碼標準、目錄慣例、禁止規則，可以參考以下最小結構。
3. 分層使用節奏：每次對話用 /compact 摘要保留關鍵決策、Shift+Tab 進計畫模式先分析後執行、@檔案 引用減少幻覺；每週跑 /review 抓效能反模式（不必要重新渲染、缺 React.memo）、/clear 切換不相關任務、/context 監控上下文用量。
4. TDD 循環：先寫失敗測試（不含實作）→ 計畫模式檢視覆蓋範圍 → 執行模式實作元件 → !npx jest --coverage 驗證。

# CLAUDE.md

## Commands
npm run dev / npm run build / npm run test

## Architecture
- src/components/ — 展示型元件
- src/features/ — 依業務功能分組
- src/hooks/ — 自訂 hook 放所有業務邏輯
- src/api/ — API 呼叫層

## Component Conventions
- 只用函式元件，具名匯出（不用預設匯出）
- 測試與樣式檔跟元件放同一目錄
- Props 型別命名一律 `{Component}Props`

## State Management
- 伺服器狀態用 TanStack Query
- 本地狀態用 Zustand
- 不要引入 Redux

## Testing
- Vitest + React Testing Library
- 針對行為測試，不測實作細節

## TypeScript
- 嚴格模式，禁用 `any`（除非附註解說明原因）

## Git
- Conventional Commits

## Do NOT
- 不要在元件內直接呼叫 fetch，一律走 src/api/

換成 Codex CLI

Codex CLI 官方對應的設定檔是 AGENTS.md——官方定義為「開放格式 README for agents」，概念上跟 CLAUDE.md 一致，可以放測試指令、禁碰路徑、commit 訊息格式。但本節示範的「分層使用節奏」（/compact、/review、/clear 這幾個 Claude Code 專屬斜線指令的每日／每週紀律，以及上面那份最小範本結構）目前找不到 Codex CLI 版本的第一手實戰案例。用 Codex CLI 的通用能力應該也能做到類似效果：把同一套 Commands／Architecture／Conventions／Do NOT 清單寫進 AGENTS.md，讓它自動載入上下文；只是「多久 compact 一次」「多久跑一次審查」這類工作節奏，目前得自己摸索，沒有現成範本可以照抄。

場景二：Svelte 官方 vs Codex

Svelte 5（2024 年 10 月起 runes 預設啟用）與 SvelteKit 2 引入 $state／$derived／$effect 等顯式反應式原語，AI 很容易沿用訓練資料裡更常見的 Svelte 4 舊語法（export let、$:、createEventDispatcher），寫出「看起來合理但實際上失去反應性」的程式碼。這是研究中少見的「框架官方團隊親自下場維護 Claude Code 整合」案例——Svelte 官方直接發布了 Claude Code plugin，反觀 Vue 目前只有社群自製整合，沒有核心團隊背書的對應物，這是一個明確的語料落差，不宜暗示 Vue 有同等級的官方支援。

Claude Code 怎麼做

1. 安裝官方 plugin，取得遠端 MCP server ＋ 教 LLM 寫 Svelte 5 正確語法的 skills ＋ 專門編輯 .svelte 檔案的 agent。
2. 想要更細的元件模式（Bits UI／Ark UI／Melt UI）與部署、資料流程指引，可以再加裝社群套件 svelte-skills-kit（spences10/svelte-skills-kit，共 10 項技能）。
3. 在 CLAUDE.md 明確把「$effect 不可用來算衍生值」「createEventDispatcher 是過時寫法」列為反面教材，避免 Claude 沿用舊語法。

/plugin marketplace add sveltejs/ai-tools
/plugin install svelte

/plugin marketplace add spences10/svelte-skills-kit
/plugin install svelte-skills

換成 Codex CLI

這是本篇少數 Codex CLI 對照語料相對紮實的場景。danielvaughan.com「Codex CLI for Svelte and SvelteKit Teams」（2026-04-26）記錄了具體設定，不只是空泛帶過：

# ~/.codex/config.toml
[mcp_servers.svelte-docs]
type = "streamable-http"
url = "https://mcp.svelte.dev/mcp"

一行安裝：npx sv add mcp，提供 list-sections、get-documentation、svelte-autofixer、playground-link 四個工具。文章附的 AGENTS.md 規則範例包括「使用 $state() 作為所有可變反應式狀態」「使用 $derived() 作為計算值，永遠不要用 $effect 代替」「不要在沒有 $derived 的情況下解構 $props()——會失去反應性」。文章也設定了 post-tool-use hook，寫檔後自動跑 npm run check 與 npx vitest run --changed，在 agent 迴圈內即時抓語法誤用。模型分級策略是元件搭建、rune 遷移用 GPT-5.5，快速修復用 o4-mini。要老實說：這篇屬於 Codex Knowledge Base 系列的教學紀錄，不是像下一個場景 Storybook MCP 那樣附「有無 MCP」的量化前後對比，但設定細節具體到可以直接照抄，可信度中高。

場景三：Storybook MCP 治理

Storybook 官方部落格講得很直白：AI agent 幫忙加新元件時最常見的失敗模式，是「無視既有設計系統元件，自己生一套全新樣式與命名」，產出的是「無法合併的低品質碼」——不是語法錯，而是跟現有元件庫脫節，之後還要人工重構整合。

Claude Code 怎麼做

1. 安裝並啟動。
2. 接進 Claude Code。
3. 在 CLAUDE.md／AGENTS.md 明寫規則：「在動手寫任何 UI 之前，一律先呼叫 Storybook MCP server 查詢既有元件。」
4. 開發時 agent 會依序呼叫 list-all-documentation（列出全部已註冊元件索引）→ get-documentation（取得特定元件的 story 範例、TypeScript prop 合約）→ 寫程式碼 → run-story-tests（跑 Vitest，回報通過／失敗與無障礙違規）。

npx storybook add @storybook/addon-mcp
npm run storybook
# MCP server 掛在 http://localhost:6006/mcp

npx mcp-add --type http --url "http://localhost:6006/mcp" --scope project

Storybook 官方部落格的實測對比很具體：無 MCP 時 agent 直接寫了 263 行自訂程式碼，完全忽視既有設計系統元件；有 MCP 時 agent 進行 6 次工具呼叫驗證元件合約，產出 188 行、100% 使用真實設計系統元件，還自動偵測到 TextInput 元件缺 htmlFor／aria-invalid 等無障礙屬性並自主修復。

換成 Codex CLI

Storybook 官方文件明確把 Codex 列為支援對象之一（與 Claude Code、Gemini CLI、VS Code Copilot 並列——這裡的「VS Code Copilot」是指 VS Code 編輯器裡的 Copilot 擴充功能，跟下面要介紹的「GitHub Copilot CLI」是兩個不同產品：前者活在編輯器裡協助你寫程式，後者是獨立於編輯器之外、直接在終端機執行的 agentic coding 工具，兩者不能互相取代），設定方式相同——同一個 MCP server URL，一樣用 mcp-add 接上。但目前找不到 Codex CLI 專屬的 Storybook 實戰案例：263 行對 188 行這種量化前後對比，只在 Claude Code 的場景裡出現過。這是「官方支援清單上掛了名，但社群實戰語料集中在 Claude Code」的落差——如果你本來就在用 Codex CLI，理論上可以照抄同一組 MCP 設定接上去，只是還沒有人公開發表過逐項對比資料，實際效果建議自己先小範圍測試。

換成 GitHub Copilot CLI

Copilot CLI 掛外部 MCP 伺服器的機制跟 Claude Code、Codex CLI 概念相通，但設定檔換了位置與格式：使用者層級的 MCP 設定存在 ~/.copilot/mcp-config.json，JSON 格式，頂層是 mcpServers 物件，每個伺服器可以是 local（本機啟動子程序）或 http（連遠端 URL）兩種類型。要接 Storybook 官方部落格示範的那個 MCP server（http://localhost:6006/mcp），寫法會是：

{
  "mcpServers": {
    "storybook": {
      "type": "http",
      "url": "http://localhost:6006/mcp",
      "tools": ["*"]
    }
  }
}

不想手動編 JSON，互動階段打 /mcp add 也能做，填完設定按 Ctrl+S 存檔就會立刻寫進 mcp-config.json 並啟動該伺服器；tools 欄位可以精細控制開放範圍，全開用 ["*"]，只想開放特定工具就列成清單。跟 Claude Code、Codex CLI 一樣，目前也找不到 Storybook × Copilot CLI 的第一手實戰案例——263 行對 188 行那組量化對比同樣只出現在 Claude Code 的場景裡。但 MCP 是標準協定，機制透明，理論上照這組設定接上去就能用，實際效果建議自己先小範圍測試。

Copilot CLI 在 MCP 整合上真正跟另外兩家拉開差距的地方，不是 Storybook 這類要自己手動加的第三方伺服器，而是內建的 GitHub MCP 伺服器——官方明講這個伺服器「已經內建在 Copilot CLI 裡，不需要任何額外設定」，且預設只開唯讀工具。對元件工程場景來說，這代表查詢某個按鈕變體當初是哪個 PR 討論定案、某個 design token 命名是哪個 issue 拍板，不用像 Claude Code、Codex CLI 那樣得先手動把 api.githubcopilot.com/mcp/ 加進設定檔才能查——Copilot CLI 開箱就能查，且預設唯讀不會不小心誤觸寫入操作；真的需要開 PR、建 issue 等寫入能力，再用 --enable-all-github-mcp-tools 明確加開，或用 --add-github-mcp-toolset discussions 只加開單一 toolset。這一步省下的不是設定時間，是「查歷史脈絡」跟「動手改元件」之間的切換成本——不用先離開終端機去瀏覽器查 PR，也不用另外掛一個 MCP server 才能問。

場景四：shadcn/ui 三件套

Claude Code 生成 UI 時常缺乏專案上下文：生成的元件變體（如 variant="outline"）跟專案實際慣例不符、頁面之間顏色不一致（沒有共享 design token），開發者得再花約 15 分鐘手動查文件核對——這正好呼應場景三的痛點：AI 不是不會寫，而是不知道你的專案已經有什麼。

Claude Code 怎麼做

三個設定，總耗時約 5 分鐘、3 條指令（dev.to 具名作者實測）：

# 1. Skills 注入專案上下文（偵測 components.json，讀框架版本、Tailwind 設定、已安裝元件清單）
npx skills add shadcn/ui

# 2. MCP Server 接上 shadcn/ui registry，即時查詢元件文件與範例
claude mcp add shadcn -- npx shadcn@latest mcp

# 3. Preset 把顏色/主題/圖示/字型/邊框半徑打包成一行，團隊與 Claude Code 共用同一套 token
npx shadcn@latest init --preset a1Dg5eFl

作者實測：設定前，AI 全靠訓練資料生成、API 常出錯、每頁主題不一致；設定後，AI 讀專案即時設定、查最新文件、CSS 變數統一全站。

換成 Codex CLI

這個場景在研究筆記裡完全沒有 Codex CLI 對照案例，得老實說：Codex CLI 目前找不到這個場景的第一手案例，但用它的通用能力應該也能做到類似效果——npx shadcn@latest mcp 本身是標準 stdio MCP server，理論上可以比照場景三的做法，用 command／args 模式（而非 URL 模式）掛進 Codex CLI 的 config.toml。但 npx skills add 背後是 Claude Code 專屬的 Skills 生態，Preset 一行指令雖然是 shadcn 官方功能、任何終端機理論上都能跑，「自動偵測專案上下文」這一步在 Codex CLI 沒有對應機制，只能靠在 AGENTS.md 裡手動寫清楚專案的 shadcn 慣例來補這一塊。

常踩的坑

延伸資源

• Svelte 官方 Claude Code plugin 文件
• Storybook 官方部落格：MCP sneak peek（263 行 vs 188 行實測）
• shadcn/ui + Claude Code 三件套實測（dev.to）
• Codex CLI for Svelte and SvelteKit Teams
• CLAUDE.md React 範本（GitHub）