AI agent'larla Next.js

Sorun: Model Eski Next.js'i Biliyor

Next.js son iki yılda hızlı değişti. Bir modelin eğitim verisi çoğu zaman kurulu sürümden eskidir ve eski kalıpları önerir.¹ Bu rehberde gördüğünüz değişikliklerin AI çıktısında sık görülen eski hâlleri:

Next.js ekibi bu sorunu framework'ün içinden çözmeye karar verdi. 16.2'den beri her sürüm agent'lar için ayrı araçlarla geliyor.²³

Paketle Gelen Doküman ve AGENTS.md

Next.js 16.2'den beri doküman paketin içinde, node_modules/next/dist/docs/ altında gelir. Kurulu sürümle birebir eşleşir ve internet gerektirmez. 16.3'ten beri create-next-app ve next dev, projenin kökündeki AGENTS.md'ye agent'ı bu klasöre yönlendiren bir blok yazar:¹

<!-- BEGIN:nextjs-agent-rules -->

## This is NOT the Next.js you know

This version has breaking changes — APIs, conventions, and file structure may all differ
from your training data. Read the relevant guide in `node_modules/next/dist/docs/`
before writing any code. Heed deprecation notices.

<!-- END:nextjs-agent-rules -->

Next.js yalnızca işaretler arasındaki kısmı yönetir; dosyanın geri kalanına kendi kurallarınızı yazabilirsiniz. Kapatmak için next.config.ts'te agentRules: false.⁴

Neden skill değil de AGENTS.md? Vercel'in Next.js 16 değerlendirmesinde AGENTS.md'ye gömülü sıkıştırılmış bir doküman dizini testlerin %100'ünü geçti; skill tabanlı yaklaşım en iyi ihtimalle %79'da kaldı. Vakaların %56'sında agent skill'i hiç çağırmamıştı.⁵ Sonuç: her zaman bağlamda duran bilgi, agent'ın gerektiğinde araması gereken bilgiyi yener.

Agent node_modules'a erişemiyorsa: nextjs.org'daki her doküman sayfası .md uzantısıyla düz Markdown döner, /docs/llms.txt de bir dizin sunar.¹

Hatalar Prompt'a Dönüşür

Cache Components açıkken engelleyici bir hata, etiketli çözümlerle gelir. Aynı liste geliştirme ekranında, terminalde ve next build çıktısında görünür; yani CI loglarını okuyan bir agent da görür:¹

Route "/products/[slug]": Next.js encountered uncached data during prerendering.

Ways to fix this:
  - [stream] Provide a placeholder with `<Suspense fallback={...}>` around the data access
  - [cache] Cache the data access with `"use cache"`
  - [block] Set `export const instant = false` to allow a blocking route

Learn more: https://nextjs.org/docs/messages/blocking-prerender-dynamic

Hata ekranındaki Copy prompt butonu seçtiğiniz çözümü agent'a yapıştırılacak bir talimata çevirir. Learn more sayfaları da agent'lar okusun diye yazılmıştır: her çözümün kalıbı, ödünleşimi ve ilk denemede gözden kaçan noktalar.¹

Çalışan Uygulamayı Görmek

Agent'ın değişikliğini doğrulaması için hem framework'ün hem tarayıcının gördüğünü bilmesi gerekir:¹⁶

• next dev, tarayıcı konsolundaki hata ve uyarıları terminale de yazar; agent zaten okuduğu çıktıda istemci hatalarını görür.

• Dev sunucusu /_next/mcp adresinde bir MCP uç noktası açar. next-devtools-mcp ile bağlanan agent rotaları, hataları ve derleme sorunlarını okur; next build çalıştırmadan kodun derlenip derlenmediğini sorabilir. Kurulumu MCP dersinde.

• next-dev-loop skill'i, agent-browser CLI'ı ile tarayıcının DOM, konsol ve ağ görünümünü ekler. React DevTools açık başlatıldığı için component ağacını ve bekleyen Suspense sınırlarını da okur.

Next.js Skill'leri

Doküman bilgiyi verir, skill'ler ise çok adımlı işleri sıralar. Next.js ekibinin kendi skill'leri:¹⁷

$ pnpm dlx skills add vercel/next.js --skill next-dev-loop

"Her düzenlemeden sonra next-dev-loop skill'iyle sayfanın çalıştığını doğrula."

optimizer skill'lerinin yöntemi iyi bir alışkanlık: önce istenen davranışı bir testle tarif et, test geçene kadar değiştir, testi commit'le ki gelecekteki bir değişiklik bozarsa yakalansın.¹ Skill yazmanın genel kuralları Skills dersinde.

Agent ile Sürüm Güncellemek

next upgrade --agent, yeni sürümün geçiş rehberlerini toplar ve işi agent'a devreder; agent değişikliği yapar ve uygulamayı doğrular. 16.4'te deneysel ve canary sürümüyle çalışıyor:⁸

npx next@canary upgrade --agent=latest

Kendin Dene

• Bir AI aracına AGENTS.md'siz bir klasörde "Next.js'te ürün sayfasını 60 saniyede bir yenilenecek şekilde cache'le" deyin. Sonra aynı isteği create-next-app ile açılmış projede yapın. Cevapları tablodaki satırlarla karşılaştırın.

• Bir sayfada cache'lenmemiş veriyi <Suspense> dışında okuyun. Hata ekranındaki Copy prompt'u bir agent'a yapıştırın ve hangi çözümü seçtiğine bakın.

• next-devtools-mcp'yi bağlayın ve agent'a "projedeki rotaları listele" deyin.

Detaylı Öğrenmek İçin

• Resmi doküman: "How Next.js supports AI coding agents"; paketle gelen doküman, hata rehberleri, MCP, skill'ler ve agent geri bildirimi.¹

• Yazı: Vercel'in "AGENTS.md outperforms skills in our agent evals" yazısı; değerlendirmenin nasıl kurulduğu ve skill'lerin neden geride kaldığı.⁵

• Resmi doküman: Next.js 16.2 ve 16.3'ün AI duyuruları; bu araçların hangi sürümde neden geldiği.²³