Claude Code ile SvelteKit Projelerinde Verimli Çalışma

SvelteKit projesinde Claude Code’u verimli kullanmak için önce CLAUDE.md ile proje kurallarını netleştirin, sonra her değişikliği küçük adımlarla planlatıp test ve diff üzerinden doğrulayın. Ajan; +page, +server dosyaları, load fonksiyonları ve form actions’ı bütün olarak okuyabildiğinde CRUD işlerini hızlandırır; ancak sunucu/istemci sınırı ile serileştirme kurallarına dikkat edilmezse hata üretir. Bu rehber kurulumdan test döngüsüne ve paralel ajan kullanımına kadar uygulanabilir bir yol sunar.

Claude Code SvelteKit işlerinde neden iyi çalışır?

SvelteKit’in dosya tabanlı yönlendirmesi ve route’ların yanına gömülen sunucu/istemci dosyaları, ajan için doğal bir bağımlılık grafiği oluşturur. Claude Code; +page.svelte, +page.ts, +page.server.ts ve +server.ts dosyalarını aynı bağlamda açabilir. Böylece load ile veri yükleme, sunucu tarafında doğrulama, form submission ve redirect akışının tamamını görür. Kod üretirken yalnızca parça değil, route’un bütün yaşam döngüsünü anlamaya çalışır. Örneğin “ürünler yönetim sayfasına silme action’ı ekle” dediğinizde önce ilgili +page.server.ts dosyasını, mevcut action’ları, $lib/server altındaki veri erişim katmanını inceler; ardından projedeki fail ve redirect desenine uygun yeni bir action önerir. Bu, yazım kalitesini artırır ve kod tabanındaki mevcut pattern’lerle tutarlılık sağlar.

Ajan, SvelteKit’in TypeScript çıkarımlarını da kullanabilir: PageLoad, ActionData ve route paramlarının tiplerini doğru tahmin eder. load fonksiyonundan dönen verinin düz nesnelerden oluşması gerektiğini, Date veya Map gibi serileştirilemeyen tiplerin build sonrası hata verdiğini bilir. Bu sayede geliştiriciyi sürekli uyarmak zorunda kalmazsınız; yeter ki CLAUDE.md ile net sınırlar çizilmiş olsun.

Projeyi Claude Code için hazırlama ve CLAUDE.md

Proje kökünde claude komutunu çalıştırmadan önce CLAUDE.md dosyasını oluşturun. Ajan bu dosyayı her oturumda okur; SvelteKit bağlamında olmazsa olmazları derleyin. package.json içinde net script adları olmalı; ajan npm run ile çağırmayı öğrenir. Aşağıdaki örnek, sık kullanılan komutları, klasör kurallarını ve SvelteKit’e özgü sınırları tek sayfada toplar:

# CLAUDE.md

## Komutlar
- Geliştirme: npm run dev -- --open
- Tip kontrolü: npm run check
- Birim test: npm run test:unit
- E2E: npm run test:e2e
- Build: npm run build
- Lint: npm run lint

## Klasör kuralları
- Sayfalar src/routes altında; her route +page.svelte, +page.ts, +page.server.ts ve +server.ts içerebilir.
- Sadece sunucuda çalışacak kod +page.server.ts, +server.ts ve $lib/server altında kalır.
- Paylaşılan tipler $lib/types.ts içinde; istemciye dönen veri sadece serileştirilebilir alanlar içerir.

## SvelteKit kuralları
- load fonksiyonları await kullanır; beklenmedik hatalarda throw error(status, message) çağırır.
- form actions `export const actions = {}` biçimindedir; hata döndürürken `fail(400, { data })` kullan.
- +server.ts API route'larında doğru HTTP durum kodunu ve Content-Type başlığını döndür.
- Tarayıcı API'leri yalnızca `onMount` veya `browser` kontrolü ile kullan; SSR sırasında `window`, `localStorage`, `document`'a erişme.
- Kullanıcı doğrulama bilgisi `locals` üzerinden taşınır; +page.server.ts içinde `getUser` yardımcısıyla kontrol et.

