Knowledge

Cursor, Claude Code, GitHub Copilot — fiecare agent AI de programare folosit de echipa ta a fost antrenat într-o perioadă în care Next.js însemna Pages Router, getServerSideProps și useEffect pentru aproape orice. În 2026, acesta este un default greșit. Proiectele App Router cu React Server Components, Server Actions și noul model de caching sunt un alt model de programare, iar agenții generează cod incorect sau nesigur dacă nu le spui explicit ce să facă.

Acest articol este fișierul de reguli pe care îl punem în fiecare proiect Next.js pe care îl coordonăm la Softescu. Copiază-l în .cursorrules, claude.md sau AGENTS.md, ajustează părțile specifice proiectului, iar agentul tău încetează să halucineze tipare Pages Router din 2022. Dacă vrei imaginea de ansamblu pentru construirea funcționalităților AI în aplicații Next.js, ghidul nostru de dezvoltare Next.js AI acoperă tiparele de producție.

Formatul — agents.md, claude.md, .cursorrules

Trei nume de fișiere, aceeași idee: un fișier markdown în rădăcina proiectului pe care agentul îl citește la fiecare prompt și îl folosește ca context de sistem.

• AGENTS.md — standardul deschis propus. Citit de OpenAI Codex, Aider și o listă în creștere de agenți.
• .cursorrules — fișierul de reguli al IDE-ului Cursor. Înlocuit cu .cursor/rules/*.mdc în 2025; ambele funcționează în continuare.
• claude.md sau CLAUDE.md — citit automat de Claude Code la pornirea sesiunii. Onorat atât global (în ~/.claude/) cât și per proiect (în directorul de lucru).

Toate trei sunt markdown simplu. Regulile de mai jos funcționează în oricare dintre ele.

Regula 1 — Server Components sunt default

Fiecare componentă din app/ este un Server Component dacă nu se exclude explicit cu 'use client'. Marchează un fișier 'use client' doar când componenta folosește una dintre:

• State React (useState, useReducer)
• Efecte React (useEffect, useLayoutEffect)
• API-uri exclusiv de browser (window, localStorage, IntersectionObserver)
• Handler-e de evenimente atașate în JSX (onClick, onChange, onSubmit)
• Biblioteci terțe care depind de oricare dintre acestea

Anti-pattern: punerea 'use client' pe app/layout.tsx sau pe orice pagină cu conținut preponderent static. Forțează tot subarborele în bundle-ul client și anulează principalul avantaj de performanță al framework-ului.

Regula 2 — Server Actions, nu API Routes, pentru mutații

Pentru trimiterea formularelor și orice mutație declanșată de o acțiune a utilizatorului în aplicație, folosește un Server Action. Apelează la o API Route (app/api/foo/route.ts) doar când endpoint-ul trebuie să fie accesibil din afara aplicației — de pe clienți mobile, webhook-uri, servicii terțe sau joburi programate.

// app/contact/page.tsx
async function submit(formData: FormData) {
  'use server'
  await db.contactSubmissions.create({
    email: formData.get('email'),
    message: formData.get('message'),
  })
  revalidatePath('/contact')
}

export default function ContactPage() {
  return <form action={submit}>…</form>
}

Anti-pattern: un agent care generează /api/contact/route.ts plus un fetch('/api/contact', { method: 'POST' }) client-side pentru un formular pe care doar această aplicație îl trimite. Două fișiere, un hop de rețea în plus, fără progressive enhancement și fără protecție CSRF integrată.

Regula 3 — Adu datele în Server Components, niciodată în useEffect

Dacă o pagină are nevoie de date din baza de date sau de la un API extern, adu-le în Server Component și transmite-le în jos prin props. Nu genera o Client Component cu useEffect(() => { fetch(…) }, []).

// app/posts/page.tsx — Server Component
import { db } from '@/server/db'

export default async function PostsPage() {
  const posts = await db.posts.findMany()
  return <PostList posts={posts} />
}

Anti-pattern: orice useEffect care încarcă date inițiale. Este un tipar din 2021. Singura utilizare legitimă pentru useEffect în Next.js 2026 este integrarea cu API-uri de browser imperative — canvas, video, geolocație, WebSocket.

Regula 4 — Edge Runtime este opt-in

Runtime-ul implicit este Node.js. Setează export const runtime = 'edge' doar când:

• Ruta este sensibilă la latență și distribuită global (verificări de auth, geo-routing, A/B test-uri).
• Codul folosește exclusiv API-uri compatibile cu Edge (Web Crypto, fetch, Headers; fără Node fs, fără crypto.createHash, fără Buffer).
• Bundle-ul este mic (Edge are limită de ~1 MB comprimat pe majoritatea hosturilor).

Anti-pattern: un agent care adaugă runtime = 'edge' pe o rută care importă Prisma, clientul Node al Drizzle sau orice bibliotecă ce trage după ea crypto/fs. Build-ul cade în producție dar trece în dev — exact modul de eroare pe care nu îl vrei.

Regula 5 — Structura de fișiere

app/                    # doar rute — pagini, layout-uri, route handlers
components/             # componente React de prezentare, fără data fetching
lib/                    # utilitare, tipuri, validatori independenți de framework
server/                 # cod server-only: client DB, auth, provideri AI
public/                 # asseturi statice

server/ există pentru ca agentul să aibă o destinație clară pentru codul care nu trebuie să ajungă niciodată în bundle-ul client. Marchează fișierele cu conexiunea la baza de date cu import 'server-only' în capul fișierului — build-ul va eșua zgomotos dacă o componentă client le importă vreodată.

Anti-pattern: agenți care creează directoare pages/, services/, utils/ sau hooks/ pentru că datele lor de antrenament folosesc acele convenții. Nu permite universul paralel.

Regula 6 — State-ul în URL bate state-ul în client

Dacă o bucată de state ar fi rezonabil de partajat prin trimiterea unui URL — filtre, paginare, ordine de sortare, tab-ul deschis dintr-o pagină de setări — păstreaz-o în URL prin searchParams (Server Components) sau useSearchParams (Client Components). Supraviețuiește reîncărcărilor, poate fi distribuită și este indexabilă.

Apelează la Zustand, Jotai sau Redux doar pentru state pur client care nu poate fi în URL: un modal deschis, un drag în curs, un draft de formular nesalvat.

Anti-pattern: punerea „pagina curentă = 3" în Zustand când ?page=3 face același lucru gratis, cu link-uri partajabile și suport pentru butonul Back.

Regula 7 — Streaming cu Suspense pentru date lente

Când o Server Component așteaptă ceva lent — un apel către un LLM, o căutare vectorială, un API terț — învelește-l în <Suspense> și trece copilul care așteaptă drept granița de suspense. Restul paginii se randează imediat; partea lentă vine prin stream când e gata.

export default function Page() {
  return (
    <>
      <Header />
      <Suspense fallback={<Skeleton />}>
        <SlowRecommendations />
      </Suspense>
    </>
  )
}

Anti-pattern: o singură componentă de pagină async care așteaptă totul secvențial înainte de a trimite primul byte. Time-to-first-byte lent fără motiv.

Regula 8 — Cache explicit, nu accidental

Next.js 15 a făcut caching-ul opt-in. Agentul trebuie să adnoteze fiecare fetch și fiecare rută cu o intenție explicită de caching:

• fetch(url, { cache: 'force-cache' }) — static, cache pentru totdeauna
• fetch(url, { next: { revalidate: 60 } }) — ISR, refresh la fiecare 60 s
• fetch(url, { cache: 'no-store' }) — mereu proaspăt
• Adaugă 'use cache' pe Server Components scumpe care ar trebui memoizate
• Adaugă export const dynamic = 'force-dynamic' pe rutele care nu trebuie cache-uite niciodată (auth-gated, personalizate)

Anti-pattern: baza tăcută pe default. Versiuni Next.js diferite, hosturi diferite și medii diferite aleg default-uri diferite. Adnotările explicite fac intenția agentului ușor de revizuit.

Fișierul de context complet, gata de copiat

Pune blocul de mai jos în AGENTS.md, .cursorrules sau claude.md (sau în toate trei — sunt identice). Ajustează liniile de stack de la final pentru proiectul tău, apoi commit-uiește-l împreună cu codul. Blocul este în engleză pentru că este citit de agentul AI:

# Next.js Rules for AI Agents

This is a Next.js 15+ App Router project. Follow these rules when generating
or editing code.

## Server Components by default
- Every component in `app/` is a Server Component.
- Mark a file `'use client'` only if it uses: useState, useEffect, browser
  APIs, JSX event handlers, or libraries that need any of those.
- Never put `'use client'` on a layout or a mostly-static page.

## Server Actions for mutations
- Forms and in-app mutations use Server Actions (`'use server'`).
- API Routes (`app/api/*/route.ts`) are only for external callers: mobile
  clients, webhooks, scheduled jobs.

## Data fetching
- Fetch in Server Components, pass data down as props.
- Do not use `useEffect` to load initial data.
- `useEffect` is only for imperative browser APIs (canvas, video, etc).

## Edge Runtime
- Default is Node.js. Do not set `runtime = 'edge'` unless explicitly asked.
- If switching to edge: only Web APIs, no Node `fs`/`crypto`/`Buffer`, bundle
  under ~1 MB.

## File structure
- `app/`        — routes only (pages, layouts, route handlers)
- `components/` — presentational React, no data fetching
- `lib/`        — framework-agnostic utilities, types, validators
- `server/`     — server-only code; add `import 'server-only'` at the top
- `public/`     — static assets
- Do not create `pages/`, `services/`, `utils/`, or `hooks/` directories.

## State
- URL state (`searchParams`, `useSearchParams`) beats client state.
- Use Zustand/Jotai/Redux only for state that cannot reasonably live in
  the URL (open modals, drag state, unsaved drafts).

## Streaming
- Wrap slow Server Components in `<Suspense fallback={…}>`.
- Do not await everything in one async page component.

## Caching
- Annotate every fetch: `cache: 'force-cache' | 'no-store'` or `next.revalidate`.
- Use `'use cache'` on expensive Server Components.
- Use `export const dynamic = 'force-dynamic'` on auth-gated / personalised
  routes.

## Project stack (edit per project)
- TypeScript strict mode
- Tailwind CSS + shadcn/ui
- Drizzle ORM + Postgres
- Auth.js (NextAuth) for authentication
- Vercel AI SDK for LLM calls (server-side only)
- Zod for runtime validation

Cum folosim acest fișier la Softescu

Menținem o versiune de bază a acestui fișier în toate engagement-urile Next.js cu clienții noștri și o versionăm împreună cu codul. Două convenții pe care le adăugăm întotdeauna:

1. Un director server/ai/ pentru clienți LLM, prompt-uri și rate limits — referențiat doar din Server Actions, niciodată din componente client.
2. O notă în fișierul de reguli despre ce tag-uri de logging sau analytics ar trebui să adauge agentul când generează pagini noi — folosim OpenPanel în toate proiectele noastre și agentul adaugă corect data-atributele necesare dacă fișierul de reguli le menționează.

Fișierul de reguli nu este o configurare unică. Îl tratăm ca pe o configurare CI: când un agent generează cod care nu respectă o convenție de proiect, fie reparăm comportamentul agentului printr-o regulă nouă, fie acceptăm că s-a schimbat convenția și actualizăm codebase-ul. Oricum, fișierul este sursa de adevăr.

Dacă echipa ta începe un proiect Next.js și vrea ajutor pentru un setup prietenos cu agenții AI — fișiere de reguli, structură, tipare RAG pentru funcționalități AI în aplicație — contactează-ne.