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

Adres: https://agentvera.dev/blog/claude-code-ile-nuxt/ · Yayın: 2026-11-01

Claude Code’u Nuxt projelerinde nasıl kullanacağınızı öğrenin: CLAUDE.md kurulumu, çalışma döngüsü, testler, dikkat edilecekler ve paralel ajan ipuçları.

**Kısaca:**

- Claude Code, Nuxt’un dosya tabanlı yönlendirme ve auto-import yapısına hızlı adapte olur.
- CLAUDE.md dosyasına Nuxt’a özel komutlar ve kurallar yazmak ajanı ciddi şekilde iyileştirir.
- Küçük adımlarla çalışıp Vitest ve nuxi typecheck ile doğrulama yapmak güvenli bir döngü oluşturur.

Claude Code, Nuxt projelerinde terminalden `claude` komutuyla başlatılan bir kodlama ajanıdır. [Claude Code](/ajanlar/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:

```markdown
# 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](/blog/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](/blog/claude-code-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.

| Alan | Claude Code iyi çalışır | Dikkat edilecekler |
|------|-------------------------|-------------------|
| Sayfa ve route | pages/ altına dosya ekleyip route oluşturur | Dinamik route adlarını yanlış parametreleyebilir |
| Server routes | server/api altında h3 handler yazar | Response döndürmeyi unutabilir; Nitro uyumsuz Node API kullanabilir |
| Composables | useFetch, useState gibi yapıları doğru kurgular | Auto-import kuralını ihlal edip gereksiz import ekleyebilir |
| SSR/istemci sınırı | onMounted gibi çözümleri önerir | client-only bileşenlerde tutarsızlık yaratabilir |

Ö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](/blog/agentvera-nasil-kullanilir/) 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.

## Sık sorulanlar

**Claude Code Nuxt projesinde hangi komutları çalıştırabilir?** Projenizde tanımlı npm script’lerini çalıştırabilir; örneğin npm run dev, npm run build, npm run lint ve npx vitest run gibi komutları kullanabilir. CLAUDE.md içinde bu komutları net belirtirseniz ajan doğru olanı seçer.

**Claude Code Nuxt auto-import’larla çalışırken hata yapar mı?** Genelde iyi çalışır ama bazen ref, computed, useFetch gibi auto-import edilenleri kendisi import etmeye çalışabilir. CLAUDE.md’ye auto-import edilenleri elle import etme kuralını eklerseniz bu risk azalır.

**Claude Code Nuxt server routes yazarken nelere dikkat etmeli?** Sunucu tarafı kodun Nitro uyumlu olması gerekir; örneğin response döndürmeyi unutmamak ve Node’a özgü API’leri dikkatli kullanmak önemlidir. Ajan, server/ altındaki dosyaların otomatik API endpoint’i olduğunu CLAUDE.md’den öğrenirse daha doğru kod üretir.

**Claude Code Nuxt’ta test yazabilir mi?** Evet, Vitest ve @nuxt/test-utils ile test dosyaları oluşturabilir. Testleri çalıştırıp hataları kendi düzeltebilir; yine de SSR ve bileşen davranışlarını siz doğrulamalısınız.

---

**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/