nextjs-standards

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Next.js Coding Standards Skill

Next.js 编码标准技能

Auto-Load Trigger: Presence of
next.config.*
or
"next"
in
package.json

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

When to Use

适用场景

Starting a new Next.js project
Before any TypeScript/React file edit
When context seems lost mid-session
After
```
/agent_reset
```
or
```
/vibe-primeAgent
```

启动新的Next.js项目时
编辑任何TypeScript/React文件之前
会话中途失去上下文时
执行
```
/agent_reset
```
或
```
/vibe-primeAgent
```
之后

🛑 Verification Protocol (MANDATORY)

🛑 验证协议（强制要求）

After Every TypeScript/TSX File Edit

每次编辑TypeScript/TSX文件后

bash

npx tsc --noEmit

If this fails:

DO NOT proceed to next file
Fix the type error immediately
Re-run until it passes
Only then continue

bash

npx tsc --noEmit

若执行失败：

请勿继续编辑下一个文件
立即修复类型错误
重新运行直到通过
之后再继续操作

Before Any Handoff

交付前必须执行

bash

python scripts/vibe-verify.py

All checks must pass before claiming "done."

bash

python scripts/vibe-verify.py

所有检查必须通过后才能标记为“完成”。

The Blueprint & Build Protocol

蓝图与构建协议

Phase 1: Blueprint (Before Coding)

阶段1：蓝图（编码前）

Check
```
docs/features/
```
for existing patterns
Create/update
```
docs/features/FeatureName.md
```
Wait for approval before coding

检查
```
docs/features/
```
目录下的现有模式
创建/更新
```
docs/features/FeatureName.md
```
文档
获得批准后再开始编码

Phase 2: Build (Implementation)

阶段2：构建（实现）

Announce which FR-XXX you're implementing
Reference the corresponding issue in
```
docs/issues/
```
Implement one step at a time
```
tsc --noEmit
```
after every file
Mark acceptance criteria as complete

声明你正在实现的FR-XXX需求
关联
```
docs/issues/
```
目录中对应的问题
分步实现功能
每次编辑文件后运行
```
tsc --noEmit
```
将验收标准标记为已完成

Phase 3: Finalization

阶段3：收尾

Run full verification (
```
vibe-verify.py
```
)
Update issue file with completion status
Generate handoff summary

运行完整验证（
```
vibe-verify.py
```
）
更新问题文件中的完成状态
生成交付总结

Full-Stack Type Safety

全栈类型安全

The AI reliability secret: TypeScript tells you when you broke something.

AI可靠性秘诀：TypeScript会告诉你哪里出了问题。

Core Principle

核心原则

If you change the backend, the frontend MUST type-check. If type-check fails:

The change broke something
Fix it before moving on
Never ignore type errors

若修改后端代码，前端必须通过类型检查。若类型检查失败：

你的修改引发了问题
修复后再继续
绝不能忽略类型错误

Stack Alignment

栈对齐

Server Components fetch data → types flow to client
API routes return typed responses → frontend consumes them
Prisma schema changes → regenerate client → type-check

Server Components获取数据 → 类型同步到客户端
API路由返回带类型的响应 → 前端按类型消费
Prisma Schema变更 → 重新生成客户端 → 执行类型检查

Next.js App Router Rules

Next.js App Router 规则

Server Components Default — No
```
'use client'
```
unless required
Client Components Sparingly — Only for interactivity, hooks, browser APIs
Data Fetching — In async Server Components, not
```
useEffect
```
Route Handlers — All API in
```
app/api/.../route.ts
```
Caching — Be explicit:
```
{ cache: 'no-store' }
```
or
```
revalidate = N
```

默认使用Server Components — 除非必要，否则不要添加
```
'use client'
```
谨慎使用Client Components — 仅用于实现交互性、hooks或浏览器API
数据获取 — 在异步Server Components中进行，而非
```
useEffect
```
路由处理器 — 所有API都放在
```
app/api/.../route.ts
```
中
缓存 — 显式声明：
```
{ cache: 'no-store' }
```
或
```
revalidate = N
```

File Structure (Feature-Sliced)

文件结构（按功能拆分）

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)

src/
├── app/                    # Next.js App Router 页面
├── features/               # 业务领域
│   └── [FeatureName]/
│       ├── components/     # 功能专属组件
│       ├── hooks/          # 功能专属hooks
│       └── *.service.ts    # 业务逻辑
├── components/
│   ├── ui/                 # 可复用UI组件（按钮、卡片等）
│   └── layout/             # 布局组件
├── lib/                    # 工具类、客户端
└── scripts/                # 自动化脚本（vibe-verify.py）

Component Rules

组件规则

200-Line Limit — Refactor if exceeded
Single Responsibility — One thing per component
Props Interface — Always use TypeScript interfaces
Custom Hooks — Extract stateful logic into
```
use*
```
hooks

200行限制 — 超过则需重构
单一职责 — 每个组件只负责一件事
Props接口 — 始终使用TypeScript接口定义Props
自定义Hooks — 将有状态逻辑提取到
```
use*
```
格式的hooks中

Styling (Tailwind v4)

样式规范（Tailwind v4）

Why Tailwind for AI Reliability: Tailwind colocates styles with UI in a single file. Unlike separate
.css
files, AI agents see the complete context (logic + styles + structure) without jumping between files. This dramatically reduces hallucinations and context fragmentation.

css

@import "tailwindcss";

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

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

Use
```
@theme
```
tokens, not
```
tailwind.config
```
extensions
Utility-first, no custom CSS files
Dark mode via
```
.dark
```
class on
```
<html>
```

为何选择Tailwind保障AI可靠性： Tailwind将样式与UI代码放在同一文件中。与单独的
.css
文件不同，AI Agent无需在文件间切换即可查看完整上下文（逻辑+样式+结构），大幅减少幻觉和上下文碎片化问题。

css

@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
```
类实现暗黑模式

Backend Rules

后端规则

Service Layer Pattern

服务层模式

Route Handlers = Controllers (parse request, return response)
Services = Business logic (DB queries, calculations)

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

Validation

验证

typescript

import { z } from 'zod';

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

All inputs validated with Zod. No exceptions.

typescript

import { z } from 'zod';

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

所有输入必须使用Zod进行验证，无例外。

Templates Available

可用模板

This skill provides templates in

templates/

Coding_Guidelines.md — Copy to
```
docs/Coding_Guidelines.md
```
Issue_Template.md — Format for FR issues

本技能在

templates/

目录下提供以下模板：

Coding_Guidelines.md — 可复制到
```
docs/Coding_Guidelines.md
```
使用
Issue_Template.md — FR问题的标准格式模板

Quick Reference

快速参考

Command	When
`npx tsc --noEmit`	After every TS/TSX edit
`python scripts/vibe-verify.py`	Before handoff
`npm run lint`	Check code style
`npm run build`	Verify production build

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

Recovery Protocol

恢复协议

If you break something:

bash

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

若出现错误：

bash

git status                    # 查看已修改文件
git diff                      # 查看具体变更内容
git checkout -- <file>        # 还原指定文件
git stash                     # 保存并还原所有变更