Gemini CLI ile Nuxt Projelerinde Verimli Kodlama

Gemini CLI, Nuxt projesinin kök klasöründe terminalde gemini komutuyla başlattığınız bir kodlama ajanıdır. Nuxt’un dosya tabanlı yönlendirme, server routes, composables ve Nitro katmanını dikkate alarak çok dosyalı değişiklikler üretir. Daha genel bilgi için Gemini CLI sayfasına bakabilirsiniz; bu rehber Nuxt’a özel pratik kullanımı anlatır.

Neden Gemini CLI Nuxt işlerine uygun?

Nuxt projeleri güçlü konvansiyonlara dayanır: pages/ altındaki her dosya bir route olur, server/api/ altındaki dosyalar Nitro endpoint’i olur, composables/ içindeki export’lar otomatik import edilir. Gemini CLI, proje dosyalarını ve GEMINI.md talimatlarını okuyarak bu konvansiyonlara uyum sağlar. Örneğin yeni bir sayfa eklerken sadece .vue dosyasını oluşturmakla kalmaz, ilgili useFetch çağrısını, composable’ı ve gerekirse server route’u birlikte önerir.

Ajanın asıl avantajı, Nuxt’un auto-import ve SSR/CSR ayrımını bilerek kod üretmesidir. ref, computed, useFetch, defineEventHandler gibi temel öğeler için gereksiz import eklemez. Bu da diff’lerin temiz kalmasını sağlar. Ayrıca mevcut kodu inceleyip projedeki isimlendirme ve yapıyı taklit eder; böylece ekip kod tabanına yabancı desenler sokmaz.

Elbette bu, ajanı denetimsiz bırakmak anlamına gelmez. Nuxt’un katmanlı yapısı yanlış varsayımlara açıktır; bu yüzden kural ve komutları GEMINI.md ile netleştirmek gerekir. Ajan, SSR sırasında hata ayıklamak için useState, useCookie gibi yardımcıları kullanabilir. Özellikle büyük Nuxt projelerinde route middleware, plugin sıralaması ve Nitro yapılandırması ajanın dikkat etmesi gereken noktalardır. Ajan, proje kökündeki nuxt.config.ts dosyasını inceleyerek modül ve build ayarlarını dikkate alır; bu sayede yanlış varsayımlar azalır.

Ajanın konvansiyon bilgisi, yeni ekip üyelerinin Nuxt’a alışma süresini kısaltır. Kıdemli bir geliştirici gibi davranarak aynı desenleri sürdürür.

Kurulum ve GEMINI.md hazırlığı

Proje kökünde gemini komutunu çalıştırın. Ajan, bulunduğu klasördeki GEMINI.md dosyasını otomatik okur. Bu dosyaya Nuxt’a özel komutları, klasör konvansiyonlarını ve ajanın uyması gereken kuralları yazın. Dosya kısa ve güncel olmalı; her ekip üyesi değiştirebilir. Ayrıntılı başlangıç için Gemini CLI nasıl kullanılır? başlıklı rehbere göz atabilirsiniz.

Aşağıdaki örnek, tipik bir Nuxt 3 projesi için başlangıç noktasıdır:

# GEMINI.md

## Komutlar
- dev: npm run dev
- build: npm run build
- test: npm run test
- lint: npm run lint
- typecheck: npx nuxi typecheck

## Klasör yapısı
- pages/ dosya tabanlı route
- server/api/ Nitro server routes
- composables/ otomatik import edilir, elle import etme
- utils/ saf fonksiyonlar

## Nuxt kuralları
- SSR varsayılan; yalnızca istemci gereken kısımlar için ClientOnly veya .client.vue kullan
- Veri çekerken useFetch/useAsyncData kullan, onMounted içinde fetch yapma
- Server route hatalarında createError kullan, 404/500 döndür
- Yeni composable eklerken dosya adını camelCase yap ve auto-import düzenini bozma
- Her değişiklik sonrası npx nuxi typecheck çalıştır

Bu dosyayı projeye göre uyarlayın; örneğin Pinia, i18n veya özel auth yapınız varsa ilgili kuralları ekleyin. Ajan, her oturum başında bu talimatları dikkate alır. Ayrıca dosyaya “prettier” veya “eslint” gibi araçlara ait kuralları da yazabilirsiniz; örneğin bileşen adlandırma düzeni, dosya başına tek bileşen gibi. GEMINI.md, ajanın proje hakkında “ortak akıl” edinmesini sağlar. İlk kullanımda kısa tutun, zamanla güncelleyin.

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

Ajanla çalışırken büyük görevleri tek seferde istemek yerine planla, küçük adımlara böl, testleri çalıştır ve diff’i incele. Bu döngü Nuxt’ta özellikle önemlidir çünkü auto-import, route middleware veya SSR hataları ancak küçük değişikliklerde kolay yakalanır.

Örnek akış:

1. Görevi tanımlayın, ajanın ilgili dosyaları incelemesini ve bir plan çıkarmasını isteyin.
2. Planı onaylayın, tek bir adımı uygulamasını söyleyin.
3. npm run test, npm run lint, npx nuxi typecheck komutlarını ajanın kendisinin çalıştırmasını isteyin.
4. git diff ile değişiklikleri gözden geçirin; gerekirse düzeltmeler isteyin.
5. Küçük parçalar halinde devam edin.

Aşağıdaki promptlar tipik Nuxt görevleri için başlangıç olabilir:

