Next.js 16.3 ve AI Ajanları: AGENTS.md ile Doğru Doküman

Next.js 16.3, AI kodlama ajanlarının en büyük şikayetine doğrudan çözüm getiriyor: artık ajanlar, projenin gerçekte kurulu olduğu Next.js sürümüyle birebir eşleşen dokümanı okuyor. next dev komutu, bu dokümana işaret eden bir AGENTS.md bloğunu otomatik yazıp bakımını yapıyor — kurulum yok, ekstra araç yok. Bu yazıda bu mekanizmanın gerçekte nasıl çalıştığına, Claude Code ve Cursor gibi araçlarla nasıl doğrulayacağına ve mekanizmanın nerede durduğuna bakacaksın.

💡 Pro Tip: Mevcut bir projede AGENTS.md'nin otomatik yazılması için tek şart Next.js 16.3+ kurulu olması ve next dev'i bir AI kodlama ajanının başlattığı bir terminalde/ortamda çalıştırman — ajan algılanmazsa dosya hiç dokunulmadan kalır.

İçindekiler

• Sorun: Ajanlar Neden Eski Next.js API'si Yazıyor
• 16.3'ün Çözümü: Sürüm-Eşleşmeli, Paketli Doküman
• next dev'in Ürettiği ve Bakımını Yaptığı AGENTS.md Bloğu
• Claude Code / Cursor Tarafında Pratik Kurulum ve Doğrulama
• Ajanın Önerdiği Kodu Kanıta Bağlama
• Sınırlar: Doküman Doğru Olsa da Halüsinasyon Biter mi
• Farkı Kendi Projende Nasıl Ölçersin
• SSS
• AGENTS.md nedir, ne işe yarar?
• AI ajanı neden eski Next.js API'lerini öneriyor?
• Next.js dokümanını AI ajanına sürüm-eşleşmeli nasıl verdirilir?
• Sürüm-eşleşmeli doküman halüsinasyonu bitirir mi?
• agentRules: false ile --no-agents-md aynı şey mi?
• Bu otomasyon hangi ajanlarla çalışıyor?
• Sonuç
• Kaynaklar

Sorun: Ajanlar Neden Eski Next.js API'si Yazıyor

AI kodlama ajanlarının kod önerileri, eğitim verisinin donduğu ana kadarki bilgiye dayanır. Next.js gibi hızlı hareket eden bir framework'te bu, ajanın altı ay önce kaldırılmış bir API'yi, deprecate edilmiş bir prop'u ya da artık varsayılan olmayan bir davranışı "doğruymuş gibi" önermesi anlamına gelir. Proje next.config.ts'de cacheComponents açmışsa ya da Edge Runtime'dan Node.js'e geçmişse, ajan bunu bilmeden eski kalıpları tekrar üretebilir — Next.js 16.3'ün Cache Components ve Instant Navigations ile Edge Runtime'ın kaldırılışı gibi kırıcı değişiklikler tam da bu riski büyüten örnekler.

Next.js ekibinin çözümü basit bir gözlemden geliyor: ajana internet üzerinden güncel dokümana erişim vermek yerine, dokümanı doğrudan kurulu paketin içine koy. Böylece ajan hangi sürümün kurulu olduğunu bilmese bile, okuduğu doküman zaten o sürümle eşleşiyor.

Bu yaklaşımın önceki nesil çözümlerden farkı, dokümanı "canlı" tutma sorumluluğunu senden alıp paket yöneticisine devretmesi. Önceden bu işi ya elle güncellenen bir proje notu, ya da genel amaçlı (sürüme duyarsız) bir "knowledge" Skill üstleniyordu — her ikisi de zamanla eskiyip projenin gerçek durumundan sapabiliyordu. next paketini npm install next@latest ile güncellediğinde, paketlenmiş doküman da otomatik olarak yeni sürümle birlikte geliyor; ayrıca bir senkronizasyon adımına gerek kalmıyor.

16.3'ün Çözümü: Sürüm-Eşleşmeli, Paketli Doküman

