Codex ile SvelteKit Projelerinde Çalışma Rehberi

Codex’i bir SvelteKit projesinde terminalden codex komutuyla başlatıp route, load fonksiyonu, form action ve test işlerini doğrudan ajana yaptırabilirsiniz. Bu rehber, ajanın SvelteKit’e özgü kuralları doğru uygulaması için kuracağınız bağlamı, çalışma döngüsünü ve dikkat etmeniz gereken yerleri anlatıyor. Genel kullanım için Codex sayfasına, CLI kurulumu için Codex CLI nasıl kullanılır? Adım adım rehber rehberine bakabilirsiniz.

SvelteKit işlerinde Codex’in güçlü yanları

Codex, dosya tabanlı route yapısını ve +page.svelte, +page.ts, +page.server.ts, +server.ts ayrımını okuyabildiği için bir görevi tek dosyayla sınırlı bırakmaz. Örneğin bir form akışında hem +page.svelte içindeki use:enhance kullanımını hem de +page.server.ts içindeki actions objesini birlikte güncelleyebilir. Ajan, load fonksiyonundan dönen verinin istemciye serileştirilebilir olması gerektiğini genellikle bilir; yine de bu sınırı sık sık denetlemeniz gerekir. En büyük faydası, npm run check ile tip hatalarını ve $lib/server sızıntılarını daha kod yazarken fark edip düzeltmesidir. Svelte 5 projelerinde $state rune’ları ve $derived kullanımını anlayabildiği için yeni sözdizimine uyum sağlar. Ancak bu, ajanın her zaman doğru state yönetimi yazacağı anlamına gelmez; özellikle istemci tarafında rune ile mağaza arasındaki seçimde yönlendirme isteyebilirsiniz.

Ajan, route dosyaları arasındaki ilişkileri çözerken projenin geri kalanını da görebilir. Örneğin bir +server.ts endpoint’ine yeni bir GET eklerken, o endpoint’i çağıran istemci fonksiyonunu veya route’u bulup uyumluluğu koruyabilir. Ayrıca hooks.server.ts içindeki oturum doğrulama mantığıyla load fonksiyonundaki yönlendirmeleri birleştirebilir. Bu, ajanı tek seferlik kod parçacığı üreticiden çok, proje bağlamında çalışan bir yardımcıya dönüştürür. Yine de Codex’in Svelte derleme ve SSR kurallarını her zaman doğru uygulamadığını unutmayın; örneğin onMount içinde fetch kullanımı veya $app/environment kontrolleri gibi ince detaylarda manuel gözden geçirme gerekir.

Projeyi ajana hazırlamak: AGENTS.md

Codex, proje kökündeki AGENTS.md dosyasını okur. SvelteKit projesinde bu dosyaya yalnızca komutları değil, route ve dosya türü kurallarını da yazın. Böylece ajan +server.ts ile +page.server.ts arasındaki farkı sormadan uygular, $lib/server altındaki kodu istemciye sızdırmaz ve form mutasyonlarını action içinde tutar. Aşağıdaki örnek, orta ölçekli bir proje için gerçekçi bir başlangıçtır:

# AGENTS.md

## Komutlar
- Bağımlılık: `npm install`
- Geliştirme: `npm run dev`
- Tip kontrolü: `npm run check`
- Lint: `npm run lint`
- Birim test: `npm run test` (Vitest)
- E2E: `npm run test:e2e` (Playwright)

## Klasör ve route kuralları
- `src/routes` altında her sayfa için `+page.svelte`, `+page.ts`, `+page.server.ts` kullan.
- API uçları için yalnızca `+server.ts` aç; `+page.server.ts` ile karıştırma.
- Sunucuya özel kod `$lib/server` altında olmalı; istemci tarafından import edilmemeli.
- Route grupları ve dinamik segmentler için URL çakışması yaratma.

## SvelteKit kuralları
- `load` fonksiyonları düz veri döndürür; Date, Map, fonksiyon veya Promise döndürme.
- Form action'ları `+page.server.ts` içinde `actions` objesiyle tanımla; mutasyonları action'da yap.
- İstemci tarafında `$app/forms` içinden `use:enhance` kullan; hata mesajlarını `form` prop'undan oku.
- Özel ortam değişkenleri yalnızca sunucu dosyalarında kullanılır.
- Her değişiklikten sonra `npm run check && npm run test` çalıştır; E2E gerekiyorsa `npm run test:e2e`.

