Cursor Agent ile SvelteKit Projelerinde Verimli Çalışma

Cursor Agent, SvelteKit projenizin kökünde cursor-agent komutuyla başlar ve AGENTS.md ya da .cursor/rules dosyasındaki yönergeleri okuyarak çalışır. Bu rehberde +page, +server, load fonksiyonları, form actions, Vitest ve Playwright ile güvenli bir döngüyü nasıl kuracağınızı gösteriyorum. Cursor Agent hakkında daha genel kullanım için Cursor Agent sayfasına bakabilirsiniz.

Cursor Agent SvelteKit için neden uygun?

SvelteKit’in dosya tabanlı yönlendirmesi ve aynı klasörde yan yana duran +page.svelte, +page.server.ts, +server.ts dosyaları, ajanın bağlamı kolayca görmesini sağlar. Cursor Agent bir route’u değiştirirken hem sunucu tarafını hem istemci tarafını birlikte ele alabilir; load fonksiyonunda veriyi çekip +page.svelte içinde render etmek gibi bütünsel değişiklikleri tek seferde yapabilir. Form actions ve API endpoint’leri açık export’lar olduğundan, ajan neyin sunucuda çalıştığını kolayca anlar. SvelteKit’in aynı route için birden çok dosya kullanması, ajanın değişikliklerin etkisini görmesini kolaylaştırır; örneğin bir form action yazarken +page.server.ts içindeki load ve actions birlikte güncellenebilir. Ayrıca terminal tabanlı olması, değişiklikleri commit’lemeden önce git diff ile incelemenize imkan verir. Cursor CLI ile ilgili genel adımlar Cursor CLI nasıl kullanılır? Adım adım rehber sayfasında da anlatılıyor.

Projeyi ajan için hazırlamak

Ajan, proje kökündeki AGENTS.md veya .cursor/rules dosyasını okur. SvelteKit projesi için bu dosyada komutlar, klasör yapısı ve SvelteKit’e özgü kurallar net olmalıdır. İşte gerçekçi bir örnek:

# AGENTS.md

## Komutlar
- Kurulum: `npm install`
- Geliştirme: `npm run dev -- --open`
- Lint: `npm run lint`
- Test: `npm run test` (Vitest)
- E2E: `npm run test:e2e` (Playwright)
- Build: `npm run build`

## Klasörler
- `src/routes/`: sayfa, layout ve endpoint dosyaları
- `src/routes/+page.svelte`: sayfa iskeleti
- `src/routes/+page.server.ts`: sayfaya özel load ve form actions
- `src/routes/api/+server.ts`: API endpoint'leri (GET, POST vb.)
- `src/lib/`: paylaşılan bileşenler ve yardımcılar
- `src/lib/server/`: yalnızca sunucuda çalışan kod

## SvelteKit kuralları
- `+page.server.ts` içinde `load` ve `actions` export edilebilir; `+server.ts` içinde HTTP handler'ları bulunur.
- `load` fonksiyonu bir nesne döndürür ya da `redirect`/`error` fırlatır; istemciye veri gönderirken `serialize` çağrısı gerekmez.
- Form işlemleri için `use:enhance` kullan, `$app/forms`'tan `applyAction` veya `fail` dönüşünü işle.
- Otomatik tipler için `import type { PageServerLoad, Actions } from './$types';` kullan.
- `$lib/server` modüllerini istemci tarafına import etme; yalnızca sunucu dosyalarında kullan.
- Her değişiklikten sonra `npm run lint`, `npm run test` ve gerekirse `npm run test:e2e` çalıştır.

Bu dosya, ajanın yanlış komut çalıştırmasını veya sunucu kodunu istemciye taşımasını büyük ölçüde engeller. Kuralları kısa ve doğrulanabilir tutun; örneğin test komutunu yazmazsanız ajan test çalıştırmayabilir. Agent kurallarınızı kısa tutun; her madde test edilebilir olsun. SvelteKit sürümü değiştiğinde veya yeni bir klasör kuralı eklendiğinde AGENTS.md dosyasını güncelleyin. Ajan yanlış bir komut çalıştırırsa, hatayı dosyaya ekleyip bir sonraki istekte düzeltmesini isteyin. Örneğin, src/lib/server/db.ts gibi bir dosyanın yalnızca sunucuda kullanılacağını belirtmezseniz ajan onu +page.svelte içine import edebilir; bu sınır, SvelteKit build sırasında patlar.

Küçük adımlarla çalışma döngüsü

Cursor Agent ile SvelteKit’te güvenli çalışmanın yolu şudur: önce görevi küçük parçalara ayırın, ajanın yalnızca bir route veya fonksiyon üzerinde değişiklik yapmasını isteyin, ardından testleri ve lint’i çalıştırın, son olarak git diff ile değişiklikleri inceleyip commit’leyin. Bu döngüyü her adımda tekrarlayın; tek seferde beş route ve on test istemek yerine tek route ve ilgili testi isteyin. Her adımda yalnızca bir dosya grubunu hedefleyin; hem +page.server.ts hem +page.svelte değişecekse bunları ayrı istekler yapmak yerine aynı istekte ama açıkça listeleyin.

