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