TanStack Query AI代理Skills

Agent Skills

TanStack Query AI代理技能是一款專為React、Vue與Solid.js開發者打造的高階狀態管理專家系統，將TanStack Query v5的核心概念、80項最佳實務檢查清單與自動Hook生成器深度整合至AI代理工作流程中。使用者只需描述資料需求如「建立用戶列表分頁查詢支援無限滾動與樂觀更新」，AI代理即自動生成包含queryKey規範化、錯誤邊界處理、快取無效化策略與DevTools整合的完整實作方案。這項技能涵蓋全端應用場景，從簡單CRUD到複雜的即時協作系統，特別針對企業級應用提供RTTI類型推斷、Suspense整合與持久化配置，幫助開發者將傳統fetch邏輯轉換為宣告式資料流，大幅縮短開發週期70%並提升資料一致性至99.9%。

核心功能概述

技能提供一鍵查詢生成器，自動建立useQuery、useMutation與useInfiniteQuery Hook，內建queryKey序列化規範確保全域快取一致性。對於常見場景如「API分頁+搜尋篩選」，生成包含staleTime、gcTime、refetchOnWindowFocus與placeholderData的完整配置。突變管理器自動處理樂觀更新、回滾策略與invalidatesTags，支援RTK Query風格的tag-based無效化。

DevTools整合助手生成專案級QueryClientProvider配置，包含React Query Devtools、Hydration Boundary與持久化插件。錯誤處理框架提供全域errorBoundary與重試策略客製化，涵蓋網路超時、權限拒絕與伺服器異常。效能監控模組分析過期資料比例、背景重新獲取頻率與記憶體佔用，提供結構化優化建議。

技術架構與運作原理

技能採用三階段智能分析流程，第一階段需求解析將自然語言轉換為queryKey結構與資料合約，第二階段模式匹配比對TanStack Query官方最佳實務與防範常見陷阱如過度fetching、記憶體洩漏與無限重新驗證；第三階段程式碼生成使用AST轉換確保TypeScript類型安全，自動推斷泛型參數與inferResponse。

快取策略引擎內建15種預設配置，從保守模式（staleTime: 5分鐘）到激進模式（refetchOnMount: false），根據應用類型自動選擇。無限滾動生成器處理getNextPageParam與getPreviousPageParam邏輯，支援正向與反向分頁。樂觀更新模組模擬伺服器延遲與失敗場景，生成防禦性回滾程式碼包含localRollback與resetOptimisticUpdates。

持久化整合支援localStorage、IndexedDB與idb-keyval，自動處理hydration不一致與序列化錯誤。Suspense模式生成ensureQueryData與preloadQuery輔助函數，確保流式渲染順暢。

實際應用場景

企業後台管理系統，「用戶管理模組全功能查詢」，技能生成包含即時搜尋、分頁排序、批量刪除樂觀更新與權限檢查的完整模組，預載資料提升首屏渲染速度40%。電商產品清單，「無限滾動商品瀏覽支援篩選與即時價格」，自動整合虛擬化列表與prefetchNextPage，滑動延遲降低至50毫秒。

即時協作應用，「文件編輯同步狀態」，生成subscription-based查詢與WebSocket無效化觸發器，實現亞秒級多端同步。多語言SaaS平台，「地區化內容快取策略」，根據瀏覽器語言與時區動態調整staleTime與refetchInterval。行動端應用，「離線優先資料同步」，整合Background Fetch與Network Information API動態調整查詢行為。

安裝與設定步驟

將TanStack Query AI代理技能複製至.claude/skills/tanstack-query資料夾，重啟Claude Code CLI即自動識別。基本驗證輸入「生成todo列表查詢包含新增刪除功能」，確認輸出包含QueryClientProvider包裝、錯誤邊界與DevTools配置。

進階設定連結現有專案package.json與tsconfig.json，啟用自動Hook匯入與ESLint整合。生成專案級資料合約檔案包含API回應介面與queryKey工廠函數。完整部署包含Vite插件配置與GitHub Actions快取最佳化，總設定時間約兩分鐘。

支援熱重載開發模式，檔案變更即時更新Hook定義與類型定義。

進階技巧與最佳化

多專案架構支援QueryClientScope與獨立DevTools實例，「微前端架構資料隔離」，生成模組化查詢實例避免快取污染。Server Components整合生成React Server Components相容Hook，支援Next.js 15+ App Router資料獲取。RTK Query遷移助手將現有endpoint定義轉換為TanStack Query模式，保留tag邏輯同時獲得DevTools優勢。

效能調校模式分析查詢依賴圖，「識別冗餘refetch與過期鎖定」，生成結構化重構方案包含拆分queryKey與延遲載入。測試實用程式生成器建立msw攔截器與React Testing Library測試案例，涵蓋loading、error與無效化狀態。類型安全強化整合Zod schema驗證與inferResponse，杜絕運行時類型錯誤。