BIGboss248/nextjs-wordpress

Next.js 專案規劃技能 (nextjs-plan)

這是一個用於規劃 Next.js App Router 應用程式的結構化編排技能。當被叫用時，它會從現有的工作區檔案中提取技術規格，針對使用者需求進行深入的引導式訪談，並輸出標準化的專案規格 (docs/project.json)、lib/ 中的類型安全程式碼登錄檔、docs/design/ 中的設計簡報，以及 docs/plan/ 中的 7 階段模組化實施路線圖。

---

工作流程概覽

flowchart TD
    Invoke["叫用 /nextjs-plan"] --> Step1["1. 自動工作區檢查<br/>(提取相依性、目錄結構、樣式、配置、路由)"]
    Step1 --> Step2["2. 關於頁面與需求的引導式訪談<br/>(頁面 ➔ 區段 ➔ 元件)"]
    Step2 --> Step3["3. 產生標準規格<br/>(docs/project.json 與 lib/ 登錄檔)"]
    Step3 --> Step4["4. 記錄策略與設計系統<br/>(docs/design/ 01-strategy, 02-sitemap, 03-tokens)"]
    Step4 --> Step5["5. 產生 7 階段模組化實作計畫<br/>(docs/plan/ README.md 與 01-07 階段檔案)"]
    Step5 --> Step6["6. 完成與結尾<br/>(呈現摘要儀表板；請勿叫用下游技能)"]

---

標準化專案目錄架構

├── lib/                             # 類型安全的 Next.js 程式碼真相來源
│   ├── routes.ts                    # 集中式路由登錄檔與路徑建構器
│   ├── site-config.ts               # 集中式網站元資料、作者簡介、社交連結
│   └── utils.ts                     # Tailwind cn 輔助函式
├── docs/                            # 架構、規劃與設計理由
│   ├── project.json                 # 標準機器可讀規格
│   ├── plan/                        # 7 階段模組化實施路線圖
│   │   ├── README.md                # 主儀表板：進度追蹤與階段索引
│   │   ├── 01-discovery-and-architecture.md
│   │   ├── 02-environment-and-cicd.md
│   │   ├── 03-system-health-probe.md
│   │   ├── 04-core-foundations.md
│   │   ├── 05-pages-and-components.md
│   │   ├── 06-server-functions-and-metadata.md
│   │   └── 07-integrations-and-release.md
│   ├── design/                      # 使用者體驗、使用者介面與畫面規格
│   │   ├── 01-strategy-brief.md     # 目的、人物誌、目標、KPI、基準
│   │   ├── 02-sitemap-and-routes.md # 頁面清單、區段層級、渲染矩陣
│   │   ├── 03-ui-design-tokens.md   # 語意化 CSS 權杖、排版、元件原語
│   │   └── components/              # 元件設計規格與拼接畫面截圖
│   └── adr/                         # 架構決策記錄

---

逐步執行手冊

1. 自動工作區檢查 (零中斷)

[!IMPORTANT] 先檢查，後提問。 絕不要求使用者提供可直接從工作區檔案推斷的事實。

• 掃描工作區上下文：檢查 package.json、鎖定檔 (pnpm-lock.yaml、bun.lockb)、路由結構 (app/ vs src/app/)、元件目錄、app/globals.css、UI 函式庫 (shadcn/ui、lucide-react、動畫)、next-intl 設定 (根目錄 messages/ 資料夾)、現有路由 (page.tsx、route.ts)，以及測試/Docker 配置。
• 完整的檢查清單，請參閱 workspace-inspection.md。

2. 使用者引導式訪談 (頁面 ➔ 區段 ➔ 元件)

• 執行適應性引導式訪談：使用引導式前沿方法論，以結構化輪次與使用者互動。為每個問題編號並提供建議答案。
• 強制性引導順序：
  1. 頁面引導：列舉所有必要的網頁與目標 URL 路由。
  2. 區段引導：對於每個頁面，從上到下識別所有內容區段。
  3. 元件引導：對於每個區段，定義所有必要的 UI 元件。
• 核心詢問項目：問題陳述、目標人物誌、認證機制、資料層/ORM、i18n 語言環境 & RTL、視覺美學風格，以及部署目標。
• 關於訪談範本和決策樹規則，請參閱 grilling-interview.md。

3. 產生標準規格與類型安全程式碼

• 建立 docs/project.json：填入技術元資料 (套件管理器、元件目錄、樣式、UI/動畫/測試函式庫、支援語言、字典路徑)。請參閱 project-schema.md 並部署 project.json.template。
• 建立 lib/routes.ts：從 routes.ts.template 產生類型安全的路由登錄檔。
• 建立 lib/site-config.ts：從 site-config.ts.template 產生集中式網站輪廓與元資料。

4. 在 docs/design/ 中記錄設計策略

• 建立 docs/design/01-strategy-brief.md：部署 01-strategy-brief.md.template。
• 建立 docs/design/02-sitemap-and-routes.md：部署 02-sitemap-and-routes.md.template。
• 建立 docs/design/03-ui-design-tokens.md：部署 03-ui-design-tokens.md.template。

5. 產生 7 階段模組化實施路線圖 (docs/plan/)