Next.js 16.3 ile birlikte, next paketini kurduğunda dokümantasyon node_modules/next/dist/docs/ altına gömülü olarak geliyor — nextjs.org sitesinin yapısını birebir yansıtan bir klasör ağacı. Bu, ajanın ağ isteği atmasına gerek kalmadan, tam olarak kurulu sürümle eşleşen dokümana erişebileceği anlamına geliyor.

Bu, Next.js'in 16.3 duyurusunda "Versioned docs for AI agents" başlığı altında öne çıkardığı özellik: "AI coding agents now automatically read documentation that matches your project's version of Next.js." Bu adım, önceden var olan ve tek işlevi ajanlara güncel doküman getirmek olan Skill'lerin emekliye ayrılmasını da beraberinde getirdi — artık ayrı bir Skill kurmaya gerek yok, mekanizma framework'ün kendisine gömülü.

Yeni projelerde bu otomatik: create-next-app çalıştırdığında hem AGENTS.md hem CLAUDE.md dosyaları ekstra kurulum gerekmeden oluşuyor. İstemiyorsan --no-agents-md bayrağıyla kapatabilirsin. Resmi doküman örnekleri @canary etiketiyle veriyor:

1npx create-next-app@canary
2# AGENTS.md ve CLAUDE.md otomatik oluşur
3 
4npx create-next-app@canary --no-agents-md
5# agent dosyaları oluşturulmaz

next dev'in Ürettiği ve Bakımını Yaptığı AGENTS.md Bloğu

Mevcut bir projede (yeni proje kurmadan) bu otomasyonu tetikleyen şey next dev komutunun kendisi. Next.js 16.3 veya sonrasında next dev çalıştırıldığında, ortamda bir AI kodlama ajanı algılanırsa ve henüz yönetilen bir blok yoksa, Next.js AGENTS.md ve CLAUDE.md dosyalarını proje kökünde otomatik oluşturuyor ya da günceliyor.

Kritik detay: bu bir "upsert". Next.js'in yönettiği blok <!-- BEGIN:nextjs-agent-rules --> ve <!-- END:nextjs-agent-rules --> işaretçileri arasında duruyor; dosya zaten varsa yalnızca bu iki işaretçinin arasındaki içerik güncelleniyor, dışına yazdığın her şey korunuyor. Böylece kendi proje kurallarını (test komutları, klasör konvansiyonları, deploy notları) aynı dosyada tutmaya devam edebilirsin, Next.js bunların üstüne yazmıyor. next dev'in bastığı blok şu:

1<!-- BEGIN:nextjs-agent-rules -->
2 
3 # This is NOT the Next.js you know
4 
5This 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/` (resolved from this file's directory; in monorepos the `next` package may not be visible from the repo root) before writing any code. Heed deprecation notices.
6 
7This block is written and re-added by `next dev` — verify at `node_modules/next/dist/server/lib/generate-agent-files.js`. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.
8 
9<!-- END:nextjs-agent-rules -->

Yukarıdaki bloktaki başlık satırının başındaki boşluk yalnızca bu sayfaya ait; gerçek dosyada boşluk yok.

Blok, ajana doğrudan "bu, bildiğin Next.js değil" diye sesleniyor; resmi dokümana göre onu diff'ten silmek işe yaramıyor, next dev yeniden ekliyor. CLAUDE.md tarafında üretilen içerik ise tek satır: @AGENTS.md.

Bu otomasyonu istemiyorsan next.config.ts içinde agentRules: false ayarıyla tamamen kapatabilirsin — bu, create-next-app'in --no-agents-md bayrağından ayrı bir mekanizma, ikisini karıştırma: biri yeni proje kurulumunu, diğeri mevcut projede next dev'in otomatik yazımını kontrol ediyor.

1// next.config.ts
2import type { NextConfig } from "next";
3 
4const nextConfig: NextConfig = {
5  agentRules: false, // next dev'in AGENTS.md/CLAUDE.md yazmasını kapatır
6};
7 
8export default nextConfig;

Claude Code / Cursor Tarafında Pratik Kurulum ve Doğrulama

Next.js'in resmi dokümanına göre Claude Code, Codex, Cursor ve GitHub Copilot dahil çoğu AI kodlama ajanı, oturum başlarken projedeki AGENTS.md dosyasını otomatik okuyor. Yani ekstra bir "bu dosyayı oku" talimatı vermene gerek yok — ajan AGENTS.md'yi kendiliğinden bulup context'ine alıyor.

Pratikte kurulum akışı şöyle işliyor:

1. Yeni proje: create-next-app çalıştır, AGENTS.md+CLAUDE.md otomatik gelir.
2. Mevcut proje: Next.js'i 16.3+'a yükselt, ardından next dev'i Claude Code veya Cursor'un açtığı bir terminalde çalıştır — ajan algılanınca dosyalar otomatik eklenir.
3. Doğrulama: cat AGENTS.md ile bloğun geldiğini, ls node_modules/next/dist/docs/ ile paketlenmiş dokümanın kurulu olduğunu kontrol et.

16.3 ayrıca next-dev-loop adlı ilk-parti bir Skill de tanıtıyor; bu Skill ajana hem framework MCP sunucusu (/_next/mcp) hem de agent-browser CLI (0.27+) üzerinden canlı tarayıcı erişimi veriyor — konsolu okuyabiliyor, network isteklerini takip edebiliyor, React ağacını inceleyebiliyor. Daha önce 16.2'de deneysel olarak gelen next-browser, genel amaçlı agent-browser CLI'a birleşti; 0.27 sürümü buna React DevTools introspection ekledi. Pratikte ajan şu komutları kullanabiliyor:

Bu react komutları yalnızca React DevTools açıkken çalışıyor — agent-browser open çağrısına --enable react-devtools geçmelisin; next-dev-loop Skill'i bunu senin yerine yapıyor.

Bu komutlar, ajanın "neden bu component yeniden render oluyor" ya da "hangi Suspense sınırı beklemede kalıyor" gibi soruları, senin manuel olarak React DevTools açmana gerek kalmadan cevaplamasını sağlıyor. Stabil 16.3'te toplam dört ilk-parti Skill var:

Ajanın Önerdiği Kodu Kanıta Bağlama

Paketli doküman, ajanın _doğru_ öneri yapma ihtimalini artırıyor ama önerinin gerçekten derlendiğini kanıtlamak ayrı bir adım. Next.js 16 ile gelen framework MCP sunucusuna 16.3 iki yeni derleme aracı ekliyor: get_compilation_issues ve compile_route. İkisi de tam bir next build çalıştırmadan, dev server üzerinden kodun derlenip derlenmediğini raporluyor — ajan bir değişiklik önerdiğinde bunu tam bir build beklemeden, çok daha hızlı doğrulayabiliyor.

get_compilation_issues tüm projeyi, compile_route tek bir route'u hedefliyor.

Erişimin iki yolu var. Resmi duyuruya göre next-dev-loop gibi Skill'ler /_next/mcp uç noktalarını doğrudan çağırıyor, ekstra kurulum istemiyor. Kendi ajan istemcinde ise .mcp.json dosyana next-devtools-mcp'yi eklemen gerekiyor; istemci çalışan next dev sunucusunu kendiliğinden buluyor. Skill'i kurmak tek komut:

1npx skills add vercel/next.js --skill next-dev-loop

Resmi dokümanın önerdiği prompt kalıbı tek cümle:

1After every edit, verify the page still works at runtime using the next-dev-loop Skill.

Hata durumunda 16.3'ün hata sayfaları devreye giriyor: Cache Components açıkken bloklayan bir hata, her biri farklı bir ödünleşme yapan etiketli düzeltmeler ([stream], [cache], [block]) halinde sunuluyor ve dev overlay'deki "Copy prompt" düğmesi, seçtiğin düzeltmeyi yapıştırmaya hazır bir prompt haline paketliyor. Aynı menü next dev terminaline ve next build çıktısına da basılıyor.

Gerçek doğrulama zinciri hâlâ üç adımlı: ajan öneriyi yazar → MCP/derleme kontrolü geçer → sen (veya CI) canlı ortamda çalıştığını teyit edersin. Paketli doküman ve MCP araçları bu zincirin ilk iki adımını hızlandırıyor, üçüncüsünü ortadan kaldırmıyor. Pratikte bu, next build'i her küçük değişiklikte tekrar çalıştırmak zorunda kalmadan, dev döngüsü içinde çok daha sık doğrulama yapabilmen anlamına geliyor — özellikle büyük bir monorepo'da tam bir next build'i beklemek yerine, tek route'luk bir kontrol çok daha hızlı dönüyor.

Sınırlar: Doküman Doğru Olsa da Halüsinasyon Biter mi

Burada net olmak gerekiyor: Next.js'in resmi kaynakları "halüsinasyon tamamen biter" gibi bir iddiada bulunmuyor. Resmi dokümanda geçen ifade şu: "Benchmark results on nextjs.org/evals show agents do better when they read the bundled docs" — yani ölçülebilir bir iyileşme iddiası var, sıfır hata iddiası yok.

Bunun pratik anlamı şu: AGENTS.md ve paketli doküman, ajanın API yüzeyini (fonksiyon adı, config anahtarı, varsayılan davranış) doğru okumasını kolaylaştırıyor. Ama ajan hâlâ mimari kararlar verirken, iş mantığını yorumlarken ya da birden fazla geçerli yaklaşım arasında seçim yaparken yanlış yapabilir — bu, dokümanın güncel olmasıyla çözülen bir sorun değil. Plan Mode ile mimari planlama gibi bir aşamayı, doküman ne kadar taze olursa olsun, atlamamak gerekiyor.

Kısacası: paketli doküman, ajanın "hangi API var" sorusuna doğru cevap verme ihtimalini artırıyor; "bu API'yi burada nasıl kullanmalıyım" sorusundaki muhakeme hatalarını otomatik olarak çözmüyor.

Bunun bir başka pratik sonucu var: paketli doküman yalnızca Next.js'in kendi API yüzeyini kapsıyor. Projendeki üçüncü parti kütüphaneler, kendi iç servislerin ya da takımının belirlediği konvansiyonlar bu dokümanın dışında kalıyor — onları hâlâ kendi AGENTS.md bloğunun dışına, ya da MCP sunucuları üzerinden ajana ayrıca tanıtman gerekiyor. AGENTS.md tek başına "her şeyi bilen ajan" garantisi vermiyor, yalnızca framework katmanındaki bilgi boşluğunu kapatıyor.

Farkı Kendi Projende Nasıl Ölçersin

Genel bir iyileşme oranı arıyorsan referans nextjs.org/evals benchmark sonuçları — resmi doküman otomatik üretimi açık bırakmayı tam da bu ölçüme dayandırıyor. Ama bu sonuçlar Next.js'in kendi test setine ait; senin kod tabanındaki farkı doğrudan söylemiyor.

Kendi projende ölçmek istersen en pratik yöntem küçük bir A/B kurmak: next.config.ts içinde agentRules: false ile bloğu geçici olarak kapat, aynı görevi (örneğin bir API route'unu belirli bir cache stratejisiyle yeniden yazmak) hem blok kapalıyken hem açıkken ajana verdir ve kaç turda derleme hatasız geçtiğini say. İki koşulda aynı prompt'u, commit'i ve modeli kullan; yoksa ölçtüğün şey blok değil, prompt farkı olur.

SSS

AGENTS.md nedir, ne işe yarar?

AGENTS.md, bir projenin kökünde duran ve AI kodlama ajanlarına kurulum, test ve konvansiyon bilgisi veren, açık bir format — "ajanlar için README" gibi düşünebilirsin. 60 binden fazla açık kaynak projede kullanılıyor ve OpenAI Codex, Amp, Google Jules, Cursor gibi araçların ortak çabasıyla ortaya çıktı. Next.js tarafında 16.2'de yeni projelerde create-next-app AGENTS.md'yi zaten paketli dokümana yönlendiriyordu; mevcut projelerde otomatik üretim 16.3 ile next dev'e geldi (16.2'de dosyayı elle eklemen gerekiyordu).

AI ajanı neden eski Next.js API'lerini öneriyor?

Çünkü ajanın eğitim verisi belirli bir zaman noktasında donuyor ve framework'ün en güncel API'lerini yakalayamıyor. Next.js bu sorunu, next paketiyle birlikte sürüm-eşleşmeli dokümanı node_modules/next/dist/docs/ altına gömüp AGENTS.md'nin ajanı doğrudan oraya yönlendirmesiyle çözüyor — ajan hangi sürümün kurulu olduğunu bilmese bile okuduğu doküman o sürümle eşleşiyor.

Next.js dokümanını AI ajanına sürüm-eşleşmeli nasıl verdirilir?

Üç yol var: yeni projede create-next-app otomatik üretiyor; mevcut projede 16.3+ ile next dev çalıştırıldığında ortamda ajan algılanırsa otomatik eklenip güncelleniyor; ağ üzerinden erişmek isteyen araçlar için her doküman sayfasına .md eklemek ya da Accept: text/markdown header'ı göndermek Markdown sürümü döndürüyor.

Sürüm-eşleşmeli doküman halüsinasyonu bitirir mi?

Tamamen bitirmiyor, azaltıyor. Next.js kendi ölçümlerine göre ajanların paketli dokümanı okuyunca "daha iyi" performans gösterdiğini söylüyor ve bunu nextjs.org/evals'taki benchmark sonuçlarıyla destekliyor — ama bu "sıfır hata" değil, ölçülebilir bir iyileşme iddiası. Mimari kararlar ve iş mantığı yorumlaması hâlâ ajanın muhakemesine bağlı kalıyor.

agentRules: false ile --no-agents-md aynı şey mi?

Hayır, iki ayrı mekanizma. --no-agents-md, create-next-app ile yeni proje kurarken dosyaların hiç oluşturulmamasını sağlayan bir bayrak. agentRules: false ise next.config.ts içinde durur ve mevcut bir projede next dev'in AGENTS.md/CLAUDE.md dosyalarını otomatik yazmasını/güncellemesini kapatır.

Bu otomasyon hangi ajanlarla çalışıyor?

Next.js'in resmi dokümanına göre Claude Code, Codex, Cursor ve GitHub Copilot dahil çoğu AI kodlama ajanı, oturum başında projedeki AGENTS.md dosyasını otomatik okuyor — ayrıca bir talimat vermene gerek kalmıyor.

Sonuç

Next.js 16.3'ün AGENTS.md otomasyonu, "ajan eski API öneriyor" sorununu kökten değil ama pratik ve ölçülebilir bir şekilde küçültüyor: doküman artık kurulu sürümle birlikte geliyor, next dev bunu senin için bir dosyaya bağlıyor, ajan da zaten o dosyayı otomatik okuyor. Bunun yanına Cache Components ve Instant Navigations gibi 16.3'ün diğer büyük değişikliklerini ve Edge Runtime'dan Node.js'e geçişi de eklersen, ajanın senin projenin gerçek durumuyla konuşması daha da kolaylaşıyor.

Bu mekanizmanın oturduğu daha geniş zemini görmek istersen MCP (Model Context Protocol) rehberimize ve MCP'nin genel AI entegrasyonundaki yerine bakabilirsin; ajanın hangi Skill/MCP/hook kombinasyonunu ne zaman seçeceğini bu karşılaştırmada işledim. Ama unutma: doğru doküman, doğru mimari kararın yerine geçmiyor — o adım için hâlâ Plan Mode gibi bir ara durağa ihtiyacın var.

Kaynaklar

• Next.js 16.3 — resmi duyuru — "Versioned docs for AI agents" özelliğinin ve next dev'in AGENTS.md bloğu yazdığının birincil kaynağı.
• Next.js 16.3 AI improvements — first-party Skill'ler, Agent Browser, küçültülmüş MCP sunucusu ve docs-as-Markdown detayları.
• Next.js — AI Agents rehberi — paketli doküman yolu, create-next-app davranışı, agentRules opt-out ve framework MCP araçlarının resmi dokümantasyonu.
• agents.md — resmi format spesifikasyonu — AGENTS.md formatının tanımı, "en yakın dosya kazanır" kuralı ve ekosistem kökeni.
• npm registry — next paketi — sürüm/tarih doğrulaması (23 Eylül 2026 itibarıyla latest 16.3.6; 16.4 yalnız canary).