# Next.js SaaS 应用的 AGENTS.md 规则

> 一个即插即用的 AGENTS.md，让 AI 编码代理在 Next.js SaaS 代码库中保持栈和约定。

**Type:** Rule  
**Tools:** Cursor, Claude Code, Codex  
**Stack:** Next.js, TypeScript, Tailwind  
**Updated:** 2026-06-08

---

将此文件放入你的仓库根目录，命名为 `AGENTS.md`。大多数代理（Codex、Cursor、Claude Code）会自动读取它，并将其视为项目规则。

## AGENTS.md

```md title="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 应用，具有已建立的约定集。

## 不适用场景

- 新项目原型，你希望代理快速且松散地行动。