• 搭建 docs/plan/ 目錄：使用 resources/templates/plan/ 中的範本部署模組化計畫檔案：
  1. docs/plan/README.md (主要進度儀表板)
  2. docs/plan/01-discovery-and-architecture.md (階段 1)
  3. docs/plan/02-environment-and-cicd.md (階段 2)
  4. docs/plan/03-system-health-probe.md (階段 3：/api/health 存活探測)
  5. docs/plan/04-core-foundations.md (階段 4：環境變數、i18n、主題權杖、佈局、OTel)
  6. docs/plan/05-pages-and-components.md (階段 5：標準頁面與元件檢查清單，含 SEO 與支援檔案)
  7. docs/plan/06-server-functions-and-metadata.md (階段 6：伺服器動作、API 路由、全域 SEO)
  8. docs/plan/07-integrations-and-release.md (階段 7：整合與產品發布)
• 單一事實來源與強制性頁面層級檔案：階段 5 (05-pages-and-components.md) 是頁面與元件的唯一標準檢查清單。對於每個頁面，強制執行 page.tsx、loading.tsx、error.tsx、generateMetadata、JSON-LD Schema 和 generateStaticParams() (用於動態路由) 的子檢查清單任務。
• 頁面完成規則：在階段 5 中，僅當該頁面的所有元件子檢查清單項目與頁面層級的 SEO/支援任務全部完成時，才能將該頁面項目標記為 - [x]。
• 請參閱 plan-checklist-structure.md 以取得完整的階段指南。

6. 結尾與完成閘道

• 向使用者呈現簡潔的摘要報告，詳細說明工作區發現、docs/project.json 中的規格，以及 docs/plan/README.md 中的路線圖。
• 請勿自動叫用下游的 Next.js 技能。 結束執行並讓使用者審閱計畫。

---

邊緣案例與已知 AI 陷阱

[!WARNING]

• 鏈結指令：切勿使用 &&、|| 或 ; 在單一行中執行複合指令。始終單獨執行終端機指令。
• 先問後查：請勿向使用者詢問可直接從 package.json 或目錄清單中讀取的基本事實。
• 里程碑順序顛倒：健康探測 (/api/health) 屬於階段 3，接著是階段 4 的核心基礎設施 (i18n、主題、佈局、OTel)，然後才是頁面/元件的實作。
• 遺漏頁面層級檔案：在撰寫階段 5 檢查清單時，切勿遺漏任何頁面的 loading.tsx、error.tsx、generateMetadata 或 JSON-LD schema 任務。
• 頁面清單重複：所有頁面與元件的追蹤嚴格保持在 docs/plan/05-pages-and-components.md 中。
• 過早標記頁面完成：階段 5 中的頁面必須保持 - [ ] 狀態，直到所有子元件與頁面層級支援檔案完成為止。
• 字典位置錯誤：在 Next.js i18n 配置中，字典位於根目錄 messages/ (例如 messages/en.json)，絕不在 app/dictionaries。
• 衍生下游技能：完成計畫後，請勿自動觸發實作或樣式技能；應停止並等待使用者指示。

---

輸出摘要架構

在規劃階段結束時，以下列格式呈現摘要：

### Next.js 專案計畫已完成

- **標準規格**：`[docs/project.json](file:///...)`
- **類型安全登錄檔**：`[lib/routes.ts](file:///...)` | `[lib/site-config.ts](file:///...)`
- **設計與策略規格**：`[docs/design/01-strategy-brief.md](file:///...)`、`[docs/design/02-sitemap-and-routes.md](file:///...)`、`[docs/design/03-ui-design-tokens.md](file:///...)`
- **模組化路線圖儀表板**：`[docs/plan/README.md](file:///...)`
  - **已識別頁面**：共 X 條已對應路由
  - **已識別元件**：跨 Z 個區段編錄共 Y 個元件
  - **已完成階段**：N / 7 個階段已驗證

_規劃完成。請檢閱 `docs/plan/README.md` 以繼續進行元件設計或實作。_

---

參考指南與範本

• 工作區檢查指南 — 訪談前程式碼庫探索檢查清單。
• 引導式訪談指南 — 多輪提問協定與詢問領域。
• 專案架構參考 — docs/project.json 的規格欄位與驗證標準。
• 計畫架構參考 — 7 階段模組化路線圖結構與頁面-元件規則。
• 專案 JSON 範本 — docs/project.json 的起始架構。
• 模組化計畫範本 — docs/plan/ 的起始範本。
• 路由 TypeScript 範本 — lib/routes.ts 的類型安全路由定義。
• 網站配置範本 — lib/site-config.ts 的集中式網站輪廓。
• 策略簡報範本 — docs/design/01-strategy-brief.md 的範本。
• 網站地圖與路由範本 — docs/design/02-sitemap-and-routes.md 的範本。
• UI 設計權杖範本 — docs/design/03-ui-design-tokens.md 的範本。
• 環境變數範例範本 — .env.example 的單一事實來源範本 (重新命名為 .env 以用於生產部署)。
• 開發環境範本 — .env.development 的預設開發變數 (本地開發，已在 gitignore 中)。