Przepisy optymalizacji Next.js

Żeby agent pisał poprawny kod Next.js 16, zrób trzy rzeczy: skieruj agenta do dokumentacji dołączonej do zainstalowanego pakietu next, żeby przestał pisać kod z Next.js 14 i 15, podłącz go do działającego serwera deweloperskiego przez next-devtools-mcp i pozwól, żeby next build, tsc oraz testy Playwrighta udowodniły każdą zmianę. Przepisy dotyczą Next.js 16 i App Routera.

Ta strona jest dla programistów, którzy oddają Claude Code, Codexowi lub Cursorowi pisanie aplikacji Next.js App Router, oraz dla tech leada, który musi zaufać wynikowi. Dashboard od agenta się renderuje, ale agent tworzy middleware.ts z export const runtime = 'edge', wywołuje revalidateTag('posts') z jednym argumentem i wstawia 'use client' na początku strony. Wszystko się kompiluje, build ostrzega, a ostrzeżeń nikt nie czyta.

Co dają te przepisy Next.js

• Konfigurację kontekstu, dzięki której agent czyta dokumentację Next.js dopasowaną do wersji, a nie dane treningowe
• Serwer Next.js DevTools MCP i skill next-dev-loop podpięte we wszystkich trzech narzędziach, żeby agent sam widział błędy runtime
• Osiem promptów do pracy z App Routerem, którą agenci najczęściej psują: streaming, Server Actions, uwierzytelnianie, modale, cache, Proxy, Core Web Vitals i izolacja tenantów
• Tabelę bramek, która zatwierdza zmianę bez czytania każdej linii, oraz tabelę awarii z krokami naprawczymi

Wersje sprawdzone 2026-09-26

Rejestr npm: next 16.3.6 (latest), @next/playwright 16.3.6, next-devtools-mcp 0.4.0, @trpc/server 11.19.0, @lhci/cli 0.15.1. Fakty o API na tej stronie pochodzą z dokumentacji dołączonej do next@16.3.6 w node_modules/next/dist/docs/. Jedna pułapka: tag latest pakietu next-auth to wciąż 4.24.15, a Auth.js v5 wychodzi pod tagiem beta (5.0.0-beta.32), więc npm install next-auth instaluje v4.

Najpierw daj agentowi dokumentację Next.js dopasowaną do wersji

Agenci uczyli się Next.js na latach kodu z Pages Routera, z Next.js od 13 do 15 i z wpisów na blogu Vercela. Od Next.js 16.2 pakiet next zawiera własną dokumentację w node_modules/next/dist/docs/, zgodną z zainstalowaną wersją. Twoje zadanie to sprawić, żeby agent przeczytał ją, zanim napisze kod.

1. Sprawdź, który przypadek cię dotyczy. W Next.js 16.3 i nowszym next dev wykrywa agenta i zapisuje zarządzany blok w AGENTS.md oraz plik CLAUDE.md z linią @AGENTS.md. Zacommituj oba pliki. W 16.2 dopisz instrukcję w AGENTS.md samodzielnie. W 16.1 i starszych uruchom w katalogu głównym projektu npx @next/codemod@canary agents-md, który pobiera dokumentację zgodną z wersją do .next-docs/.

2. Dopisz reguły projektu do AGENTS.md poza znacznikami <!-- BEGIN:nextjs-agent-rules -->. Wszystko między nimi next dev nadpisuje.

   ## Next.js rules for this repo (Next.js 16.3, App Router only)
   - Read node_modules/next/dist/docs/ before using any Next.js API. Heed deprecation notices.
   - Request interception lives in proxy.ts (export `proxy`). Never create middleware.ts.
   - No `export const runtime = 'edge'`. The Edge Runtime is deprecated.
   - cacheComponents is on: use 'use cache' + cacheLife + cacheTag, never `revalidate`,
     `dynamic` or `dynamicParams` segment exports.
   - revalidateTag(tag, 'max') in Route Handlers; updateTag(tag) in Server Actions.
   - 'use client' only on leaf interactive components, never on page.tsx or layout.tsx.
   - Every Server Action checks the session and the user's permission itself.
   - Done means: next typegen && tsc --noEmit, eslint, next build and Playwright all pass.

