Cursor Agent ile Nuxt Geliştirme: Pratik Kılavuz

Cursor Agent, Nuxt projelerinde terminalden cursor-agent komutuyla çalışan bir kodlama ajanıdır. Nuxt’un dosya tabanlı yönlendirmesi, server/ rotaları, composable’ları ve Nitro/Vitest altyapısıyla uyumlu çalışır; proje talimatlarını AGENTS.md veya .cursor/rules dosyalarından okur. Bu rehberde, ajanı Nuxt’a özel kurallarla nasıl yapılandıracağınızı, hangi görevlerde güvenle kullanacağınızı ve hangi tuzaklara dikkat edeceğinizi pratik örneklerle anlatıyorum.

Cursor Agent neden Nuxt işine uygun?

Cursor Agent, proje kökündeki bağlam dosyalarını okuyarak Nuxt’un konvansiyonlarına hızla adapte olur. pages/ altında dosya oluşturduğunda otomatik route üretildiğini, server/api/ altındaki dosyaların Nitro handler’larına dönüştüğünü ve composables/ içindeki use ile başlayan dosyaların auto-import edildiğini bilir. Ajan, Vue SFC’lerde <script setup> kullanımını, useFetch ve useAsyncData gibi Nuxt composable’larını ve defineEventHandler yapısını tanır. Ayrıca pnpm test, pnpm lint ve pnpm build gibi komutları kendisi çalıştırıp çıktıyı yorumlayabilir. Cursor Agent’ın genel kullanımı için Cursor Agent sayfasına bakabilirsiniz.

Projeyi ajan için hazırlama: AGENTS.md ve .cursor/rules

Ajanın doğru kararlar vermesi için proje bağlamını açıkça yazmalısınız. AGENTS.md dosyasını proje köküne koyun veya .cursor/rules altına kural dosyaları ekleyin. Nuxt projesi için komutları, klasör yapısını ve Nuxt’a özgü kuralları belirtin. Aşağıdaki örnek, gerçek bir Nuxt projesinde işe yarar bir başlangıçtır:

# AGENTS.md

## Komutlar
- Kurulum: `pnpm install`
- Geliştirme: `pnpm dev`
- Test: `pnpm test` (Vitest)
- Lint: `pnpm lint`
- Build: `pnpm build`

## Klasör yapısı
- `pages/` dosya tabanlı rotalar; yeni sayfa eklerken mevcut düzeni koru.
- `server/api/` Nitro rotaları; sadece `server/` içinde sunucu kodu yaz.
- `composables/` otomatik import edilir; `use` ile başlayan dosya adları kullan.
- `components/` otomatik import edilir; PascalCase isimlendir.

## Kurallar
- Her yeni composable için `composables/` altında tek sorumluluklu bir dosya oluştur.
- Sunucu rotalarında `event` parametresini doğru kullan; hata durumunda `createError` fırlat.
- Vue SFC'lerde `<script setup>` kullan; Nuxt 3 konvansiyonlarına uy.
- Testlerde `@nuxt/test-utils` kullan; her yeni server route için en az bir Vitest testi yaz.

Bu dosya, ajanın Nuxt’un otomatik import ve dosya tabanlı yönlendirme davranışını göz ardı etmesini engeller. Ayrıca test ve lint komutlarını bilmesi, her değişiklikten sonra doğrulama yapmasını sağlar.

Çalışma döngüsü ve örnek komutlar

Ajanla verimli çalışmak için planla, küçük adımlarla uygula, testleri çalıştır ve diff’i incele döngüsünü kullanın. Tek seferde büyük bir refactor istemek yerine, görevi küçük parçalara bölün. Her adımdan sonra git diff ile değişiklikleri gözden geçirin ve testleri çalıştırın. Bu döngüyü daha geniş bir perspektifle Vibe coding nasıl yapılır? Güvenli bir iş akışı yazısında ele aldık.

Nuxt projelerinde sık kullanılan örnek komutlar:

• “pages/ altında urunler/[id].vue sayfası oluştur ve useFetch ile server/api/urunler/[id].get.ts rotasından veri çek. Loading ve error state’lerini ekle.”
• “server/api/sepet.post.ts rotasına istek gövdesi doğrulaması ekle; geçersiz veride 422 dön.”
• “Mevcut useAuth composable’ına logout fonksiyonu ekle ve server/api/auth/logout.post.ts rotasını yaz; ardından ilgili testleri çalıştır.”
• “pages/index.vue sayfasındaki ürün listesini server/api/urunler.get.ts’den çekecek şekilde refactor et ve mevcut Vitest testlerini güncelle.”
• “Projede pnpm lint hatalarını düzelt ve pnpm test ile tüm testlerin geçtiğini doğrula.”

Her komuttan sonra ajanın ürettiği kodu inceleyin; özellikle sunucu rotaları ve composable’larda hata yönetimi ile SSR/CSR sınırlarına dikkat edin.

Nuxt’ta iyi gittiği görevler ve dikkat edilecek tuzaklar

Aşağıdaki tablo, ajanın güçlü olduğu alanları ve Nuxt’a özgü riskleri özetler:

Ajan çoğu zaman Nuxt’un konvansiyonlarına uyar ancak karmaşık SSR/CSR geçişlerinde, özellikle üçüncü taraf kütüphanelerle client-only kullanımı gerektiğinde hata yapabilir. Sunucu rotalarında event.context veya useRuntimeConfig kullanımı gibi Nitro detaylarını gözden geçirin.

Nuxt’ta test ve doğrulama

Ajanın ürettiği kodu doğrulamak için testleri manuel olarak da çalıştırın. pnpm test komutu Vitest’i çalıştırır; @nuxt/test-utils ile yazılmış testler Nuxt ortamını başlatır. Ajan, test çıktısını analiz edip hataları düzeltebilir ancak test kapsamını siz belirlemelisiniz. Sunucu rotalarını doğrulamak için node .output/server/index.mjs ile build edilmiş sunucuyu başlatıp curl veya fetch ile istek atın; ajan bunu da yapabilir. Ayrıca pnpm lint ve pnpm build komutlarını ajanın her değişikliğinden sonra çalıştırarak tip hatalarını ve derleme sorunlarını erken yakalayın. Özellikle Nitro build’i sırasında server/ klasöründeki hatalar ortaya çıkar; ajan bu adımı atlayabilir.

Birden fazla ajanı AgentVera ile yönetme

AgentVera, Cursor Agent gibi CLI ajanlarını aynı pencerede gerçek terminal panelleriyle yan yana çalıştırır. Nuxt projesinde farklı özellikleri ayrı git worktree’lerde geliştirmek, dosya çakışmalarını önler. Her ajan turu bittiğinde ikinci bir model kodu otomatik inceler ve bulguları file:line ile gösterir; bu, Nuxt’a özgü hataları erken yakalar. Checkpoint’ler sayesinde bozuk bir değişiklik tek tıkla geri alınabilir. Token bütçeleri ise maliyeti kontrol altında tutar. Daha fazla bilgi için Paralel kodlama ajanları için en iyi araçlar (2026) sayfasına bakabilirsiniz.

Sonuç

Cursor Agent, Nuxt projelerinde doğru kurallar ve doğrulama disiplini ile ciddi zaman kazandırır. AGENTS.md dosyasını baştan hazırlayın, görevleri küçük parçalara bölün, testleri ve build’i asla atlamayın. Ajanın ürettiği kodu her zaman diff üzerinden inceleyin; özellikle sunucu rotaları ve SSR sınırlarında Nuxt’a özgü hataları kendiniz doğrulayın. Böylece ajan, güvenilir bir çift programcı gibi çalışır.