{
  "id": "agents-md-nextjs-saas",
  "type": "rules",
  "category": "rules",
  "locale": "en",
  "url": "/rules/agents-md-nextjs-saas",
  "title": "AGENTS.md Rules for a Next.js SaaS App",
  "description": "A drop-in AGENTS.md that keeps AI coding agents on-stack and on-convention in a Next.js SaaS codebase.",
  "tools": [
    "Cursor",
    "Claude Code",
    "Codex"
  ],
  "stack": [
    "Next.js",
    "TypeScript",
    "Tailwind"
  ],
  "tags": [
    "agents-md",
    "nextjs",
    "conventions"
  ],
  "difficulty": null,
  "updated": "2026-06-08",
  "markdown": "Drop this in your repo root as `AGENTS.md`. Most agents (Codex, Cursor, Claude\nCode) read it automatically and treat it as project rules.\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## Why these rules\n\n- **\"Server Components by default\"** is the single biggest quality lever in\n  App Router projects — see the related failure pattern on server-in-client code.\n- **Centralised env validation** stops the most common class of AI mistakes:\n  silently reading an undefined `process.env` value.\n\n## Good fit\n\n- Mid-size Next.js SaaS apps with an established convention set.\n\n## Not a fit\n\n- Greenfield prototypes where you want the agent to move fast and loose."
}