3. Pokaż przestarzałe wzorce także recenzentowi. To API, po które agent sięga najpierw, sprawdzone w dokumentacji dołączonej do next@16.3.6:

   Agent pisze	Status w Next.js 16	Zamiast tego
   middleware.ts z export function middleware	Przestarzałe, przemianowane w 16.0.0	proxy.ts z export function proxy (codemod: npx @next/codemod@canary middleware-to-proxy .)
   export const runtime = 'edge'	Edge Runtime przestarzały; nieobsługiwany w proxy.ts ani z Cache Components	Usuń eksport; domyślny jest Node.js
   revalidateTag('posts')	Forma z jednym argumentem przestarzała, błąd TypeScriptu	revalidateTag('posts', 'max') albo updateTag('posts') w Server Action
   experimental.ppr lub experimental_ppr	Usunięte w 16	cacheComponents: true w next.config.ts
   export const revalidate = 3600 na stronie	Usunięte przy włączonych Cache Components	'use cache' z cacheLife('hours')
   request.geo, request.ip	Usunięte w 15	Nagłówki od hostingu albo geolocation() z @vercel/functions na Vercelu
   dynamic(() => import(...), { ssr: false }) w Server Component	Błąd buildu	Przenieś wywołanie do Client Component
   next lint	Usunięte w 16	Bezpośrednio eslint (codemod: next-lint-to-eslint-cli)
   Slot parallel route bez default.tsx	Build w 16 się nie udaje	default.tsx, który zwraca null albo wywołuje notFound()
   <Image priority>	Przestarzałe w 16.0.0	fetchPriority="high" albo loading="eager" (lub preload) na jedynym obrazie LCP

Podłącz agenta do działającego serwera deweloperskiego Next.js

Sprawdzenie typów dowodzi, że kod się kompiluje. Nie pokazuje błędu hydratacji w konsoli przeglądarki ani trasy, która blokuje prerendering. Serwery deweloperskie Next.js 16 wystawiają endpoint MCP pod /_next/mcp, a pakiet next-devtools-mcp (0.4.0) łączy z nim agentów. Wśród jego narzędzi są get_errors, get_routes, get_logs oraz compile_route, które kompiluje jedną trasę na żądanie, i get_compilation_issues, które zwraca bieżące błędy kompilacji całego projektu. Oba działają tylko z Turbopackiem i nie wymagają pełnego next build. Szczegóły znajdziesz w opisie serwerów MCP dla serwerów deweloperskich Next.js i innych frameworków.

Claude Code

# Terminal, w katalogu głównym projektu. -s project zapisuje .mcp.json, więc zespół go współdzieli.
claude mcp add -s project next-devtools -- npx -y next-devtools-mcp@latest
npx skills add vercel/next.js --skill next-dev-loop

Uruchom npm run dev w drugim terminalu, a potem wpisz /mcp w sesji, żeby potwierdzić, że next-devtools jest połączony.

Codex

# Terminal. Zapisuje serwer w ~/.codex/config.toml.
codex mcp add next-devtools -- npx -y next-devtools-mcp@latest
npx skills add vercel/next.js --skill next-dev-loop

Uruchom codex mcp list, żeby potwierdzić wpis, i trzymaj npm run dev włączone, dopóki sesja pracuje.

Cursor

Dodaj ten sam serwer do .cursor/mcp.json w katalogu głównym projektu, a skill zainstaluj z terminala poleceniem npx skills add vercel/next.js --skill next-dev-loop.

{
  "mcpServers": {
    "next-devtools": { "command": "npx", "args": ["-y", "next-devtools-mcp@latest"] }
  }
}

next-dev-loop wymaga Next.js 16.3 lub nowszego z Turbopackiem oraz CLI agent-browser w wersji 0.31.1 lub nowszej: npm install -g agent-browser && agent-browser install. Gdy czegoś brakuje, skill podaje, jak zaktualizować, i przerywa pracę.