Bu dosyayı kısa tutun; ajan, net kuralları uzun genel açıklamalara tercih eder. Bağlamın nasıl katmanlanacağını daha geniş biçimde öğrenmek için Bağlam mühendisliği: yapay zeka kodlama ajanları rehberi rehberindeki pratik yaklaşımı uygulayabilirsiniz. AGENTS.md’ye ekleyebileceğiniz diğer maddeler arasında veritabanı şemasına erişim kuralları, auth kütüphanesi kullanımı, ortam değişkeni adları ve test verisi hazırlama yöntemleri bulunur. Örneğin Lucia veya Auth.js kullanıyorsanız session doğrulama fonksiyonunun tam yolunu belirtmek, ajanın yanlış import yapmasını engeller. Benzer şekilde Prisma veya Drizzle şemanızın bulunduğu dosyayı ve CRUD işlemlerinin nasıl yapılacağını yazarsanız, form action veya endpoint’lerde tutarlı kod üretir.

Çalışma döngüsü ve örnek promptlar

Planı önce siz yapın; ajana küçük ve test edilebilir adımlar verin. Her adımda ajanın değişiklikleri yapmasını, npm run check veya test komutunu çalıştırmasını isteyin, ardından git diff ile değişiklikleri inceleyin. İşe yarayan döngü şöyledir:

1. Mevcut route yapısını ve ilgili load/action dosyalarını özetletin.
2. Tek bir davranışı tanımlayan görev verin; örneğin “şu route’a redirect ekle” gibi.
3. Ajanın test veya tip kontrolü çalıştırmasını isteyin.
4. git diff ile değişiklikleri satır satır inceleyin; yanlış istemci-sunucu sınırını düzeltin.
5. Sonucu kabul edin veya aynı oturumda küçük düzeltmeler isteyin.

SvelteKit için kullanabileceğiniz beş örnek prompt:

• “Mevcut route yapısını ve +page.server.ts dosyalarındaki load fonksiyonlarını özetle; eksik hata yakalama veya redirect varsa listele.”
• “/dashboard route’una kullanıcı oturumunu doğrulayan bir load fonksiyonu ekle; oturum yoksa /login sayfasına redirect et. Değişiklikten sonra npm run check çalıştır.”
• “/api/notlar için +server.ts içinde GET ve POST endpoint’lerini yaz; gelen veriyi Zod ile doğrula, hata yanıtlarını json ile döndür.”
• “Profil formunu use:enhance ile güncelle; action başarısız olursa hata mesajlarını form prop’undan göster ve butonu devre dışı bırak.”
• “Vitest’te /dashboard load fonksiyonu için birim testi yaz, testi çalıştır ve kırık varsa düzelt.”

Bu promptlarda dosya adını ve beklenen davranışı netleştirmek, ajanın tahmin yürütmesini azaltır. Ayrıca ajana değişiklik yaptığı dosyaları git diff --stat ile özetletmek, incelemeyi hızlandırır. Bir test başarısız olursa, hatayı kopyalayıp ajana verin; ajan genellikle hangi dosyanın sorumlu olduğunu bulur. Büyük değişikliklerde işi parçalara ayırın: önce load fonksiyonunu, sonra action’ı, sonra UI’ı güncelletin. Böylece hata durumunda geri almak kolaylaşır ve ajanın bağlamı yönetilebilir kalır.

Codex’in iyi yaptığı işler ve SvelteKit tuzakları

İyi sonuç verdiği işler arasında form action eklemek, use:enhance ile hata mesajı yönetmek, CRUD endpoint’leri yazmak, load fonksiyonuna redirect ve hata yakalama eklemek, Vitest ile birim testi oluşturmak sayılabilir. Bunlar genellikle birden çok dosyayı tutarlı biçimde değiştirmeyi gerektirir; Codex bu bütünlüğü kurar. Özellikle +page.server.ts içindeki action ile +page.svelte içindeki use:enhance arasındaki sözleşmeyi korumakta faydalıdır.

Dikkat etmeniz gereken SvelteKit’e özgü tuzaklar şunlardır: istemci-sunucu sınırı, load verisinin serileştirilmesi, route çakışmaları ve state yönetimi. Ajan bazen $env/dynamic/private değişkenini +page.svelte içinde kullanmak isteyebilir; bu derlemede patlar. load fonksiyonundan Date, Map veya fonksiyon döndürmesi halinde SvelteKit serileştirme hatası verir. Dinamik route ve route gruplarında iki dosya aynı URL’i yakalamaya çalışabilir. Svelte 5 projelerinde $state rune’larını mağazalarla karıştırabilir; değişiklikleri incelerken istemci tarafındaki state kurallarını netleştirin. Ayrıca adaptör seçimi ve ortam değişkenleri gibi derleme zamanı kararlarını ajanın değiştirmesine izin vermeyin.

