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

Adres: https://agentvera.dev/blog/cursor-agent-ile-nextjs/ · Yayın: 2026-11-01

Cursor Agent’ı Next.js projelerinde planlama, test ve diff inceleme ile güvenli kod üretin. App Router, route handler ve ESLint kurallarına uygun rehber.

**Kısaca:**

- Cursor Agent, Next.js projelerinde AGENTS.md kurallarıyla test ve lint komutlarını kullanarak küçük adımlarla güvenli değişiklik yapar.
- App Router, server/client component sınırları ve route handler gibi Next.js’e özgü konularda ajanı yakından denetleyin.
- Paralel ajanlar için AgentVera ile her ajanı kendi git worktree’sinde çalıştırıp diff incelemesi yapabilirsiniz.

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](/ajanlar/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](/blog/cursor-cli-nasil-kullanilir/) 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:

```markdown
# 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:

| Görev | İyi prompt |
| --- | --- |
| Sunucu bileşeni | `app/blog/[slug]/page.tsx` için `generateStaticParams` ve `generateMetadata` ekle; içerik `fs` ile okunsun. |
| Route handler | `app/api/products/route.ts` içinde GET handler’ı query parametreleriyle filtrelesin; yanıt tipini `Product[]` yap. |
| Client component | `app/cart/page.tsx` içinde sepet durumu için `useReducer` kullan; localStorage ile senkronize et. |
| Test | `src/lib/formatPrice.ts` için Vitest testi yaz; Türk Lirası ve döviz kurları için parametrik test olsun. |

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.

## Sık sorulanlar

**Cursor Agent Next.js projesinde nasıl başlatılır?** Proje klasöründe terminalden cursor-agent komutunu çalıştırın. Ajan, AGENTS.md veya .cursor/rules dosyasındaki talimatları okuyarak Next.js kurallarına uygun çalışır. İlk görevde küçük ve test edilebilir bir değişiklik isteyin.

**Cursor Agent Next.js’te sunucu bileşeni ile istemci bileşenini ayırt edebilir mi?** Evet, genellikle 'use client' direktifini ve dosya konumunu tanır, ancak yan etkiler veya tarayıcı API’leri konusunda hata yapabilir. Bu yüzden ajanın ürettiği bileşenlerin sınırlarını diff’te denetleyin ve gerekiyorsa kural dosyasında açıkça belirtin.

**Cursor Agent ile Next.js’te testleri nasıl çalıştırırım?** Ajana 'npm test' veya 'npx vitest run' gibi proje komutlarını çalıştırmasını söyleyin; test çıktısını okuyup düzeltme önerir. CI’da çalışan aynı komutları AGENTS.md içinde tanımlarsanız daha tutarlı olur.

**Cursor Agent Next.js projelerinde route handler yazabilir mi?** Evet, app/api altındaki route handler’lar için GET, POST gibi fonksiyonları üretebilir. Ancak doğrulama, hata durumları ve tip güvenliğini şablondan öteye taşımak için request şeması ve test eklemesini isteyin.

---

**AgentVera hakkında.** AgentVera, Solviera Teknoloji tarafından geliştirilen macOS, Windows ve Linux masaüstü uygulamasıdır. 18 yapay zeka kodlama ajanını (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) proje bazında, gerçek terminallerde ve kullanıcının kendi CLI kurulum ve girişleriyle yan yana çalıştırır. Ücretsiz planda sınırsız ajan vardır. İndir: https://agentvera.dev/indir/ · Fiyatlar: https://agentvera.dev/fiyatlar/