1. “Önce pages ve server/api klasörlerini incele, blog listesi ve detay sayfası için adım adım plan çıkar. Kod yazma.”
2. “Planın ilk adımını uygula: server/api/posts.get.ts dosyasını oluştur ve mock veri döndür. Auto-import düzenini bozma.”
3. “Oluşturduğun server route için Vitest testi yaz ve npm run test ile çalıştır. Hata varsa düzelt.”
4. “Yeni composable’ı composables/usePosts.ts olarak ekle, useFetch ile veriyi çek, SSR uyumlu olsun.”
5. “Son değişiklikleri git diff ile göster ve düzenli commit mesajı öner.”

Prompt yazarken ajanın belirsizlik yaşamaması için dosya yolunu ve beklenen davranışı net belirtin. İpuçları için Kodlama ajanları için prompt nasıl yazılır? başlıklı yazıya bakabilirsiniz.

Ajan, bazen plan adımında gereksiz ayrıntılara girebilir. Bu yüzden planı sınırlayın: “Sadece üç madde ile plan çıkar” gibi. İlk adımı uygularken de tam olarak hangi dosyayı değiştireceğini söyleyin. Böylece ajan başka dosyalara dokunmaz.

Hangi görevlerde iyi, nerelerde dikkatli olmalı

Gemini CLI, Nuxt’ta şu işlerde genellikle iyi sonuç verir:

• Yeni sayfa ve dinamik route oluşturma (pages/blog/[slug].vue gibi)
• server/api/ altında CRUD endpoint’leri yazma
• Composable ve utility fonksiyonları ekleme
• Form doğrulama ve temel state yönetimi
• Vitest ile birim testi yazma

Buna karşılık ajanın zorlandığı veya yanlış varsayım yapabileceği Nuxt’a özgü alanlar vardır:

• SSR sırasında window, document, localStorage kullanımı; ajan bazen bunları setup içinde korumasız bırakabilir.
• useFetch yerine fetch + onMounted desenine kayması; bu, SSR’da veri eksikliğine yol açar.
• Otomatik import’ları gereksiz yere açık import’a çevirmesi; çalışır ama kod tabanını kirletir.
• Nitro route middleware, server utils veya özel plugin sıralaması gibi ince ayarları yanlış anlaması.
• Dış paketlerin Nuxt uyumluluğunu kontrol etmeden bağımlılık eklemesi.

Bu yüzden ajanın ürettiği her değişiklikten sonra nuxi typecheck, npm run lint ve mümkünse npm run build çalıştırın. Diff’i inceleyip SSR’ye duyarlı kodları özellikle kontrol edin. Örneğin, onMounted içinde localStorage kullanımı SSR’da sorun çıkarmaz ancak setup içinde doğrudan erişim hataya yol açar. Ajan bazen bunu karıştırabilir. Ayrıca useCookie gibi SSR güvenli API’leri kullanmasını isteyin.

Bir de Nuxt’un plugins/ klasöründeki sıra kritiktir. Ajan, yeni bir plugin eklerken order değerini atlamayabilir. Gerekirse GEMINI.md’ye plugin kuralları ekleyin.

Test ve doğrulama

Nuxt projelerinde ajanla çalışırken doğrulama katmanını erken kurun. Vitest ve @nuxt/test-utils, hem composable hem server route testleri için yeterlidir. Ajan, test dosyalarını kendisi yazabilir; siz komutları çalıştırmasını ve hataları düzeltmesini isteyin.

Aşağıdaki tablo, ajanın değişiklik sonrası çalıştırması gereken temel komutları özetler:

Ajana şu şekilde talimat verebilirsiniz: “Değişiklikleri tamamladıktan sonra npx nuxi typecheck ve npm run test çalıştır, hataları listele ve düzelt.” Böylece doğrulama döngüsü otomatikleşir. Testleri yazarken server route’lar için $fetch veya doğrudan handler import’u kullanın; composable testlerinde SSR davranışını taklit etmek için @nuxt/test-utils kurulumunu tercih edin.

Örneğin, bir server route için ajan şu testi üretebilir:

import { describe, it, expect } from 'vitest'
import handler from '~~/server/api/posts.get'

describe('GET /api/posts', () => {
  it('mock veri döndürür', async () => {
    const response = await handler({} as any)
    expect(response).toBeDefined()
    expect(response).toHaveProperty('data')
  })
})

Bu test, Nitro handler’ının doğrudan çağrılmasıyla çalışır; böylece tam sunucu başlatmaya gerek kalmaz. Ajan, bu deseni bilir ve uygular. Ancak yine de siz testin doğru senaryoyu kapsadığını kontrol edin.

Ajan, test yazarken bazen mock’ları aşırı basitleştirebilir. Gerçek veri dönen bir endpoint için sahte veri kullanmasını isteyin; böylece testler anlamlı olur.

Birden fazla ajanı AgentVera ile yönetmek

Nuxt projesinde paralel çalışan ajanlar istiyorsanız AgentVera, her ajanın gerçek CLI aracını kendi terminal panelinde yan yana çalıştırır. Ajanlar kendi git worktree’lerinde çalışabildiği için aynı dosyaları ezme riski olmaz. Bir ajanın turu bittiğinde ikinci model otomatik kod incelemesi yapar ve bulgular file:line ile işaretlenir. Ayrıca token bütçeleri sayesinde ajan başına ve tur başına limit koyabilir, yüzde 80’de uyarı alırsınız. Bu özellikler, Nuxt’ta sayfa, composable ve server route geliştirmelerini paralel yürütürken güvenliği artırır.

Özet

Gemini CLI, Nuxt projesinde GEMINI.md ile beslendiğinde dosya tabanlı route, server API ve composable işlerini hızlandırır. Küçük adımlarla çalışın, her değişiklikten sonra typecheck, test ve diff incelemesi yapın. Ajanın SSR sınırlarını ve auto-import düzenini bozmadığından emin olun. Paralel çalışma gerektiğinde AgentVera gibi araçlarla işleri güvenli bölümlere ayırabilirsiniz.