Claude Code ile Nuxt Projelerinde Verimli Çalışma Rehberi

Claude Code, Nuxt projelerinde terminalden claude komutuyla başlatılan bir kodlama ajanıdır. Claude Code Nuxt’un dosya tabanlı routing, server routes ve composable yapısını okuyup düzenleyebilir; siz de CLAUDE.md ve doğru komutlarla onu projeye hizalarsınız. Bu rehber, ajanı Nuxt’ta verimli kullanmak için pratik bir akış sunar.

Neden Claude Code Nuxt işlerine uygun?

Nuxt’un en büyük avantajı kurallara dayalı yapıdır: pages/, components/, composables/, server/ klasörleri bellidir. Claude Code bu sözleşmeleri çözümleyip hızlıca yeni sayfa, composable veya API endpoint ekleyebilir. Ayrıca auto-import edilen Vue ve Nuxt fonksiyonları sayesinde dosya başına import kalabalığı olmadığından ajanın ürettiği kod daha derli toplu olur. Nitro tabanlı server routes’ta ise tek dosyayla hem API yazıp hem de tip güvenliğini koruyabilirsiniz. Ajan, nuxt.config.ts, modüller ve runtime config’i de okuyabildiği için yalnızca UI değil, tam stack işler yapabilir. Bu da onu Nuxt projelerinde genel amaçlı bir yardımcıdan öteye taşır.

Örneğin, ajan pages/blog/[slug].vue dosyasını oluşturduğunda route parametresini useRoute().params.slug ile okuyup veriyi useAsyncData ile çekmeyi önerir. Server tarafında server/api/posts/[id].get.ts gibi bir handler’ı h3’ün getRouterParam ile yazabilir. Üretilen kod Nuxt’un soyutlamalarıyla uyumlu olduğu için merge sonrası sürpriz yaşanmaz.

Nuxt projesini ajan için hazırlama: CLAUDE.md

Claude Code her oturumda proje kökündeki CLAUDE.md dosyasını okur; bu yüzden Nuxt’a özel talimatları oraya koymak en yüksek getirili adımdır. Dosyada komutlar, klasör sözleşmeleri, test/lint koşulları ve Nuxt’a özgü kurallar olmalı. Ajan bu dosyayı her değişiklik öncesi referans alır; siz de proje yapısı değiştikçe güncelleyin. Örnek:

# CLAUDE.md

## Komutlar
- Dev: npm run dev
- Build: npm run build
- Lint: npm run lint
- Test: npx vitest run
- Tip kontrolü: npx nuxi typecheck

## Klasör yapısı
- pages/ dosya adı route olur; yeni sayfa buraya.
- server/api/ içindeki dosyalar otomatik endpoint olur; her handler mutlaka bir response döndürür.
- composables/ altına yazılanlar auto-import edilir; elle import ekleme.

## Nuxt kuralları
- ref, computed, useFetch, useRuntimeConfig gibi auto-import edilenleri elle import etme.
- İstemci bileşenlerinde window, document kullanma; gerekirse onMounted içinde kullan.
- Server route'larda yalnızca Nitro uyumlu API'ler kullan; Node'a özgü çağrılarda dikkatli ol.
- Her yeni özellik için en az bir Vitest testi yaz.

Bu dosyayı kısa ve net tutun; ajan belirsiz talimatlardan çok somut kurallarla beslenir. Kod bloğundaki her satır ajanın hata payını düşürür. Örneğin ‘handler mutlaka response döndürür’ kuralı, server route’larda boş response bırakma hatasını engeller. ‘Auto-import edilenleri elle import etme’ kuralı ise gereksiz import satırlarını ve tip hatalarını azaltır. Ek olarak .env dosyalarındaki değişkenlerin yalnızca sunucuda erişilebilir olduğunu, public değerlerin runtimeConfig üzerinden kullanılacağını da belirtebilirsiniz. Claude Code en iyi pratikler sayfasındaki kontrol listesi de Nuxt’a uyarlanabilir.

Çalışma döngüsü: planla, küçük adım, test et, diffi incele

Claude Code’a büyük görev vermek yerine plan modunda ilerleyin. Plan modu ile önce ajanın önerdiği dosya listesini görebilirsiniz. Değişikliği tarif edin, öneriyi onaylayın; sonra tek bir küçük değişiklik yaptırın, testleri çalıştırın ve git diff ile neyin değiştiğine bakın. Nuxt’ta auto-import hataları ve SSR eşleşmeleri genellikle küçük parçalarda daha kolay yakalanır.

Örnek Nuxt görev prompt’ları:

• server/api/tasks.post.ts içinde gelen JSON’u doğrulayan ve hata durumunda 400 döndüren bir handler yaz; h3’ün readBody ve createError fonksiyonlarını kullan.
• pages/index.vue içindeki ürün listesini useFetch ile çekip yükleniyor ve hata durumlarını gösteren bir bileşene ayır.
• composables/useAuth.ts içinde login, logout ve kullanıcı state’ini yöneten, token’ı cookie’de saklayan bir composable oluştur.
• Vitest ile pages/index.vue için temel render testi yaz ve geçmesini sağla; @nuxt/test-utils kullan.
• SSR sırasında window is not defined hatası veren kodu bul ve onMounted içine al; değişikliği açıkla.

Ajan bir öneri yaptığında, diff’i incelemeden onaylamayın. Özellikle Nuxt’ta dosya adı değişikliği route’u etkiler; pages/ içindeki bir dosyanın yeniden adlandırılması eski URL’leri kırar. Bu yüzden ajanın önerdiği dosya listesini ve değişiklik özetini görüp, yalnızca amaçladığınız kapsamda olduğundan emin olun. Gerekirse ‘Bu değişikliği yapmadan önce hangi route’lar etkilenir?’ gibi sorular sorun. Her başarılı testten sonra git commit atın; böylece sonraki adımda sorun çıkarsa dönmesi kolay olur.

