Cursor Agent ile Next.js projelerinde hızlı geliştirme

Next.js projesinde terminal üzerinden cursor-agent komutuyla başlattığınız Cursor Agent, proje kökündeki AGENTS.md veya .cursor/rules dosyalarındaki talimatları okuyarak değişiklik yapar. Bu rehber, App Router ve Pages Router bilen geliştiriciler için ajanı planlama, test ve diff inceleme ile güvenli kullanmayı gösterir. Cursor Agent’ın temel kullanımı için Cursor Agent sayfasına göz atabilirsiniz.

Cursor Agent neden Next.js işleri için uygun

Cursor Agent, editörden bağımsız bir terminal ajanı olduğu için mevcut Next.js toolchain’iyle doğrudan çalışır. package.json içindeki dev, build, lint ve test komutlarını sizin yerinize çalıştırabilir, çıktıyı okuyup hatayı düzeltebilir. Next.js projelerinde çok sayıda küçük ama birbirine bağlı kural vardır: dosya tabanlı routing, server/client component sınırları, route handler imzaları, metadata ve caching. Ajan bu kuralları proje talimatlarından ve framework’ün hata mesajlarından hızlı öğrenir; böylece her değişiklikte npx tsc --noEmit, npm run lint ve ilgili testleri çalıştırarak döngüyü kısaltır. Terminalden yönetilen akış, CI’daki aynı komutları kullandığı için sürprizleri azaltır. Cursor CLI’nin temel çalışma biçimiyle ilgili Cursor CLI nasıl kullanılır? Adım adım rehber rehberine de bakabilirsiniz.

Next.js projesini ajan için hazırlama

İlk iş, proje köküne AGENTS.md eklemek veya .cursor/rules altında kural dosyaları oluşturmaktır. Cursor Agent bu dosyaları okur; komutlar, klasör yapısı ve Next.js’e özgü kısıtlar ne kadar netse, ajan o kadar az tahmin yapar. Aşağıdaki örnek, App Router kullanan bir proje için kısa ama işlevsel bir başlangıçtır:

# AGENTS.md

## Komutlar
- Kurulum: `npm ci`
- Geliştirme: `npm run dev`
- Lint: `npm run lint`
- Test: `npm run test` (Vitest)
- E2E: `npm run test:e2e` (Playwright)
- Tip kontrolü: `npx tsc --noEmit`

## Klasör kuralları
- `src/app/` altında App Router; sayfalar `page.tsx`, layout'lar `layout.tsx`.
- Sunucu bileşenlerinde `useState`, `useEffect` veya tarayıcı API'si kullanma.
- İstemci bileşenlerinin en üstüne `"use client"` ekle; mümkünse yaprak bileşenlerde tut.
- Route handler'lar `src/app/api/` altında; her handler için request doğrulaması ve hata yanıtı yaz.
- Tipler `src/types/` altında; API yanıtları için ortak tipler kullan.

## Next.js'e özgü kurallar
- `next/link` kullan; `href` için mutlaka string veya URL object; dinamik segmentlerde doğru tipleme.
- `next/image` kullan; remote görseller `next.config` içinde tanımlanmalı.
- Metadata API'yi `generateMetadata` ile kullan; client component'lerde metadata export etme.
- Çevre değişkenleri yalnızca sunucu tarafında; `NEXT_PUBLIC_` öneki olmadan client'ta okunmaz.
- Fetch işlemlerinde `cache` ve `revalidate` seçeneklerini bilinçli ayarla; gereksiz `no-store` kullanma.

Bu dosya, ajanın npm run lint ve npx tsc --noEmit komutlarını neden çalıştırması gerektiğini de netleştirir. Pages Router kullanıyorsanız src/app/ yerine src/pages/ ve getServerSideProps, getStaticProps kurallarını aynı biçimde ekleyin. Kural dosyalarını tek tek iş alanlarına ayırmak da iyidir: örneğin AGENTS.md genel komutları, .cursor/rules/nextjs.md ise yalnızca Next.js kısıtlarını tutabilir.

Güvenli çalışma döngüsü ve örnek komutlar

Ajana doğrudan büyük bir özellik yazdırmak yerine şu döngüyü kullanın: önce plan isteyin, sonra tek bir küçük adım uygulamasını söyleyin; ardından ilgili test, lint ve tip kontrolünü çalıştırın; git diff ile değişikliği inceleyin; ancak ondan sonra sıradaki adıma geçin. Her adımda ajanın önerdiği dosyaları ve komut çıktılarını gözden geçirin. Bitişik dosyalarda değişiklik varsa git diff --stat ile kapsamı kontrol edin; gereksiz geniş diff’leri geri çevirin.

Tipik Next.js görevleri için örnek komutlar:

1. src/app/dashboard altındaki kullanıcı listesini sunucu bileşeni olarak yeniden yaz; fetch için revalidate: 60 kullan ve loading.tsx ekle. Önce planı göster, sonra değişikliği yap.
2. app/api/orders/route.ts içindeki POST handler’a basit bir request şeması doğrulaması ekle; geçersiz gövde için 400 döndür. Test eklemeyi unutma.
3. src/components/ProductCard.tsx dosyasını client component’e çevir, useState ile sepete ekleme durumu ekle; "use client" direktifini en üste koy.
4. ESLint hatasını düzelt: no-unused-vars kuralı src/lib/api.ts dosyasında iki yerde uyarı veriyor. Önce hatayı göster, sonra en küçük düzeltmeyi uygula.
5. Playwright ile /checkout sayfasının başarılı ödeme akışını test eden bir E2E testi yaz; test öncesi veri hazırlığı olmadan çalışsın.

Ajanın iyi yaptığı işler ve Next.js’e özgü tuzaklar

Cursor Agent; sunucu ve istemci bileşenlerini oluşturma, route handler yazma, form doğrulaması ekleme, TypeScript hatalarını giderme, Playwright testi yazma ve basit refaktörlerde iyi çalışır. Aşağıdaki tablo, görev seçerken kullanabileceğiniz örnekleri gösterir:

Buna karşılık ajanı en çok şu Next.js konularında yakından denetleyin:

• Server/client sınırı: sunucu bileşenine yanlışlıkla onClick veya tarayıcı API’si ekleyebilir; hydration hataları oluşur.
• Gereksiz "use client": bütün sayfayı client’a çevirip statik optimizasyonu bozabilir.
• Route handler güvenliği: şema doğrulaması, yetkilendirme ve hata durumlarını eksik bırakabilir; her handler’ı testle doğrulayın.
• Caching ve revalidate: fetch seçeneklerini yanlış kullanıp gereksiz no-store ekleyebilir veya dinamik veriyi statik sanabilir.
• Metadata ve next/head karışıklığı: App Router’da metadata’yı export const metadata veya generateMetadata ile yapması gerekir; eski next/head kullanmamalı.
• next.config ve middleware: değişiklikler build’i ve tüm istekleri etkiler; mutlaka npm run build ile test edin.

Next.js projesinde test ve doğrulama

Ajanın yaptığı her değişiklikten sonra en az şu üçünü çalıştırın: npm run lint, npx tsc --noEmit ve ilgili test komutu. Vitest veya Jest ile birim testlerini çalıştırmak hızlıdır; ajan test çıktısını okuyup küçük düzeltmeleri kendisi yapabilir. Playwright testleri daha yavaş olduğu için CI öncesi son adımda çalıştırın; ancak route handler ve sayfa akışlarını değiştiren her görevde E2E testlerini de ajanla birlikte güncelleyin.

Next.js’e özgü en önemli doğrulama npm run build komutudur. Statik üretim sırasında dinamik route parametreleri, generateStaticParams, metadata ve server component hataları burada ortaya çıkar. Ajana “build hatasını göster ve düzelt” demek yeterlidir; ancak çıktıyı kendiniz de inceleyin. Ayrıca next lint yerine projede tanımlı ESLint komutunu kullanın; Next.js’in lint kuralları bazı hataları build aşamasında da yakalar. Testleri ve komutları AGENTS.md içinde tutarsanız ajan her seferinde aynı doğrulamayı yapar.

Tek Next.js projesinde paralel ajanlar: AgentVera

Birden fazla ajanı aynı Next.js projesinde çalıştırırken en kritik ihtiyaç dosya çakışmalarını önlemek ve hataları erken yakalamaktır. AgentVera her ajanı kendi git worktree’sinde çalıştırır; böylece aynı anda App Router bileşeni, route handler ve E2E testi üzerinde paralel çalışabilirler. Ajanın sırası bittiğinde ikinci bir model kodu otomatik inceler ve bulguları file:line olarak işaretler; sunucu/istemci sınırı gibi Next.js hatalarını commit öncesi yakalar. Ayrıca her turun checkpoint’i geri alınabilir, böylece yanlış bir next.config değişikliği tek tıkla eski duruma döner.

Sonuç

Cursor Agent, Next.js projelerinde net kurallar, küçük adımlar ve sürekli doğrulama ile birlikte kullanıldığında ciddi zaman kazandırır. Proje kökündeki AGENTS.md veya .cursor/rules dosyasını eksiksiz yazın; her değişiklikten sonra lint, tip kontrolü ve testleri çalıştırın; diff’i inceleyerek sunucu/istemci sınırlarını doğrulayın. Paralel çalışmada AgentVera’nın worktree ve otomatik inceleme özellikleri, Next.js projesinin karmaşık yapısını yönetmeyi kolaylaştırır.