Gemini CLI ile SvelteKit projeleri: pratik rehber

Gemini CLI’yi SvelteKit proje klasöründe gemini komutuyla başlattığınızda ajan dosya ağacını, package.json betiklerini ve GEMINI.md talimatlarını okuyarak route, load, form action ve test işlerinde size yardımcı olur. Bu rehber, ajanın SvelteKit’e özgü davranışlarını denetlemek ve üretken bir döngü kurmak için pratik adımları anlatır. Gemini CLI hakkında genel bilgi için Gemini CLI sayfasına, ilk adımlar için Gemini CLI nasıl kullanılır? rehberine bakabilirsiniz.

Gemini CLI neden SvelteKit işlerine uygun?

SvelteKit, dosya tabanlı routing sayesinde ajanın proje yapısını hızlı kavramasını sağlar. src/routes altındaki +page.svelte, +page.ts, +page.server.ts ve +server.ts dosyaları bir arayüz sözleşmesi gibidir; ajan, server ve client kodunu ayırt edebilir. Örneğin bir liste sayfası isteğinde load fonksiyonunun +page.server.ts içinde mi yoksa +page.ts içinde mi olması gerektiğini GEMINI.md’deki kurallara göre değerlendirir. Form action’larının actions exportu, $app/forms ve invalidateAll kullanımı gibi SvelteKit’in kendine özgü kalıplarını öğrenir. Ayrıca npm run check, Vitest ve Playwright gibi araçlarla değişikliğin doğruluğunu test etmeye yatkındır. Bu sayede ajan yalnızca kod yazmaz; route bütünlüğünü ve tip güvenliğini de gözetir. Svelte compiler’ının anlık önerileri ajanın hatalarını erken yakalamasına yardımcı olur; svelte-check çıktısı üzerinden düzeltme önerileri isteyebilirsiniz. Buna ek olarak SvelteKit’in server/client ayrımını netleştiren +page ve +server dosyaları, ajanın hangi kodu SSR sırasında çalıştıracağını, hangi kodu yalnızca tarayıcıda kullanacağını daha kolay belirlemesini sağlar.

Proje kurulumu ve GEMINI.md

Ajan başlatılmadan önce projede net bir GEMINI.md bulunması en büyük farkı yaratır. Bu dosyaya yalnızca genel kurallar değil, SvelteKit projesinin somut komutlarını ve dizin varsayımlarını yazın. package.json içindeki script’lere ek olarak GEMINI.md’de lint, format ve test araçlarının nasıl kullanılacağını belirtin. Örneğin projede ESLint ve Prettier varsa, ajanın her değişiklik sonrası npm run lint ve npm run format çalıştırmasını isteyin. Ayrıca hangi paket yöneticisinin kullanıldığını (npm, pnpm, yarn) ve SvelteKit’in hangi adaptor ile deploy edildiğini not edin; bu, adapter-node veya adapter-static arasındaki farklı runtime varsayımlarını ortadan kaldırır. GEMINI.md, ajanın aşağıdaki örnekteki gibi net talimatlarla çalışmasını sağlar:

# SvelteKit projesi için GEMINI.md

## Komutlar
- Dev: npm run dev
- Derleme: npm run build
- Tip kontrolü: npm run check
- Lint: npm run lint
- Birim test: npm run test:unit
- Uçtan uca test: npm run test:e2e
- Format: npm run format

## Dizin kuralları
- Sayfalar src/routes altındadır; her route için +page.svelte, +page.ts ve/veya +page.server.ts kullanın.
- Ortak bileşenler src/lib/components altında, server-only yardımcılar yalnızca src/lib/server altında olmalı.
- Statik varlıklar static/ altında tutulur; import etmek için $lib veya $app yollarını kullanın.

## SvelteKit'e özgü kurallar
- Veri çekme önceliği +page.server.ts veya +server.ts olmalı; client'ta fetch kullanmaktan kaçının.
- Form gönderimleri +page.server.ts içindeki actions ile yönetilir; fail() ve redirect() @sveltejs/kit'ten, enhance $app/forms'dan import edilir.
- Browser API'leri yalnızca onMount içinde veya browser kontrollü koşullarda kullanın; SSR sırasında window/document erişmeyin.
- Sunucuya özel ortam değişkenleri $env/static/private veya $env/dynamic/private ile, client'a açılacaklar $env/static/public veya $env/dynamic/public ile alınmalıdır.
- Mevcut adaptor ve route yapısını değiştirmeden çalışın.
- State yönetimi için Svelte stores kullanın; custom store'ları src/lib/stores altına koyun.
- `setContext` ve `getContext` yalnızca kurucu (constructor) içinde eşleştirilmelidir.

