# Codex ile SvelteKit Projelerinde Çalışma Rehberi

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

Codex’i SvelteKit projelerinde kullanmak için pratik bir rehber: AGENTS.md kurulumu, çalışma döngüsü, sık görevler, tuzaklar ve test doğrulama.

**Kısaca:**

- Codex, SvelteKit projelerinde route, load ve form action değişikliklerini çok dosyalı olarak yapar.
- AGENTS.md’ye komut ve klasör kurallarını yazmak, ajanın istemci-sunucu sınırını korumasına yardımcı olur.
- Her değişiklikten sonra npm run check ve Vitest çalıştırmak regresyonu erken yakalar.

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](/ajanlar/codex/) sayfasına, CLI kurulumu için [Codex CLI nasıl kullanılır? Adım adım rehber](/blog/codex-cli-nasil-kullanilir/) 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:

```markdown
# 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](/blog/baglam-muhendisligi/) 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:

| Komut | Doğruladığı şey |
|---|---|
| `npm run check` | SvelteKit ve TypeScript tip hataları |
| `npm run test` | Vitest birim testleri |
| `npm run test:e2e` | Playwright ile kritik kullanıcı akışları |
| `git diff` | Ajanın yaptığı dosya değişiklikleri |

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

## Sık sorulanlar

**Codex SvelteKit projesinde nasıl başlatılır?** Proje klasöründe terminalden codex komutunu çalıştırın. Ajan, AGENTS.md talimatlarını ve mevcut route yapısını okuyarak görevleri yürütür.

**AGENTS.md dosyasına SvelteKit için neler yazmalıyım?** Komutların yanında +page.server.ts, +server.ts ve $lib/server kurallarını yazın. Form action’ların yeri, load verisinin serileştirilmesi ve ortam değişkeni kullanımı gibi SvelteKit’e özgü kısıtları ekleyin.

**Codex SvelteKit’te form action ve use:enhance birlikte düzenleyebilir mi?** Evet, ajan +page.server.ts içindeki action ile +page.svelte içindeki use:enhance kullanımını aynı görevde güncelleyebilir. Hata mesajlarının form prop’undan okunmasını ayrıca belirtmek faydalı olur.

**Codex SvelteKit testlerini kendisi çalıştırır mı?** Evet, AGENTS.md veya prompt içinde verdiğiniz komutları kullanarak Vitest ve Playwright çalıştırabilir. Test çıktısına göre hatayı düzeltmesini isteyebilirsiniz.

---

**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/