Aşağıdaki tablo tipik SvelteKit görevleri için etkili prompt örnekleri verir:

Her prompt’tan sonra ajanın çıktısını okuyun; değişiklikleri git diff ile gözden geçirin. SvelteKit’te küçük bir sunucu/istemci hatası build’de veya çalışma zamanında patlayabilir, bu yüzden diff incelemesini atlamayın.

Tipik SvelteKit görevleri ve dikkat edilmesi gerekenler

Cursor Agent şu işlerde iyi sonuç verir: yeni route oluşturma (+page.svelte, +page.server.ts), load fonksiyonlarında veri çekme ve dönüştürme, form actions ile doğrulama ve hata döndürme, +server.ts endpoint’leri yazma, bileşenleri ayırma, Vitest birim testleri ve Playwright e2e senaryoları yazma. Özellikle SvelteKit’in otomatik $types importlarını doğru kullanabilir.

Ancak şu noktalara dikkat edin:

• Sunucu/istemci sınırı: Ajan bazen $lib/server içindeki bir modülü +page.svelte içine import edebilir ya da browser kontrolü olmadan localStorage kullanabilir. Değişikliklerde bu tür hataları arayın.
• Load fonksiyonunun türü: Evrensel load (+page.ts) ile sunucu load (+page.server.ts) karışabilir. Sunucuya özel locals, cookies veya veritabanı erişimi gerekiyorsa mutlaka +page.server.ts kullanılmalıdır.
• Form actions dönüşü: fail kullanılmadan return { message } yapılırsa hata durumu doğru işlenmez. Ajan bazen fail çağrısını unutabilir.
• Redirect ve throw: throw redirect bir kontrol akışıdır; ajan bazen return redirect gibi yanlış bir ifade üretebilir.
• depends ve invalidate eksikliği: load fonksiyonu bir form action sonrası yeniden çalışmazsa, ajan invalidate eklemeyi atlayabilir.
• Rune kullanımı: Svelte 5 rune’ları ($state, $derived) ile eski reactive ifadeler karışabilir; projenizin sürümüne göre ajanı uyarın.
• Adapter ve environment: build sırasında adapter seçimi veya process.env kullanımı farklı ortamlarda sorun çıkarabilir; değişiklikleri build ile doğrulayın.

Test ve doğrulama

Cursor Agent test yazma ve çalıştırma konusunda iyidir. Vitest ile load fonksiyonlarını, form actions’ları ve +server.ts endpoint’lerini birim testi yapabilirsiniz. Örneğin bir +server.ts GET handler’ının doğru JSON döndürdüğünü ve başlıkları ayarladığını test etmesini isteyin. Playwright ile form gönderimi, yönlendirme ve sayfa render’ını e2e olarak doğrulatabilirsiniz. Her değişiklikten sonra AGENTS.md’de tanımlı komutları çalıştırmasını isteyin: npm run lint, npm run test, gerekirse npm run test:e2e. Ayrıca npm run check veya npm run build ile TypeScript ve Svelte derleme hatalarını yakalayın.

Ajanın test çıktılarını doğru yorumladığını varsaymayın; başarısız bir testin nedenini siz de okuyun. Özellikle Playwright testlerinde seçiciler route değişikliğiyle bozulabilir. Ajan testi geçirmek için seçiciyi gevşetmek yerine doğru erişilebilirlik rolünü kullanmalıdır; bu yüzden test diff’lerini inceleyin.

Birden çok ajanı AgentVera ile çalıştırmak

Bir SvelteKit projesinde aynı anda birden fazla Cursor Agent çalıştıracaksanız AgentVera iyi bir seçenektir. Her ajanı kendi git worktree’sinde çalıştırır; böylece +page.svelte ve +page.server.ts üzerinde paralel değişiklikler birbirini ezmez. Ajan dönüşü bittiğinde ikinci model otomatik kod incelemesi yapar ve SvelteKit sunucu/istemci sınırı hatalarını file:line olarak gösterir. Checkpoint’ler sayesinde yanlış bir load veya form action değişikliğini tek tıkla geri alabilirsiniz. Token bütçeleri de uzun route refactor’larında ajanı limitler içinde tutar. Paralel ajan kurulumları için Paralel kodlama ajanları için en iyi araçlar (2026) sayfasına bakın.

Sonuç

Cursor Agent, doğru AGENTS.md ve küçük adımlı bir döngüyle SvelteKit projelerinde hız kazandırır. Sunucu/istemci sınırı, form actions ve test çıktıları konusunda dikkatli olun; değişiklikleri mutlaka diff üzerinden inceleyin. Birden fazla ajanı paralel çalıştırmak isterseniz git worktree’leri ve otomatik inceleme sunan AgentVera ile riskleri azaltabilirsiniz.