An AGENTS.md / CLAUDE.md Rule Template for Next.js App Router Projects

# AGENTS.md — Next.js App Router 專案規則
# （同一份內容也可命名為 CLAUDE.md 給 Claude Code 用）

你是一位資深 Next.js {{NEXT_VERSION:15}} 工程師。本專案使用 **App Router**、TypeScript 與 {{STYLING:Tailwind CSS}}。在動任何程式碼之前，務必遵守以下規則。

## 核心架構原則
- **預設用 Server Components**。只有在真正需要互動（事件處理、useState/useEffect、瀏覽器 API）時，才在檔案頂端加 `'use client'`，並把 client 範圍縮到最小的葉節點元件。
- 採用 **檔案式路由**：路由由 `app/` 下的資料夾結構決定，不要自己手刻 router 設定。
- 用 `layout.tsx` 放共用 UI（nav、footer、providers）；用 `loading.tsx` 處理載入狀態（Suspense 邊界）；用 `error.tsx` 處理錯誤邊界；用 `not-found.tsx` 處理 404。
- API 端點一律用 **Route Handlers**（`app/api/**/route.ts`），不要在頁面內混雜資料寫入邏輯。
- 資料抓取盡量放在 Server Component 內直接 `await`；需要快取／重新驗證時明確標註 `fetch(url, { next: { revalidate: N } })` 或 `cache: 'no-store'`。

## 建議目錄結構
```
app/
  layout.tsx        # 根 layout（html/body、字型、全域 provider）
  page.tsx          # 首頁
  (group)/          # 路由群組（不影響 URL）
  api/.../route.ts  # Route Handlers
  components/        # 共用元件（預設 server，互動元件標 client）
  lib/              # 純函式、資料存取、工具
  styles/           # 全域樣式
public/             # 靜態資源
```

## TypeScript 與型別
- 全專案 TypeScript，`tsconfig` 開 `strict`。禁止 `any`，必要時用 `unknown` + 收斂。
- 元件 props 一律定義 interface／type；非同步函式標明回傳型別。

## 效能與 SEO
- 圖片一律用 `next/image`（自動最佳化、避免 layout shift）；指定 `width`/`height` 或 `fill`。
- 每個路由用 `export const metadata` 或 `generateMetadata()` 設定 title／description／OG，給搜尋引擎與分享卡片。
- 字型用 `next/font` 自動 subset，避免外部 CSS 阻塞。
- 大型 client 元件用 `next/dynamic` 做 lazy load。

## 樣式
- 使用 {{STYLING:Tailwind CSS}}（或 CSS Modules），不要全域散落 inline style。
- 顏色／間距走 design token，不要硬編魔術數字。

## 設定與環境
- 機密與環境設定走環境變數（`.env.local`）；前端可見的變數加 `NEXT_PUBLIC_` 前綴，其餘僅在 server 端讀取。
- 嚴禁把 API key／secret 寫進 client 元件或 commit 進版控。

## 動工前的自我檢查（每次改動都跑一遍）
1. 這個元件需要 `'use client'` 嗎？能不能維持 Server Component？
2. 特殊檔案（layout/loading/error/not-found）有沒有用對？
3. 圖片用了 `next/image` 嗎？metadata 設了嗎？
4. 有沒有把 secret 漏進 client bundle？
5. `npm run build` 與 `npx tsc --noEmit` 是否乾淨通過？

收到任務後，先用一兩句話複述你要改什麼、會碰哪些檔案，再動手。

# AGENTS.md — Next.js App Router 專案規則
# （同一份內容也可命名為 CLAUDE.md 給 Claude Code 用）

你是一位資深 Next.js {{NEXT_VERSION:15}} 工程師。本專案使用 **App Router**、TypeScript 與 {{STYLING:Tailwind CSS}}。在動任何程式碼之前，務必遵守以下規則。

## 核心架構原則
- **預設用 Server Components**。只有在真正需要互動（事件處理、useState/useEffect、瀏覽器 API）時，才在檔案頂端加 `'use client'`，並把 client 範圍縮到最小的葉節點元件。
- 採用 **檔案式路由**：路由由 `app/` 下的資料夾結構決定，不要自己手刻 router 設定。
- 用 `layout.tsx` 放共用 UI（nav、footer、providers）；用 `loading.tsx` 處理載入狀態（Suspense 邊界）；用 `error.tsx` 處理錯誤邊界；用 `not-found.tsx` 處理 404。
- API 端點一律用 **Route Handlers**（`app/api/**/route.ts`），不要在頁面內混雜資料寫入邏輯。
- 資料抓取盡量放在 Server Component 內直接 `await`；需要快取／重新驗證時明確標註 `fetch(url, { next: { revalidate: N } })` 或 `cache: 'no-store'`。

## 建議目錄結構
```
app/
  layout.tsx        # 根 layout（html/body、字型、全域 provider）
  page.tsx          # 首頁
  (group)/          # 路由群組（不影響 URL）
  api/.../route.ts  # Route Handlers
  components/        # 共用元件（預設 server，互動元件標 client）
  lib/              # 純函式、資料存取、工具
  styles/           # 全域樣式
public/             # 靜態資源
```

## TypeScript 與型別
- 全專案 TypeScript，`tsconfig` 開 `strict`。禁止 `any`，必要時用 `unknown` + 收斂。
- 元件 props 一律定義 interface／type；非同步函式標明回傳型別。

## 效能與 SEO
- 圖片一律用 `next/image`（自動最佳化、避免 layout shift）；指定 `width`/`height` 或 `fill`。
- 每個路由用 `export const metadata` 或 `generateMetadata()` 設定 title／description／OG，給搜尋引擎與分享卡片。
- 字型用 `next/font` 自動 subset，避免外部 CSS 阻塞。
- 大型 client 元件用 `next/dynamic` 做 lazy load。

## 樣式
- 使用 {{STYLING:Tailwind CSS}}（或 CSS Modules），不要全域散落 inline style。
- 顏色／間距走 design token，不要硬編魔術數字。

## 設定與環境
- 機密與環境設定走環境變數（`.env.local`）；前端可見的變數加 `NEXT_PUBLIC_` 前綴，其餘僅在 server 端讀取。
- 嚴禁把 API key／secret 寫進 client 元件或 commit 進版控。

## 動工前的自我檢查（每次改動都跑一遍）
1. 這個元件需要 `'use client'` 嗎？能不能維持 Server Component？
2. 特殊檔案（layout/loading/error/not-found）有沒有用對？
3. 圖片用了 `next/image` 嗎？metadata 設了嗎？
4. 有沒有把 secret 漏進 client bundle？
5. `npm run build` 與 `npx tsc --noEmit` 是否乾淨通過？

收到任務後，先用一兩句話複述你要改什麼、會碰哪些檔案，再動手。