Skill next-dev-loop zamienia to połączenie w cykl: sprawdź, zmień, zweryfikuj. Korzysta z serwera MCP i z CLI agent-browser, który daje widok przeglądarki. Do sprawdzania stron w przeglądarce poza tym cyklem dodaj Playwright MCP albo Playwright CLI. Pozostałe skille Next.js z vercel/next.js (next-cache-components-adoption, next-cache-components-optimizer, next-partial-prefetching-adoption) opisujemy razem z innymi skillami frontendowymi.

Streamuj dashboard z niezależnymi granicami Suspense

Dashboard wykonuje cztery niezależne wywołania danych, a strona czeka na najwolniejsze. Rozwiązaniem jest osobna granica <Suspense> dla każdej sekcji. Chodzi o to, żeby agent nie owinął wszystkiego w Promise.all ani nie przeniósł strony na klienta.

Prompt do skopiowania: streamowany dashboard

Refactor app/dashboard/page.tsx (Next.js 16, cacheComponents on) to stream.
Read node_modules/next/dist/docs/01-app/02-guides/instant-navigation.md first.
- Keep page.tsx a Server Component. No 'use client' in app/dashboard/page.tsx or layout.tsx.
- Split the four fetches (getStats, getRecentOrders, getTopProducts, getActivityFeed) into
  four async Server Components, each wrapped in its own <Suspense> with a skeleton that has
  the same height as the loaded section. Do not use Promise.all across sections.
- getStats and getTopProducts can be 5 minutes stale: 'use cache' + cacheLife('minutes').
  Orders and activity are per-user and stay uncached.
- Add an e2e test in e2e/dashboard.spec.ts with instant() from @next/playwright asserting
  the page heading and all four skeletons are visible on navigation from /settings.
Verify: call get_errors and compile_route for /dashboard via next-devtools, then run
npx next build and npx playwright test e2e/dashboard.spec.ts. Report both outputs.

Funkcja pomocnicza instant() z @next/playwright zawęża asercje do interfejsu dostępnego w chwili nawigacji. Test nie przejdzie, jeśli późniejsza zmiana znowu zablokuje trasę, a właśnie tej regresji code review prawie nigdy nie wyłapuje.

Buduj formularze na Server Actions, które same sprawdzają uprawnienia

Server Actions wyglądają jak wywołania funkcji, ale dokumentacja Next.js mówi wprost, że są „osiągalne bezpośrednimi żądaniami POST”. Agent, który sprawdza sesję w proxy.ts i ufa temu wewnątrz akcji, zostawia endpoint otwarty dla każdego, kto powtórzy żądanie.

Prompt do skopiowania: formularz kontaktowy na Server Actions

Build a contact form with a Server Action. Next.js 16, React 19, Zod 4.
1. app/contact/actions.ts ('use server'): submitContact(prevState, formData). Validate with
   Zod (name 1-100 chars, valid email, message 10-1000 chars, empty honeypot field).
   Rate-limit 5 submissions per IP per hour; read the IP from the x-forwarded-for header
   set by our host, not request.ip. Return { ok, fieldErrors } and never throw to the client.
2. app/contact/contact-form.tsx ('use client'): useActionState for state and field errors,
   useFormStatus for the pending button. The form must work with JavaScript disabled.
3. app/contact/page.tsx stays a Server Component.
Tests: Vitest for the action (valid, each invalid field, honeypot, 6th submission) and a
Playwright test that submits with javaScriptEnabled: false. Run both and paste the output.

Przy akcji, która zmienia dane zalogowanego użytkownika, dopisz do promptu jedno zdanie: „call updateTag for the tag the page reads, so the user sees the change on the next render”. updateTag działa tylko w Server Actions; Route Handler obsługujący webhook używa revalidateTag(tag, 'max').

Chroń trasy przez Proxy i warstwę dostępu do danych

Przy uwierzytelnianiu agenci najczęściej zacierają granicę między serwerem a klientem. W Next.js 16 proxy.ts działa na runtime Node.js, a dokumentacja zaleca go tylko do sprawdzeń optymistycznych: odczytu ciasteczka sesji bez zapytania do bazy. Prawdziwa kontrola należy do miejsca, w którym są dane. Zanim napiszesz prompt, wybierz jedną bibliotekę: Auth.js v5 jest wciąż pod tagiem beta, a Better Auth (better-auth 1.7.6) to drugi częsty wybór w projektach z App Routerem.

