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/                      # UX、UI 与屏幕规格
│   │   ├── 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：服务端 Actions、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 个路由已映射
  - **已识别组件**: 共 Y 个组件已编目，分布于 Z 个区块
  - **已完成阶段**: 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）。