## Test
- Vitest için test dosyaları src/lib/__tests__ veya route'a yakın olabilir.
- Playwright testleri tests/ altında; route etkileşimleri için data-testid kullanmayı tercih edin.
- E2E testlerinden önce `npm run build` yapmayı unutmayın.

Bu dosya kısa ama nettir. Ajan, komutları doğru çalıştırmak için package.json’a bakar; GEMINI.md ise yanlış katmana kod yazmasını engeller. Örneğin src/lib/api.ts içindeki fetch çağrısını client tarafına açmak yerine, ajan src/lib/server altında tutmayı öğrenir. GEMINI.md yoksa SvelteKit’e özgü bu tür kararlar tahmine kalır ve sık sık SSR hataları veya bundle boyutu artışı yaşanır.

Çalışma döngüsü: planla, küçük adımla, test, diff

Gemini CLI ile en verimli döngü, büyük bir isteği tek seferde vermek yerine görevi parçalara bölmektir. Önce ajanın plan yapmasını isteyin; ardından yalnızca planı uygulamasını, testleri çalıştırmasını ve diff çıktısını göstermesini söyleyin. Her adımdan sonra git diff ile değişiklikleri inceleyin. Özellikle +page.server.ts ve +page.ts arasındaki taşımalarda serialization hatalarını kontrol edin. Prompt yazımı için genel kalıpları Kodlama ajanları için prompt nasıl yazılır? yazısında bulabilirsiniz.

Tipik SvelteKit görevleri için örnek promptlar:

• “src/routes/checkout/+page.server.ts içine actions.default ekle; form verilerini bir schema ile doğrula, hata varsa fail(400, { errors }) döndür, başarılıysa redirect(303, ‘/success’) yap.”
• “Mevcut src/routes/products/+page.ts içindeki load fonksiyonunu +page.server.ts’e taşı; fetch’i server tarafında yap ve dönen veriyi döndür. Client bundle’a API URL’si sızmasın.”
• “src/lib/server/products.ts oluştur ve ürün listeleme sorgusunu oraya taşı; +page.server.ts load fonksiyonu bu fonksiyonu çağırsın. Unit test ekle.”
• “Vitest ile src/lib/utils/price.spec.ts yaz; fiyat formatlama ve kdv hesaplama fonksiyonlarını test et. npm run test:unit çalıştır ve başarısız testleri düzelt.”
• “Playwright testi ekle: /login sayfasında boş form gönderilince hata mesajı görünüyor mu ve form action fail durumları doğru mu kontrol et.”
• “src/routes/api/products/+server.ts oluştur; GET isteğinde ürünleri JSON döndür, limit ve offset query parametrelerini destekle. Hata durumunda 400 veya 500 döndür.”
• “Mevcut src/routes/dashboard/+layout.ts içindeki kullanıcı kontrolünü +layout.server.ts’e taşı; redirect kullanarak giriş yapmamış kullanıcıları /login’e yönlendir.”

Bu promptlar ajanın işi anlamasını kolaylaştırır; her seferinde yalnızca bir katmanı veya bir route’u hedefleyin. Planlama aşamasında ajana “ilk olarak hangi dosyaları değiştireceğini ve neden” sorun; onay verdiğinizde uygulamaya geçsin. Uygulama sonrası npm run check çalıştırmasını ve hataları düzeltmesini isteyin. Böylece döngü 5-10 dakikada tamamlanır ve geri dönüşler kısa olur.

SvelteKit’te güçlü olduğu işler ve dikkat edilecekler

Ajan, yeni route ekleme, load fonksiyonu yazma, form action oluşturma, +server.ts endpoint dönüştürme ve mevcut kodun server/client ayrımını düzeltme gibi iyi tanımlanmış işlerde hızlıdır. Örneğin bir ürün listesi sayfası için +page.server.ts, load ve +page.svelte üçlüsünü birlikte oluşturabilir. Test yazmak da güçlü olduğu alanlardandır; Vitest betiği eklemek için izole fonksiyonları tespit eder. Aynı şekilde Svelte 5 runes API’si ($state, $derived) kullanımı istenirse ajan bu dönüşümü uygulayabilir, ancak bu tür kapsamlı geçişlerde manuel inceleme şarttır.

Dikkat edilmesi gereken yerler SvelteKit’e özgüdür:

• Server-only kodun client’a sızması: $lib/server dışında kalan importlar yanlışlıkla client bundle’a girebilir. Ajanın her değişiklik sonrası npm run build çalıştırmasını isteyin.
• SSR varsayımı: Ajan bazen window veya document kullanabilir; bu, tarayıcıda değil server’da çalışan load sırasında patlar. onMount veya browser kontrolü eklemesini hatırlatın.
• Form action dönüş tipleri: fail ve redirect importları karışabilir; action’un döndürdüğü errors nesnesinin sayfada doğru okunması gerekir.
• invalidateAll veya invalidate kullanımı: Ajan bazen güncel veri için invalidateAll’ı atlar; form sonrası listeyi güncellemek istiyorsanız bunu prompt’a ekleyin.
• Adapter ve environment değişkenleri: Ajan, varsayılan adapter-node dışında bir yapıyı varsayabilir. GEMINI.md’de mevcut adapter’ı belirtin ve ortam değişkeni yönetimini netleştirin.
• $app/navigation ve $app/stores importları: Ajan bazen page store’unu server tarafında kullanmaya çalışır; bu yalnızca client’ta geçerlidir. Sunucu tarafında locals veya url parametresini kullanmasını isteyin.
• Svelte component’lerinde reaktivite: Ajan, bir değişkene yeniden atama yapması gerektiğinde let kullanmayı unutabilir veya yanlış yerde $: bloğu oluşturabilir. Basit bir kullanıcı arayüzü değişikliğinde bile diff’i gözden geçirin.
• +layout dosyalarındaki load fonksiyonlarında dönen veri türü: Layout load’ları, child sayfalar için de çalışır; ajan bazen bu veriyi gereksiz yere yeniden fetch eder. Gereksiz request’leri önlemek için setContext veya data geçişini yönlendirin.

SvelteKit’te test ve doğrulama

Gemini CLI’ya her zaman “testleri çalıştır, çıktıyı rapor et” komutunu verin. SvelteKit’te npm run check ile tip hatalarını, npm run test:unit ile Vitest birim testlerini, npx playwright test ile uçtan uca testleri doğrularsınız. Aşağıdaki tablo, hangi katmanda hangi doğrulamanın anlamlı olduğunu gösterir.

Ajan test çıktısını yorumlayıp düzeltir; ancak testlerin gerçekten çalıştığını doğrulamak için komut çıktısını isteyin. Playwright testlerinde ajan, selector yerine data-testid eklemeyi öğrenmelidir. GEMINI.md’ye “Playwright testleri için data-testid kullan” notunu eklemek seçici hatalarını azaltır. Vitest için ajanın src/lib altındaki saf fonksiyonlara odaklanmasını sağlayın; Svelte component testleri istiyorsanız @testing-library/svelte gibi bir kütüphane kullanılıp kullanılmadığını GEMINI.md’ye yazın. Ayrıca ajanın test dosyalarını doğru konumda oluşturduğundan emin olun; Vitest config dosyasında include pattern’ini kontrol edin. Son olarak, tüm testler geçtikten sonra npm run build çalıştırarak production build’de SSR hataları olmadığını doğrulayın.

Aynı projede birden fazla ajan: AgentVera

Birden fazla Gemini CLI oturumunu aynı SvelteKit projesinde çalıştırmak istediğinizde AgentVera kullanışlıdır. AgentVera masaüstü uygulaması, gerçek komut satırı ajanlarını tek pencerede yan yana çalıştırır; her ajan kendi git worktree’sinde ilerleyebildiği için iki farklı route üzerinde aynı anda çalışmak dosyaları ezmez. Bir ajanın turu bitince ikinci model kodunu inceler ve bulguları dosya:satır olarak gösterir; bu, +page.server.ts’ye yanlışlıkla client-only kod sızmasını yakalamakta iyidir. Checkpoint’ler sayesinde hatalı bir route değişikliği tek tıkla geri alınabilir ve oturum adım adım izlenebilir. Günlük token bütçesi ise uzun test döngülerinin kontrolden çıkmasını önler.

Sonuç

Gemini CLI’yi SvelteKit’te etkili kullanmanın anahtarı, GEMINI.md ile proje kurallarını netleştirmek, küçük adımlarla plan yapmak ve her değişikliği test ile doğrulamaktır. Böylece route, load, form action ve endpoint işleri hızlanır; düzeltme yükü azalır. Ajanı bir asistan olarak değil, yönlendirmeye ihtiyaç duyan bir geliştirici gibi düşünün; net talimatlar ve kapsamlı test altyapısı onun en büyük gücünü ortaya çıkarır. Zaman içinde GEMINI.md’yi projenin alışkanlıklarına göre güncelleyin; böylece ajan her yeni oturumda daha isabetli kod üretir. SvelteKit’in dosya tabanlı mimarisi ve güçlü test araçları, Gemini CLI ile birleştiğinde rutin geliştirme görevlerini büyük ölçüde hızlandırır.