Next.js 與 TypeScript 編碼規範

我的功能

• •提供專案統一的編碼標準
• •指導 AI 代理遵循最佳實踐
• •確保 TypeScript 嚴格模式和型別安全
• •統一元件設計、狀態管理和樣式撰寫方式

何時使用我

在以下情況下使用此技能：

• •撰寫新的 React 元件時
• •進行程式碼審查 (Code Review) 時
• •需要確認程式碼是否符合專案規範時
• •重構現有程式碼時
• •處理型別定義和介面設計時
• •建立新檔案或目錄結構時

核心技術棧

必須使用的套件

• •Next.js: ^16.0.10 (App Router 模式)
• •React: ^18.3.1
• •Jotai: ^2.16.0 (狀態管理)
• •Tailwind CSS: ^3.4.19 (樣式)
• •TypeScript: ^5.9.3 (嚴格模式)
• •i18next: ^25.7.3 (國際化)
• •pnpm: 套件管理器

禁止使用的套件

❌ Redux、Zustand、Recoil (已使用 Jotai) ❌ styled-components、emotion (已使用 Tailwind CSS) ❌ Material-UI、Ant Design (使用 Tailwind CSS) ❌ axios (使用原生 fetch) ❌ next-intl、next-i18next (已使用 react-i18next)

編碼規範總覽

詳細的編碼規範和最佳實踐，請參考 AGENTS.md 檔案。

主要規範類別

1. 架構與檔案結構

• •App Router 目錄結構
• •元件組織原則
• •型別定義規範

2. TypeScript 與型別安全

• •嚴格模式配置
• •Interface vs Type 使用時機
• •避免 any 的具體做法

3. React 元件設計

• •函式元件優先
• •Hooks 使用規則
• •效能最佳化

4. 狀態管理 (Jotai)

• •Atom 定義標準
• •避免 props drilling
• •全域狀態最佳實踐

5. 樣式與 UI

• •Tailwind CSS 使用規範
• •響應式設計原則
• •無障礙性要求

6. 效能最佳化

• •Next.js 效能技巧
• •React 效能最佳實踐
• •打包體積優化

7. 國際化 (i18n)

• •i18next 配置標準
• •語言檔案管理
• •翻譯工作流程

8. 開發流程與工具

• •測試流程
• •Git 工作流程整合
• •建置與部署規範

快速參考

常用模式

// 元件模式
'use client';

import { useAtomValue } from 'jotai';
import type { ComponentProps } from '@/types';

export default function Component({ prop }: ComponentProps) {
  const data = useAtomValue(dataAtom);
  return <div>{data}</div>;
}

// 型別定義
interface UserData {
  id: string;
  name: string;
}

// 狀態管理
export const userDataAtom = atom<UserData[]>([]);

禁止模式

// ❌ 錯誤：使用 any
function processData(data: any) {}

// ❌ 錯誤：直接修改 props
function Component({ data }: { data: any }) {
  data.modified = true; // 錯誤
}

// ❌ 錯誤：使用禁止套件
import styled from "styled-components";

驗證檢查清單

程式碼品質

• • 使用 TypeScript 嚴格模式
• • 避免 any 類型，使用具體型別
• • 元件使用 'use client' 標記（如需要）
• • 使用 interface 定義物件結構
• • 正確使用 React Hooks

架構與組織

• • 遵循 App Router 目錄結構
• • 元件大小合理（建議 < 200 行）
• • 正確使用路徑別名（@/）
• • 適當的檔案組織

狀態管理

• • 使用 Jotai atoms 而非 props drilling
• • Atom 定義清晰且型別安全
• • 避免直接修改狀態
• • 使用適當的 Jotai hooks

樣式與 UI

• • 使用 Tailwind CSS 類別
• • 實現響應式設計
• • 新增必要的 aria-label
• • 避免內聯樣式（除非必要）

效能

• • 使用適當的 React 最佳化（memo、useCallback）
• • 避免不必要的重新渲染
• • 使用動態導入（如適當）
• • 優化圖片載入

相關技能

• •git-workflow - Git 工作流程規範
• •i18n-workflow - 多語言國際化流程
• •readme-maintenance - README.md 維護指南

這個技能確保您的程式碼始終符合專案標準並保持高品質！