core-principles

core-principles 技能為開發者與 AI 代理提供了現代 React 19 單頁應用程式的強制性架構框架。它作為專案組織的唯一權威來源，透過嚴格遵守經驗證的模式來最小化技術債。此技能旨在幫助工程團隊在不犧牲程式碼品質或效能的情況下擴展開發速度。它連接了高階架構意圖與日常實作細節，以維護強大、可測試且易於維護的程式碼庫。

• 標準化堆疊配置，包括帶有編譯器功能的 React 19、TypeScript（嚴格模式）、Vite、用於代碼檢查與格式化的 Biome、用於伺服器狀態管理的 TanStack Query，以及用於型別安全檔案路由的 TanStack Router。

• 定義嚴格的專案目錄結構（/src/app, /src/features, /src/api, /src/routes），以確保組件隔離與可預測的資料流。

• 強制執行嚴格的資料存取規則：API 互動必須僅透過 TanStack Query 特徵 Hook 處理，嚴禁在 UI 組件內直接進行資料請求。

• 使用 Apidog MCP 作為權威來源來管理 API 整合模式，確保 /src/api 中的客戶端型別始終與後端規範同步。

• 指導狀態管理與效能最佳化，優先考慮純組件與自動記憶化（memoization）模式，同時為使用 React Actions 或 TanStack Query 進行伺服器變更提供了清晰的執行規則。

• 在提交程式碼前務必執行 'biome check --write' 以維持格式一致性。

• 確保所有 API 驅動的功能均使用 Apidog MCP 整合產生的型別，以維持資料邊界的型別安全。

• 新增路由時，實作 loader 以進行預取（prefetching），從而在導覽期間最佳化感知的載入效能。

• 將測試檔案與功能檔案放在一起，並利用 MSW 進行網路存根（stubbing），以達成全面的測試覆蓋率。

• 將此技能文件視為架構合約；除非已針對這些核心準則進行驗證，否則避免引入第三方框架。