nextjs-standards

Next.js 编码规范技能

自动加载触发条件： 存在 next.config.* 或 package.json 中包含 "next"

使用时机

• 开始一个新的 Next.js 项目时
• 编辑任何 TypeScript/React 文件之前
• 会话中途感觉上下文丢失时
• 执行 /agent_reset 或 /vibe-primeAgent 后

---

🛑 验证协议（必须遵守）

每次编辑 TypeScript/TSX 文件后

npx tsc --noEmit

如果验证失败：

1. 不要继续处理下一个文件
2. 立即修复类型错误
3. 重新运行，直到通过
4. 只有通过后才能继续

移交之前

python scripts/vibe-verify.py

声称“完成”之前，所有检查都必须通过。

---

蓝图与构建协议

阶段 1：蓝图（编码之前）

1. 检查 docs/features/ 中是否有现有模式
2. 创建或更新 docs/features/FeatureName.md
3. 获得批准后再开始编码

阶段 2：构建（实现）

1. 说明你正在实现哪个 FR-XXX
2. 参考 docs/issues/ 中对应的问题
3. 一次实现一个步骤
4. 每个文件编辑后运行 tsc --noEmit
5. 将验收标准标记为已完成

阶段 3：收尾

1. 运行完整验证（vibe-verify.py）
2. 在问题文件中更新完成状态
3. 生成移交摘要

---

全栈类型安全

AI 可靠性的秘诀：TypeScript 会告诉你何时破坏了某些功能。

核心原则

如果你修改了后端，前端就必须通过类型检查。如果类型检查失败：

• 说明这次修改破坏了某些功能
• 先修复，再继续
• 绝不忽略类型错误

技术栈对齐

• 服务端组件获取数据 → 类型流向客户端
• API 路由返回带类型的响应 → 前端使用这些响应
• Prisma schema 变更 → 重新生成客户端 → 进行类型检查

---

Next.js App Router 规则

1. 默认使用服务端组件 — 除非有必要，否则不要使用 'use client'
2. 谨慎使用客户端组件 — 仅用于交互、钩子和浏览器 API
3. 数据获取 — 在异步服务端组件中进行，而不是使用 useEffect
4. 路由处理程序 — 所有 API 都放在 app/api/.../route.ts
5. 缓存 — 明确指定：{ cache: 'no-store' } 或 revalidate = N

---

文件结构（按功能切分）

src/
├── app/                    # Next.js App Router pages
├── features/               # Business domains
│   └── [FeatureName]/
│       ├── components/     # Feature-specific components
│       ├── hooks/          # Feature-specific hooks
│       └── *.service.ts    # Business logic
├── components/
│   ├── ui/                 # Reusable UI (Button, Card)
│   └── layout/             # Layout components
├── lib/                    # Utilities, clients
└── scripts/                # Automation (vibe-verify.py)

---

组件规则

1. 200 行限制 — 超出时进行重构
2. 单一职责 — 每个组件只做一件事
3. Props 接口 — 始终使用 TypeScript 接口
4. 自定义钩子 — 将有状态逻辑提取到 use* 钩子中

---

样式（Tailwind v4）

Tailwind 为何有助于提高 AI 可靠性： Tailwind 将样式与 UI 放在同一个文件中。与独立的 .css 文件不同，AI Agent 无需在文件之间切换，就能看到完整上下文（逻辑 + 样式 + 结构）。这能大幅减少幻觉和上下文碎片化。

@import "tailwindcss";

@theme {
  --color-background: #ffffff;
  --color-foreground: #0b1221;
  --color-border: #e5e7eb;
}

@theme .dark {
  --color-background: #0b1221;
  --color-foreground: #e5e7eb;
}

• 使用 @theme 令牌，而不是扩展 tailwind.config
• 采用实用工具优先，不使用自定义 CSS 文件
• 通过 <html> 上的 .dark 类实现深色模式

---

后端规则

服务层模式

• 路由处理程序 = 控制器（解析请求，返回响应）
• 服务 = 业务逻辑（数据库查询、计算）

验证

import { z } from 'zod';

const schema = z.object({
  email: z.string().email(),
  password: z.string().min(8),
});

所有输入都必须使用 Zod 验证，不得例外。

---

可用模板

此技能在 templates/ 中提供模板：

1. Coding_Guidelines.md — 复制到 docs/Coding_Guidelines.md
2. Issue_Template.md — FR 问题的格式

---

快速参考

命令	时机
npx tsc --noEmit	每次编辑 TS/TSX 后
python scripts/vibe-verify.py	移交之前
npm run lint	检查代码风格
npm run build	验证生产构建

---

恢复协议

如果你破坏了某些功能：

git status                    # See changed files
git diff                      # See what changed
git checkout -- <file>        # Revert specific file
git stash                     # Save and revert all