Next.js Coding Rules

Opinionated coding standards and architecture rules for Next.js + TypeScript projects. Designed to be consumed by AI coding agents (Claude Code, Cursor, etc.) and human developers alike.

What's in here

A single .rules/ directory with markdown files covering:

• Architecture — Next.js App Router folder structure, Server vs Client Components
• TypeScript — strictness, naming, generics, unions over enums
• Components — layering (ui/, forms/, layout/), props typing
• State management — Zustand + React Query, with RSC boundary rules
• API layer — Server Components, Route Handlers, Server Actions, Zod validation
• Styling — Tailwind CSS conventions, theme tokens, next/font, next/image
• Forms — React Hook Form + Zod, error recovery, server actions
• Testing — Jest + React Testing Library, Playwright for E2E
• Git — commit format, branch naming, rebase workflow, PR size limits
• Code quality — ESLint, Prettier, file-length guidelines, imports, JSDoc
• Security — env var handling, CSP, cookies, CSRF, XSS prevention
• Error handling — error.tsx, not-found.tsx, toast system, network error mapping
• Accessibility — semantic HTML, ARIA, keyboard navigation, WCAG contrast
• Firebase — web SDK setup, account deletion flow, security rules
• Performance — next/image, next/font, bundle size, Core Web Vitals
• SEO — Metadata API, sitemap.ts, robots.ts, Open Graph
• Deployment — Vercel, env vars, preview deploys, branch → environment mapping
• AI agent behavior — mandatory rules every agent must follow before writing code

Who this is for

• Projects using: Next.js (App Router), TypeScript, Tailwind CSS, Zustand, React Query, React Hook Form + Zod, Firebase web SDK.
• Projects hosting on: Vercel (primary), though most rules are host-agnostic.
• AI-assisted development: these rules are written to be consumed by AI agents (Claude Code, Cursor, Continue, etc.) via a top-level CLAUDE.md or AGENTS.md pointing agents here.

If your project doesn't match this stack, adapt or fork.

How to use it

Option 1: Copy into your project

1. Copy the .rules/ folder into the root of your project.
2. Copy CLAUDE.md.example to your project root as CLAUDE.md (or AGENTS.md).
3. Gitignore .rules/, CLAUDE.md, and AGENTS.md if you want them to be local-only. Commit them if the whole team should share the rules.

Option 2: Git submodule

git submodule add <this-repo-url> .rules

Add to your top-level CLAUDE.md:

# Project Rules

You MUST read and follow all rule files in the `.rules/` directory before writing any code.

Start by reading `.rules/ai-agent-behavior.md`.

Option 3: Symlink (local experimentation)

ln -s ~/path/to/nextjs-coding-rules/.rules .rules

Then gitignore the symlink.

Reading order

1. RULES.md — table of contents and tech stack summary.
2. ai-agent-behavior.md — mandatory agent rules (read before writing any code).
3. Any file relevant to the task at hand.

Updating

These rules evolve. When you change a rule:

• Update the file.
• Bump a mental version — if behavior changes materially, consider tagging a release.
• Notify teammates / your agent that the rules have changed.

License

MIT — see LICENSE.