Hangi Nuxt görevlerinde iyi, nerelerde dikkatli olunmalı

Claude Code, tekrarlayan ve kural tabanlı işlerde güçlüdür. Yeni sayfa, API endpoint, composable oluşturmak, refactor ve test yazmak hızlıdır. Ancak Nuxt’un büyüsü bazen ajanı yanıltabilir.

Özellikle useAsyncData ve useFetch kullanımında ajan, verinin hem sunucu hem istemcide çalıştığını unutup yalnızca istemci varsayımıyla kod yazabilir. Server route’larda ise hata durumlarını createError ile döndürmek yerine sessizce boş response bırakabilir. useRuntimeConfig içindeki değerlerin yalnızca sunucuda veya public alanlarda erişilebilir olduğunu karıştırabilir. Bu yüzden her diff’te bu noktalara bakın; ajanın ürettiği kodu Nuxt runtime’ının gerçekleriyle karşılaştırın.

Ajan ayrıca middleware, plugin ve kompozit bileşen oluşturmada da başarılıdır. Örneğin middleware/auth.ts yazarak sayfa erişimini koruyabilir, plugins/init.ts ile global yardımcılar enjekte edebilir. Ancak ajanın önerdiği kodu doğrudan kullanmaktan kaçının; her zaman Nuxt’un çalışma zamanı kurallarını kontrol edin. Özellikle useAsyncData çağrılarında key parametresinin benzersiz olması gerekir; ajan bazen aynı anahtarı tekrar kullanabilir. Ayrıca client-only kodları yanlışlıkla sunucuya kaçırabilir; import.meta.client veya process.client kontrolleri eklemeyi önerin.

Test ve doğrulama

Nuxt’ta ajanla çalışırken doğrulama katmanı şart. Claude Code test yazabilir ve çalıştırabilir; siz de komutları netleştirin. Standart döngüde şunları çalıştırın:

• npx vitest run ile birim ve bileşen testlerini koşturun.
• npx nuxi typecheck ile auto-import ve tip hatalarını yakalayın.
• npm run lint ile stil ve yapı hatalarını temizleyin.
• npm run build ile Nitro server ve SSR çıktısını doğrulayın; bazı hatalar yalnızca build’de ortaya çıkar.

Ajan testleri kendi başlattığında başarısız olanları düzeltmeye çalışır; ancak yalnızca testi geçirmek için davranışı değiştirmesine izin vermeyin. Testlerin niyetini koruyun ve git diff sonrası test dosyalarını da inceleyin. Server route testlerinde $fetch yerine handler’ı doğrudan çağırmak daha güvenilir olabilir; hangisinin kullanılacağını CLAUDE.md’ye yazabilirsiniz. Bileşen testlerinde @nuxt/test-utils ile mountSuspended gibi yardımcıları kullanmak SSR davranışını daha iyi yansıtır; ajanın bu yardımcıları bilmesini sağlayın.

Vitest’i Nuxt projesine eklerken vitest.config.ts dosyasında @nuxt/test-utils eklentisini kullanın; bu, Nuxt ortamını ve auto-import’ları testlere taşır. Bileşen testlerinde mountSuspended ile SSR davranışını simüle edin. Sunucu route testlerinde $fetch yerine handler fonksiyonunu doğrudan çağırmak daha izole ve hızlıdır. Ajan test yazarken vi.mock kullanarak useFetch gibi çağrıları mock’layabilir; ancak mock’lanan verinin gerçek API şemasına uygun olduğundan emin olun. Ayrıca npx nuxi typecheck komutunu her değişiklik sonrası çalıştırmayı alışkanlık haline getirin; çünkü auto-import hataları yalnızca tip seviyesinde ortaya çıkabilir.

Birden fazla ajanı aynı Nuxt projesinde çalıştırma: AgentVera

Nuxt’ta paralel işler çoğaldığında tek Claude Code oturumu darboğaz olur. AgentVera, Claude Code ve diğer CLI ajanlarını gerçek terminal panellerinde yan yana çalıştıran bir masaüstü uygulamasıdır. Nuxt için en kritik katkısı, her ajanı kendi git worktree’sinde koşturarak dosya çakışmalarını önlemesidir; böylece biri server route yazarken diğeri composable’ı refactor edebilir. Ajanın turu bitince ikinci bir model otomatik kod incelemesi yapar ve bulguları file:line ile işaretler; auto-import veya SSR hatalarını merge öncesi yakalarsınız. Checkpoint özelliği sayesinde yanlış bir değişikliği tek tıkla geri alıp oturumu adım adım tekrar oynatabilirsiniz. Token bütçeleri ise uzun Nuxt görevlerinde maliyeti ve süreyi kontrol altında tutar. Daha fazlası için AgentVera nasıl kullanılır sayfasına bakın.

Sonuç

Claude Code’u Nuxt projelerinde etkili kullanmanın yolu, proje sözleşmelerini CLAUDE.md’ye işlemek ve küçük adımlarla doğrulama yapmaktır. Ajanı iyi beslediğinizde sayfa, composable ve server route üretiminde ciddi hız kazanırsınız; yine de auto-import ve SSR/istemci sınırını diff’lerde denetlemek sizin sorumluluğunuzda kalır. Testleri ve build’i döngünün parçası yaparsanız, Nuxt projelerinde ajanla güvenli bir çalışma temposu yakalarsınız.