Next.js SaaS 应用的 AGENTS.md 规则
一个即插即用的 AGENTS.md,让 AI 编码代理在 Next.js SaaS 代码库中保持栈和约定。
CursorClaude CodeCodex Next.jsTypeScriptTailwind
将此文件放入你的仓库根目录,命名为 AGENTS.md。大多数代理(Codex、Cursor、Claude Code)会自动读取它,并将其视为项目规则。
AGENTS.md
# Project Rules
## Stack- Next.js (App Router) + TypeScript (strict).- Tailwind CSS v4. No CSS-in-JS.- PostgreSQL via the existing db client in `src/lib/db.ts`.
## Hard rules- Never add a dependency without listing it and why first.- Server Components by default. Only add `"use client"` when you need state, effects, or browser APIs — and keep those components small.- All env vars go through `src/lib/env.ts` (zod-validated). Never read `process.env` directly in app code.- Never put secrets or server-only code in a Client Component.
## Conventions- Co-locate route code under `app/`. Shared logic lives in `src/lib/`.- Use the existing UI primitives in `src/components/ui/` before adding new ones.- Write the diff and wait for approval before editing more than 3 files.
## Definition of done- `bun run typecheck` and `bun run lint` pass.- No new `any`. No unused exports.为什么这些规则
- “默认使用服务器组件” 是 App Router 项目中最大的质量杠杆——请参见服务器代码嵌入客户端的相关失败模式。
- 集中式环境变量验证 阻止了最常见的一类 AI 错误:静默读取未定义的
process.env值。
适用场景
- 中型 Next.js SaaS 应用,具有已建立的约定集。
不适用场景
- 新项目原型,你希望代理快速且松散地行动。