Başka tuzaklar da vardır. load fonksiyonunda fetch kullanırken URL’nin göreceli olmaması gerekir; ajan bazen fetch('/api/notlar') yerine mutlak yol yazabilir. onMount içinde fetch kullanmak SSR ile çakışabilir; bunun farkında olmalıdır. $app/stores içindeki page store’u yalnızca bileşenlerde kullanılmalı, load içinde değil. error ve redirect çağrılarının yalnızca sunucu tarafında çalıştığını hatırlatmak gerekebilir. +layout.ts ile +page.ts arasındaki veri birleştirmesinde load dönüş tiplerini tutarlı tutmak da sık unutulan bir noktadır. Ajan, setHeaders veya cookies gibi sunucuya özgü nesneleri istemciye aktarmaya çalışabilir; bu tür satırları git diff içinde arayın. Son olarak, use:enhance kullanırken action’un dönüş değerini form prop’undan okumayı unutmamalısınız; ajan bazen result değişkenini yanlış yerde kullanır.

SvelteKit’te test ve doğrulama

Codex’e her değişiklik sonrası şu komutları çalıştırmasını söyleyin. Tablo, hangi komutun neyi doğruladığını gösterir:

Playwright, SvelteKit geliştirme sunucusunu kendisi ayağa kaldırdığı için testlerden önce ayrıca npm run dev çalıştırmaya gerek yoktur. Codex’ten kırık bir testi okumasını ve hatanın kaynağını bulmasını isteyebilirsiniz. Özellikle load fonksiyonları için Vitest’te fetch mock’lamak yerine gerçek fonksiyonu çağırmak, SvelteKit davranışını daha iyi yakalar. Ajanın testleri yazarken $app/forms veya $app/navigation gibi SvelteKit modüllerini mock etmesi gerekiyorsa bunu açıkça söyleyin.

Vitest ile test yazarken ajanın vi.mock kullanımı agresif olabilir; global mock’lar testler arasında sızabilir. beforeEach ile mock’ları temizlemesini isteyin. +server.ts endpoint’lerini test etmek için Request nesnesi oluşturup fonksiyonu doğrudan çağırmak mümkündür; ajan bunu yapabilir. Playwright’ta form gönderimi, use:enhance davranışını tam simüle etmese de ağ isteklerini ve sayfa geçişlerini doğrular. E2E testlerinizi kritik akışlarla sınırlayın; ajanın tüm route’ları test etmeye çalışması yavaşlar. npm run check komutu SvelteKit’in tip kontrolünü yapar ve SSR hatalarının çoğunu yakalar; bu yüzden her değişiklikte çalıştırılmalıdır. Ajanın lint komutunu atlamamasını sağlayın; ESLint ve Prettier kuralları kod tutarlılığını korur.

Birden fazla ajanı AgentVera ile koşurmak

Birden fazla Codex oturumunu aynı SvelteKit projesinde çalıştırmak isterseniz AgentVera masaüstü uygulaması, her ajanın gerçek CLI’ını kendi terminal panelinde çalıştırır. Git worktree desteği sayesinde ajanlar farklı route veya test dosyalarında paralel çalışır ve birbirinin dosyalarını ezmez. Her turun anlık görüntüsü checkpoint olarak saklanır; böylece bir ajanın load veya action değişikliği bozulursa tek tıkla geri alınabilir. Token bütçeleri ise ajanın kontrolden çıkıp tüm krediyi tüketmesini önler. Kurulum ve çoklu ajan akışı için AgentVera nasıl kullanılır: ilk proje, ajanlar ve ızgara sayfasına bakabilirsiniz.

Sonuç

Codex ile SvelteKit’te verimli çalışmanın anahtarı, AGENTS.md’de net komutlar ve route kuralları tanımlamak, görevleri küçük tutmak ve her adımda check ile testleri çalıştırmaktır. Ajan, form action, load ve endpoint işlerini hızlandırır; siz de istemci-sunucu sınırını ve serileştirmeyi gözden geçirirsiniz. Paralel işler için AgentVera gibi bir araçla birden fazla ajanı güvenle koşabilirsiniz.