# Claude Code ile SvelteKit Projelerinde Verimli Çalışma

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

SvelteKit projelerinde Claude Code ile çalışmak için CLAUDE.md ayarları, doğru promptlar, test ve doğrulama döngüsü, sık yapılan hatalar ve çoklu ajan kullanımı.

**Kısaca:**

- CLAUDE.md içinde build, test ve lint komutlarıyla SvelteKit klasör kurallarını tanımlayın; ajan doğru bağlamla başlasın.
- Her görevi planla, küçük adım at, testleri çalıştır ve diff’i incele; form actions ve load fonksiyonlarında tuzakları erken yakala.
- Birden fazla Claude Code ajanını ayrı git worktree’lerde paralel çalıştırıp otomatik kod incelemesi ve checkpoint ile riski azaltın.

SvelteKit projesinde [Claude Code](/ajanlar/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:

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

| Dosya | Ne istenir? |
|---|---|
| `src/routes/**/+page.server.ts` | load ve actions tipleri, serileştirme, yönlendirme |
| `src/routes/**/+server.ts` | HTTP durum kodu, başlık, gövde formatı |
| `src/lib/**` | Vitest ile saf fonksiyon ve bileşen testi |
| `e2e/**` | Playwright ile kritik kullanıcı akışı |

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

## Sık sorulanlar

**Claude Code’u SvelteKit projesinde nasıl başlatırım?** Proje klasöründe terminalde claude yazın. Başlatmadan önce kök dizine CLAUDE.md ekleyin ve içinde build, test, lint komutlarıyla SvelteKit klasör kurallarını tanımlayın.

**Claude Code SvelteKit form action’larını ve load fonksiyonlarını anlayabiliyor mu?** Evet, +page.server.ts, +page.ts ve +server.ts dosyalarını birlikte okuyup form actions, load ve redirect akışını izleyebilir. Yine de sunucu/istemci sınırını ve serileştirme kurallarını prompt içinde hatırlatmak gerekir.

**CLAUDE.md içine SvelteKit için neler yazmalıyım?** Build, test, lint ve tip kontrolü komutlarını; src/routes altındaki dosya sorumluluklarını; sunucu kodunun yalnızca +server.ts, +page.server.ts ve $lib/server altında kalacağını; istemciye gönderilen verinin serileştirilebilir olması gerektiğini ekleyin.

**Claude Code SvelteKit projesinde Vitest ve Playwright testlerini çalıştırabilir mi?** Evet, package.json içinde tanımlı script adlarını kullanır. npm run test:unit ve npm run test:e2e komutlarını çalıştırıp hataları okuyabilir; ancak çıktıyı siz de görmeli ve düzeltmelerin test edildiğini 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/