Komutlar bloğu, ajanın hangi scriptleri koşabileceğini bilmesini sağlar; klasör kuralları istemci kodunun sunucuya sızmasını engeller; SvelteKit kuralları ise en sık yapılan hataları baştan önler. CLAUDE.md dosyasını kısa ve eyleme dönük tutun; her satır somut bir davranış kuralı belirtsin. Daha kapsamlı bir kontrol listesi için Claude Code en iyi pratikler yazısına göz atabilirsiniz. Yeni bir adapter (ör. adapter-node) veya farklı bir doğrulama kütüphanesi kullanmaya başladığınızda dosyayı güncelleyin; ajan eski kurallara göre kod üretmesin.

Çalışma döngüsü: planla, küçük adım at, testleri çalıştır, diff’i incele

Claude Code’a doğrudan büyük bir görev vermek yerine şu döngüyü kullanın: ilgili route’ları okutup akışı özetletin; plan isteyin; tek küçük adım uygulatın; testleri ve tip kontrolünü çalıştırın; son olarak git diff çıktısını inceleyin. Ajan bir adımı tamamlamadan sıradakine geçmeyin. SvelteKit’te route’a bağlı birden çok dosya aynı anda değişeceği için diff’i dosya bazında değil akış bazında okuyun. Plan aşamasında ajanın soru sormasına izin verin; “hangi doğrulama kütüphanesi kullanılıyor?”, “auth nasıl sağlanıyor?” gibi belirsizlikleri açıklığa kavuşturun.

Claude Code plan modu kullanarak önce plan yaptırıp onaylamak, yanlış yöne giden büyük değişikliklerin önüne geçer. Planı onayladıktan sonra aynı oturumda küçük diff’ler halinde uygulamasını isteyin. Aşağıdaki promptlar SvelteKit’te sık yaşanan senaryolara örnektir:

• src/routes/urunler/+page.server.ts ve +page.svelte dosyalarını incele. Önce mevcut veri akışını üç maddeyle özetle; sonra sayfalama için plan öner, kod yazma.
• Yeni bir form action ekle: src/routes/randevu/+page.server.ts içinde olustur action’ı olsun. Şemayı Zod ile doğrula, hata olursa fail döndür, başarılı olursa redirect ile /randevu/onay sayfasına git.
• src/routes/panel/+layout.server.ts içinde kullanıcı oturumunu kontrol eden bir load fonksiyonu yaz. Yetkisiz kullanıcıyı /giris sayfasına yönlendir, yetkili kullanıcının bilgisini döndür.
• src/lib/components/Tablo.svelte için Vitest testi yaz. Mock veriyle render et ve satır tıklama olayını doğrula.
• npm run check çalıştır; tip hatalarını tek tek düzelt ve her düzeltmeden sonra ilgili testi yeniden çalıştır.

Her adımın sonunda ajan size test sonuçlarını ve git diff özetini versin. Siz de değişikliği gözden geçirin; sunucu/istemci sınırı ihlallerini ve beklenmeyen veri akışlarını arayın.

SvelteKit’te iyi giden işler ve dikkat edilmesi gereken tuzaklar

Claude Code özellikle yeni route oluşturma, Zod ile form doğrulama, load fonksiyonlarını tiplendirme, hata sayfaları ve yönlendirme gibi tekrarlı işlerde iyidir. Ayrıca var olan bir sayfayı parçalara ayırıp +layout.ts içinde ortak yüklemeyi düzenleyebilir, Playwright senaryolarını sayfa yapısına göre yazabilir. Kullanıcı yetkilendirmesi, locale yönetimi ve tema değişimi gibi cross-cutting işleri de hooks.server.ts üzerinden hatasız kurgulayabilir.

Yine de şu tuzaklara dikkat edin:

• Sunucu/istemci sınırı: Ajan +page.ts içine window veya localStorage erişimi koyabilir. Mutlaka browser kontrolü veya onMount içine alınması gerektiğini prompt ile hatırlatın.
• Serileştirme: load fonksiyonundan Date, Map veya class örneği döndürmek build sonrası hata verir. DTO’lar ve düz nesneler isteyin.
• Form action ve use:enhance: Ajan formu use:enhance ile bağlarken hata mesajlarını güncellemeyi unutabilir; dönüş tipini ActionData ile açıkça modelleyin.
• Route çakışmaları: Yeni bir statik route ile dinamik route arasında çakışma oluşabilir. Ajanın planında route ağacını kontrol etmesini isteyin.
• Adapter farkları: Projede adapter-node veya adapter-static kullanılıyorsa +server.ts route’larının davranışı değişebilir; CLAUDE.md’de bu bilgiyi verin.
• Çevresel değişkenler: PUBLIC_ ön ekli değişkenler istemciye gönderilir, diğerleri yalnızca sunucuda kalır. Ajan istemci kodunda process.env kullanırsa bunun çalışmayacağını hatırlatın.
• Svelte 5 runes: $state, $derived, $effect kullanımı klasik reactive syntax’la karışabilir. Projede hangi sürümün kullanıldığını CLAUDE.md’e yazın; ajan yanlış desen kullanmasın.

SvelteKit test ve doğrulama döngüsünde Claude Code

Ajanın yalnızca ‘testler geçiyor’ demesine güvenmeyin; terminal çıktısını gösterin. SvelteKit projelerinde doğrulama genellikle üç katmandan oluşur: tip kontrolü, birim testler ve E2E. Claude Code’dan her değişiklikten sonra npm run check ile tip kontrolü yapmasını, ardından ilgili Vitest dosyalarını çalıştırmasını isteyin. Kullanıcı akışı kritikse Playwright senaryosunu da çalıştırın. Ajan hata çıktısını okuyup ilgili dosyayı düzeltmeli; düzeltmeyi tekrar test ettirmeden kapatmayın.

Claude Code test komutlarını çalıştırırken bazen Playwright’ın tarayıcı kurulumu veya ortam değişkeni eksikliği nedeniyle yanlış negatif üretebilir. Bu durumda önce npx playwright install komutunu el ile çalıştırıp sonra ajanın testleri yinelemesini sağlayın. Ayrıca testlerin izolasyonuna dikkat edin: aynı test dosyası içinde state paylaşımı varsa, ajan bu durumu gözden kaçırabilir. Her testten sonra veri tabanını veya mockları sıfırlayan bir beforeEach olması gerektiğini prompt içinde belirtin. Son olarak, ajanın git diff çıktısıyla birlikte hangi testleri çalıştırdığını ve sonuçlarını özetlemesini isteyin; böylece doğrulamayı kendiniz hızlıca teyit edersiniz.

Birden fazla Claude Code ajanını SvelteKit projesinde çalıştırma

SvelteKit projesi büyüdüğünde, route’ları ve testleri tek ajanla sırayla ilerletmek yavaşlar. AgentVera ile her Claude Code ajanı kendi gerçek terminal panelinde, ayrı bir git worktree üzerinde çalışabilir; böylece biri yeni bir form action eklerken diğeri Playwright senaryosunu paralel yazabilir. Ajan bitince ikinci bir model otomatik kod incelemesi yapar ve bulgular file:line bağlantısıyla gelir; bu, SvelteKit’teki sunucu/istemci sınırı gibi ince hataları yakalar. Checkpoint’ler sayesinde yanlış bir refactor tek tıkla geri alınabilir ve token bütçeleri SvelteKit bağlamının uzun sürdüğü oturumlarda ajanın kontrolden çıkmasını engeller.

Sonuç

Claude Code’u SvelteKit projesinde etkili kullanmanın anahtarı, projeye özgü kuralları CLAUDE.md ile vermek ve her değişikliği testlerle doğrulamaktır. Küçük adımlar, net promptlar ve dikkatli diff incelemesi ile ajan route geliştirme, form doğrulama ve test yazma işlerini ciddi biçimde hızlandırır. Sunucu/istemci sınırını sürekli hatırlatın; serileştirme ve browser guard gibi SvelteKit’e özgü kuralları CLAUDE.md’e yazın. Birden fazla işi paralel yürütmek istediğinizde AgentVera gibi worktree ve kod incelemesi destekleyen bir ortam, SvelteKit’e özgü tuzakları yönetmeyi kolaylaştırır. Uygulamayı yavaşlatan en büyük hata, ajanı denetimsiz bırakıp uzun bir görev zinciri vermektir; bunun yerine her döngüde siz de sürecin içinde olun.