opencode, SvelteKit projesinin kök klasöründe opencode komutuyla başlatılan bir CLI kodlama ajanıdır. SvelteKit’in dosya tabanlı routing, +page ve +server dosyaları, load fonksiyonları ve form actions yapısını anlar; sizden aldığı görevi AGENTS.md’deki proje kurallarına göre küçük adımlarla uygular. Bu rehber, SvelteKit geliştiricilerinin opencode’dan en iyi verimi alması için somut kurulum ve çalışma pratikleri sunar.
SvelteKit işleri için opencode’u uygun kılan özellikler
opencode, dosya sistemini ve terminal komutlarını doğrudan kullanır; bu da SvelteKit’in route dosyalarını düzenlerken gerçek proje yapısına sadık kalmasını sağlar. Örneğin src/routes altındaki +page.svelte, +page.ts, +page.server.ts ve +server.ts dosyalarını tek başına değiştirmek yerine birlikte ele alabilir. Load fonksiyonunun sunucu mu istemci mi çalışacağını dosya uzantısına göre ayırt eder; form actions’ta fail ve redirect döndürme kalıplarını bilir. Ayrıca SvelteKit’in build çıktısı, adapter seçimi ve $app/* importları gibi çerçeveye özgü ayrıntıları anlayarak genel kodlama ajanlarına göre daha az yanlış varsayım yapar. Kurulumda takılırsanız opencode nasıl kullanılır? Adım adım rehber yararlı olur.
Ajana projeyi hazırlama: AGENTS.md içeriği
opencode, proje kökündeki AGENTS.md dosyasını okur. SvelteKit projesi için bu dosyaya build, test, lint ve dev komutlarını; src/routes, src/lib, src/lib/server gibi klasör ayrımlarını; SSR ve client kurallarını yazın. Ajan her göreve başlarken bu talimatlara uyar; böylece her seferinde hangi test komutu diye sormaz. Aşağıdaki örnek, tipik bir SvelteKit projesinde işe yarayan kısa bir AGENTS.md dosyasıdır.
# AGENTS.md
## Komutlar
- dev: `npm run dev`
- build: `npm run build`
- preview: `npm run preview`
- test: `npx vitest run`
- e2e: `npx playwright test`
- lint: `npm run lint`
- check: `npm run check`
## Klasör düzeni
- src/routes: yalnızca route dosyaları (+page, +server, +layout, +error)
- src/lib/components: yeniden kullanılabilir Svelte bileşenleri
- src/lib/server: yalnızca sunucu tarafında çalışacak kod
- src/lib: istemci ve sunucu ortak yardımcıları
## SvelteKit kuralları
- +page.server.ts içindeki load fonksiyonları yalnızca sunucuda çalışır; tarayıcı API'si kullanma.
- Form actions +page.server.ts içinde tanımlanır; başarıda `redirect`, hatada `fail` döndür.
- `$app/*` importları yalnızca SvelteKit ortamında geçerlidir; testlerde mock gerekebilir.
- Dış API çağrılarını src/lib/server altına koy; +page.ts içine koyma.
- Her değişiklikten sonra `npm run check` ve ilgili testleri çalıştır.Bu dosya ne kadar kısa ve net olursa ajan o kadar az varsayım yapar. SvelteKit’e özgü olarak browser kontrolü, $app/stores kullanımı ve adapter seçimi gibi bilgileri de ekleyebilirsiniz; ancak komut listesi ile klasör kuralları en kritik kısımdır.
Çalışma döngüsü: plan, küçük adım, test, diff
opencode ile SvelteKit projesinde verimli çalışmak için her görevi tek bir route veya tek bir bileşenle sınırlayın. Önce ajanın bir plan sunmasını isteyin; planı onayladıktan sonra değişiklikleri yapmasını söyleyin. Her adımdan sonra git diff çıktısını isteyin ve inceleyin. Testleri çalıştırmasını isteyin; başarısız olursa düzeltmesini söyleyin. Aşağıdaki tablo, sık kullanılan SvelteKit dosyaları için doğrudan kopyalanabilir görev istemlerini eşler.
| Dosya / görev | opencode’a yazılacak talep |
|---|---|
| +page.ts load | src/routes/urunler/+page.ts içindeki load fonksiyonuna ürün listesini çeken fetch ekle; başarısız olursa boş dizi döndür. |
| +page.server.ts action | src/routes/giris/+page.server.ts içindeki login action’ını cookie ayarlayacak şekilde güncelle; hata mesajını form alanına döndür. |
| +server.ts endpoint | src/routes/api/notlar/+server.ts içine GET handler ekle; JSON yanıt döndür, authorization header kontrolü yap. |
| Svelte bileşeni | src/lib/components/DataTable.svelte bileşenini sunucudan gelen veriyi props olarak alacak şekilde refactor et. |
Aşağıdaki örnek istemler tipik SvelteKit görevleri içindir:
- src/routes/blog/[slug]/+page.server.ts içindeki load fonksiyonuna ilgili yazıyı çeken bir veritabanı sorgusu ekle; hata durumunda 404 döndür.
- Yeni bir iletişim formu için src/routes/contact altına +page.svelte ve +page.server.ts oluştur; action’da zod ile doğrula, başarılıysa redirect, hata varsa fail döndür.
- src/lib/components/Button.svelte bileşenini erişilebilirlik kurallarına göre güncelle: aria-label desteği, klavye odak yönetimi ve disabled state.
- Mevcut +server.ts endpoint’ine rate limiting ekle; istek başına kullanıcı IP’sini basit bir Map ile tut, limit aşımında 429 döndür.
- Vitest ile load fonksiyonunun testlerini yaz; mock data döndüren bir fixture kullan ve hata senaryosunu da kapsa.
Bu istemlerde dosya yollarını ve beklenen davranışı net belirtmek, ajanın yanlış route’a dokunmasını veya SSR/client sınırını ihlal etmesini önler.
SvelteKit’te iyi giden görevler ve dikkat gerekenler
opencode, SvelteKit’te özellikle şu işlerde başarılıdır: yeni route dosyaları oluşturma, load fonksiyonlarını yazma veya düzenleme, basit +server endpoint’leri, form actions, Vitest birim testleri ve erişilebilirlik iyileştirmeleri. Buna karşılık SSR/browser ayrımı en sık hata yapılan noktadır. Ajan, +page.ts içinde window veya localStorage kullanmayı deneyebilir; bunu src/lib altındaki ortak bir dosyaya koysa bile sunucu render sırasında patlar. Ayrıca form actions’ta fail yerine yanlışlıkla throw kullanabilir veya redirect sonrası kod çalıştırmaya devam edebilir. +page.server.ts ile +page.ts arasındaki serialization farkları da gözden kaçabilir: sunucudan dönen Date veya Map gibi nesneler client’a geçerken sorun çıkarır. Svelte 5 runes ile eski reactive syntax karıştırıldığında ajan eski $: kullanabilir; proje Svelte 5 kullanıyorsa bunu AGENTS.md’ye açıkça yazın. Adapter seçimi, özellikle adapter-node ile adapter-static arasındaki farklar, build sırasında hatalara yol açabilir. Bu alanlarda diff’i dikkatle inceleyin ve ajanın her seferinde npm run check çalıştırmasını isteyin.
SvelteKit’te test ve doğrulama
Ajanın yaptığı değişikliği kabul etmeden önce mutlaka testleri ve tip kontrolünü çalıştırın. AGENTS.md içinde tanımlı komutları kullanın. opencode’a şu cümleleri kurdurun: ‘Vitest’i çalıştır, başarısız olan testleri düzelt’ veya ‘Playwright ile kritik akışı çalıştır; hata varsa düzeltme öner.’ Ajan, test çıktısını okuyarak kendi kodunu düzeltebilir; ancak e2e testlerinin flaky olabileceğini unutmayın, diff’i küçük tutun. Özellikle form actions ve load fonksiyonları için Vitest ile birim testi; kullanıcı akışları için Playwright ile uçtan uca test eklemek, ajanın yaptığı değişikliği doğrulamanın en güvenilir yoludur. Testler geçtikten sonra npm run build çalıştırın; SvelteKit’in adapter’a bağlı derleme hataları ancak build aşamasında ortaya çıkar. Ajan build çıktısını da okuyup düzeltebilir.
Bir projede birden fazla ajan: AgentVera
AgentVera, opencode gibi CLI ajanlarını yan yana çalıştıran bir masaüstü uygulamasıdır. SvelteKit projesinde aynı anda hem bir +server endpoint’i hem de bir form action’ı geliştirmek isterseniz, her ajanı ayrı bir git worktree içinde çalıştırıp dosyaların ezilmesini önlersiniz. Ajanın turu bitince ikinci bir model otomatik kod incelemesi yapar ve bulguları file:line ile işaretler; ayrıca her turun checkpoint’i alındığı için yanlış bir değişikliği tek tıkla geri alabilirsiniz. Token bütçeleri sayesinde ajanın günlük kullanımını sınırlayabilir, SvelteKit’e özgü hataları düzeltirken maliyeti kontrol altında tutabilirsiniz.
Sonuç
opencode, SvelteKit projelerinde AGENTS.md ile iyi beslendiğinde route, load ve form action işlerini güvenilir biçimde hızlandırır. Küçük adımlar, net dosya yolları ve test komutları her zaman en iyi sonucu verir. Değişiklikleri diff ile inceleyip Vitest ve Playwright doğrulaması yapmadan ana dala almayın.