Claude Code

Zacznij w trybie planowania (/plan), żeby przejrzeć listę plików, zanim powstanie jakikolwiek kod. Po zmianie uruchom /code-review i poproś o listę wszystkich Server Actions i Route Handlerów, które nie wywołują verifySession(). W CI ten sam audyt działa bez interfejsu przez claude -p "…" --tools "Read,Grep,Glob", więc recenzent nie może edytować tego, co audytuje.

Codex

Wykonaj zmianę w osobnym worktree, żeby niedokończony proxy.ts nie zepsuł działającego serwera deweloperskiego: codex exec --worktree --sandbox workspace-write "…". Potem poproś drugą sesję, tylko do odczytu (codex exec --sandbox read-only), o tę samą listę niechronionych akcji i handlerów.

Cursor

Listę plików przygotuj w Plan Mode, a implementację zleć agentowi w worktree. Przejrzyj w edytorze diff proxy.ts i lib/dal.ts. Te dwa pliki zawierają wszystkie decyzje, reszta to okablowanie. Bugbot na pull requeście jest drugim recenzentem, nie bramką.

Prompt do skopiowania: uwierzytelnianie przez Proxy i warstwę dostępu do danych

Add authentication with Better Auth to this Next.js 16 App Router app. Read
node_modules/next/dist/docs/01-app/02-guides/authentication.md and data-security.md first.
- proxy.ts (export proxy, Node runtime, no runtime export): optimistic check only. Read the
  session cookie, redirect unauthenticated users from /dashboard/* and /admin/* to /login.
  Matcher excludes _next/static, _next/image, favicon.ico and /api/auth/*. No database calls.
- lib/dal.ts with import 'server-only': verifySession() (cached per request with React cache)
  and requireRole(role). Every Server Action, Route Handler and admin page calls one of them.
- Session and role come from the server; never from a client-supplied header or form field.
Tests (Playwright): anonymous user redirected from /dashboard; a user without the admin
role gets 403 from /admin and from a direct POST to each admin Server Action; sign-out
invalidates the session. Then list every exported Server Action and Route Handler and
state which guard each one calls.

Otwieraj szczegóły produktu w modalu dzięki intercepting routes

Szczegóły produktu mają się otwierać w modalu z siatki, a jako pełna strona przy bezpośrednim wejściu lub odświeżeniu. Agenci zwykle trafiają z nazwami katalogów, ale gubią dwie rzeczy: default.tsx, którego Next.js 16 wymaga teraz dla każdego slotu parallel route, oraz zachowanie po odświeżeniu.

Prompt do skopiowania: modal produktu z intercepting route

Implement a product modal with parallel and intercepting routes (Next.js 16).
- app/products/page.tsx: Server Component grid linking to /products/[id].
- app/products/[id]/page.tsx: full detail page (await params).
- app/products/@modal/(.)[id]/page.tsx: the same data inside <ProductModal>.
- app/products/@modal/default.tsx returning null. The build fails without it.
- app/products/layout.tsx renders {children} and {modal}.
- ProductModal ('use client'): closes on backdrop click and Escape via router.back(),
  traps focus, returns focus to the clicked card, and has a "View full page" link.
Playwright tests: click opens the modal and the URL changes; Escape closes it; the browser
back button closes it; reload on /products/42 shows the full page with no modal; a direct
visit shows the full page. Run them and paste the result.

Buforuj bloga przez Cache Components i rewalidację na żądanie

Dawny przepis na bloga z 500 wpisami to Incremental Static Regeneration z export const revalidate. Przy cacheComponents: true tych eksportów segmentu już nie ma. Cache deklarujesz na funkcji danych przez 'use cache', a webhook z CMS-a unieważnia właściwy tag.

Prompt do skopiowania: cache bloga, metadane i rewalidacja

Set up caching for app/blog on Next.js 16 with cacheComponents: true in next.config.ts.
Read 01-app/02-guides/migrating-to-cache-components.md in the bundled docs first.
- lib/posts.ts: getPost(slug) and listPosts() with 'use cache', cacheLife('days'),
  cacheTag('post-' + slug) and cacheTag('posts').
- app/blog/[slug]/page.tsx: generateStaticParams for the 50 newest posts; generateMetadata
  with title, description, canonical URL and Open Graph data; Article JSON-LD in a script tag.
- app/blog/[slug]/opengraph-image.tsx with ImageResponse from next/og.
- app/api/revalidate/route.ts: POST, verify the CMS signature header with a secret from
  process.env.CMS_WEBHOOK_SECRET, then revalidateTag('post-' + slug, 'max') and
  revalidateTag('posts', 'max'). Return 401 on a bad signature.
- app/sitemap.ts and app/robots.ts.
No `export const revalidate`, `dynamic` or `dynamicParams` anywhere.
Verify: npx next build must list /blog/[slug] as prerendered; a Vitest test for the webhook
covers a valid signature, a bad signature and an unknown slug.

Prowadź testy A/B i flagi funkcji w proxy.ts

Proxy to dobre miejsce na podział wariantów przez ciasteczko i na przekazywanie flag do Server Components w nagłówkach żądania. To złe miejsce na cokolwiek wolnego, bo działa przy każdym dopasowanym żądaniu, łącznie z prefetchami.

Prompt do skopiowania: podział A/B i flagi funkcji w Proxy

Create proxy.ts (Next.js 16, export function proxy, no runtime export) that:
1. Assigns an ab-pricing cookie (a or b, 50/50, 30 days) if missing, and rewrites /pricing
   to /pricing/a or /pricing/b without changing the visible URL.
2. Reads flags for the visitor from lib/flags.ts (an in-memory snapshot refreshed every
   60 seconds, no per-request network call) and sets an x-flags request header.
3. Sets x-is-bot for known crawler user agents so pages skip personalisation.
The matcher excludes _next/static, _next/image, favicon.ico, robots.txt and sitemap.xml.
Keep each concern a small pure function in lib/proxy/ and unit-test it with NextRequest.
Add a Playwright test that a first visit to /pricing sets the cookie and that the same
variant is served on the next five visits.

Popraw Core Web Vitals z budżetem, którego pilnuje CI

Lighthouse pokazuje wynik wydajności 65, LCP 4,2 s i CLS 0,25. Poprawki są rutynowe: next/image z fetchPriority="high" na jedynym obrazie LCP, next/font, szkielety o stałych wymiarach i useTransition na filtrze. Trwały efekt daje dopiero budżet w CI: dzięki niemu następna zmiana od agenta nie cofnie tych poprawek.

Claude Code

Dodaj serwer Chrome DevTools MCP (claude mcp add chrome-devtools --scope user npx chrome-devtools-mcp@latest, wersja 1.10.1), żeby agent sam nagrał ślad wydajności dla http://localhost:3000 i odczytał element LCP, zamiast zgadywać, który to obraz.

Codex

Uruchom poprawkę przez codex exec --worktree z promptem poniżej, a potem otwórz pull request z liczbami Lighthouse sprzed zmiany i po niej w opisie. Worktree oddziela gałąź wydajnościową, dopóki budżety się nie ustabilizują.

Cursor

Pozwól agentowi przejść przez edycje komponentów w wielu plikach i sprawdź w każdym diffie fetchPriority="high": należy się jednemu obrazowi na stronę. Wysoki priorytet na każdym obrazie spowalnia LCP, zamiast go przyspieszać. Jeśli agent napisze priority, zamień je: Next.js 16 oznaczył ten prop jako przestarzały.

Prompt do skopiowania: Core Web Vitals z budżetem w CI

Improve Core Web Vitals on / and /products. Measure first, change second.
1. Run npx @lhci/cli autorun against a production build (npx next build && npx next start)
   and record LCP, CLS and total blocking time for both pages before any change.
2. Fix LCP: next/image with fetchPriority="high" on the single LCP image, never on more
   than one (the priority prop is deprecated in Next.js 16); explicit width, height and
   sizes. Fix CLS: fixed-size skeletons, next/font for every font. Fix interaction delay:
   useTransition on the product filter; next/dynamic with ssr:false only inside Client
   Components; analytics via next/script strategy="lazyOnload".
3. Add lighthouserc.json with assertions: largest-contentful-paint maxNumericValue 2500,
   cumulative-layout-shift 0.1, total-blocking-time 200, and a GitHub Actions job with
   permissions: contents: read that runs npx @lhci/cli autorun on every pull request.
4. Add useReportWebVitals in a Client Component that posts field INP, LCP and CLS to
   /api/vitals.
Report a before/after table for each page. Do not change unrelated components.

Lighthouse to test laboratoryjny bez interakcji użytkownika, więc nie zmierzy Interaction to Next Paint. Laboratoryjnym odpowiednikiem jest total blocking time, a INP z terenu daje useReportWebVitals w prawdziwych sesjach. Według progów Core Web Vitals Google na web.dev (sprawdzone 2026-09-26) „dobre” wartości to LCP do 2,5 s, CLS do 0,1 i INP do 200 ms. Testy obciążeniowe poza samą stroną opisujemy w testach wydajności z agentami.

Izoluj tenantów w SaaS dla wielu klientów

SaaS, który kieruje tenantów po subdomenie, psuje się w jeden istotny sposób: jeden tenant widzi wiersze drugiego. Jedynym dowodem, który przetrwa następny refaktor agenta, jest opakowanie zapytań ograniczone do tenanta plus test, który próbuje przekroczyć tę granicę.

Prompt do skopiowania: izolacja tenantów z testem przekroczenia granicy

Add subdomain multi-tenancy to this Next.js 16 app with Drizzle on Postgres.
- proxy.ts resolves the tenant from the host (acme.example.com -> acme), treats www and the
  apex domain as the marketing site, rewrites unknown subdomains to a branded 404, and sets
  x-tenant-slug. It does no database lookup.
- lib/tenant.ts (import 'server-only'): getTenant() reads the header, loads the tenant once
  per request with React cache, and throws if it is missing.
- lib/db/scoped.ts: scopedDb(tenantId) returns query helpers that always add
  where tenant_id = tenantId. Direct imports of the raw db outside lib/db are an ESLint error
  (no-restricted-imports).
- Integration test on a real Postgres (Testcontainers): seed tenants A and B, then call every
  exported query and Server Action as A with B's record ids. Each call must return nothing or
  404. The test fails if a new query is exported without being added to the test's list.

Do bezpieczeństwa typów end-to-end między serwerem a klientem nadal możesz użyć tRPC 11 (@trpc/server 11.19.0). Server Actions i Route Handlery z typami PageProps wystarczają jednak większości aplikacji na App Routerze. Niezależnie od wyboru dowód jest ten sam: zmień typ zwracany po stronie serwera i potwierdź, że tsc --noEmit zgłasza błąd w komponencie, który go używa.

Jak weryfikować kod Next.js od agenta bez czytania każdej linii

Czytaj diffy proxy.ts, lib/dal.ts, next.config.ts i każdego pliku, który eksportuje Server Action. Resztę niech udowodnią bramki.

Bramka	Polecenie lub narzędzie	Co świeci na czerwono
Typy	npx next typegen && npx tsc --noEmit	Synchroniczne params, zły PageProps, jednoargumentowe revalidateTag, zmiana typu na serwerze, za którą nie poszedł klient
Lint	npx eslint . plus no-restricted-imports dla modułów server-only i surowego klienta bazy	Kod serwerowy zaimportowany do Client Component; zapytania tenantów z pominięciem klienta z zakresem
Build	npx next build (dodaj --debug-prerender, gdy sam błąd buildu nie wystarcza)	Trasy blokujące prerendering, ssr: false w Server Component, slot bez default.tsx
Runtime	get_errors i compile_route przez next-devtools-mcp	Błędy hydratacji i runtime, których nie łapie sprawdzanie typów
Zachowanie	Playwright, z instant() z @next/playwright dla nawigacji	Obejście uwierzytelniania, nawigacja modala, regresje streamingu, przekroczenie granicy tenanta
Wydajność	npx @lhci/cli autorun z budżetami powyżej	Regresje LCP i CLS, ciężki JavaScript

Każ agentowi uruchomić te same bramki, zanim zgłosi koniec pracy. W Claude Code dodaj do .claude/settings.json hook Stop, który uruchamia npx tsc --noEmit && npx next build i kończy się kodem 2, gdy któreś polecenie zawiedzie. Kod 2 odsyła agentowi stderr hooka zamiast kończyć turę, dlatego polecenie przekierowuje wynik builda na stderr:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "cd \"$CLAUDE_PROJECT_DIR\" && { npx tsc --noEmit && npx next build; } 1>&2 || exit 2",
            "timeout": 600
          }
        ]
      }
    ]
  }
}

Stop nie przyjmuje pola matcher. Żeby nieudany build nie zapętlił agenta, sprawdzaj stop_hook_active w osobnym skrypcie; zobacz automatyzację hookami. W Codexie i Cursorze wpisz linię „Done means” z bloku reguł do AGENTS.md albo do Rules i wymagaj wyniku poleceń w podsumowaniu. Programista, do którego należy pull request, zatwierdza wyniki bramek i cztery wymienione pliki; resztę egzekwuje CI. Jak taki przegląd działa w skali zespołu, opisujemy w przeglądzie pull requestów od agentów.

Kiedy kod Next.js od agenta się psuje

Objaw	Przyczyna	Naprawa
Cała strona renderuje się po stronie klienta; generateMetadata nie działa	'use client' w page.tsx lub layout.tsx	Przenieś dyrektywę do najmniejszego interaktywnego liścia; dodaj regułę ESLint albo grep w CI, który blokuje 'use client' w page.tsx i layout.tsx
Build ostrzega o przestarzałym middleware albo pada na eksporcie runtime w proxy.ts	Agent napisał kod z Next.js 15	npx @next/codemod@canary middleware-to-proxy ., usuń eksport runtime i sprawdź, czy AGENTS.md wciąż ma zarządzany blok
Po mutacji widać stare dane	revalidateTag z profilem tam, gdzie użytkownik musi zobaczyć własny zapis	Użyj updateTag w Server Action; revalidateTag(tag, 'max') zostaw dla webhooków
Akcja administratora działa dla zwykłego użytkownika przez spreparowany POST	Autoryzacja tylko w proxy.ts	Dodaj requireRole() w akcji; dodaj test Playwrighta z bezpośrednim POST-em z przepisu o uwierzytelnianiu
Server Action lub strona pada z błędem serializacji „Only plain objects”	Przez granicę serwer–klient przeszła instancja klasy (encja ORM, Decimal) albo funkcja	Mapuj wyniki na zwykłe obiekty w warstwie danych, zanim trafią do Client Component lub opuszczą akcję; dodaj test jednostkowy, który sprawdza, że zwracana wartość jest zwykłym obiektem
Po zmianie w Proxy przestają się ładować CSS lub obrazy	Matcher obejmuje _next/static i _next/image	Przywróć negatywny matcher; dodaj test Playwrighta, że arkusz stylów strony zwraca 200
Agent w nowej sesji wciąż pisze kod z Next.js 14	Usunięty blok w AGENTS.md albo brak dołączonej dokumentacji (16.1 i starsze)	Uruchom next dev z sesji agenta (albo npx @next/codemod@canary agents-md w 16.1 i starszych), żeby przywrócić blok, a potem go zacommituj

Dokąd dalej z Next.js i agentami

• Zacznij od przeglądu przepisów frontendowych, jeśli pracujesz też z Angularem, Vue lub Nuxtem.
• Wzorce na poziomie komponentów rozwiniesz w przepisach dla Reacta.
• Kryteria akceptacji, które kodują twoje testy Playwrighta, opisujemy w kryteriach akceptacji, które agent może zweryfikować.
• Zestaw testów end-to-end, na którym stoją bramki, zbudujesz według testów end-to-end z agentami.
• Aktualną dokumentację do reszty stosu da agentom Context7.
• Aplikację w kontenerze wdrożysz według wzorców Dockera, a API za nią zaprojektujesz według wzorców tworzenia API.