Nuxt projesinde Codex’i kullanmak için proje kök dizininde codex komutunu çalıştırmanız yeterlidir; ajan, AGENTS.md dosyasındaki talimatları okur ve Nuxt’un dosya tabanlı yönlendirme, server routes, composables ve Nitro mimarisine göre değişiklik önerir. Codex ile küçük adımlar atıp her turda test çalıştırarak SSR, auto-import ve API endpoint’lerini güvenle geliştirebilirsiniz. Aşağıdaki rehberde kurulum, çalışma döngüsü ve Nuxt’a özgü tuzaklar yer alıyor.
Codex neden Nuxt işine uygun?
Nuxt projelerinde işin çoğu sözleşmeye dayalıdır: pages/ altındaki dosyalar route olur, server/api/ altındaki dosyalar Nitro endpoint’i olur, composables/ içindeki useX fonksiyonları otomatik içe aktarılır. Codex terminalde gerçek komutları çalıştırıp çıktıyı okuyabildiği için pnpm dev ile hata ayıklayabilir, pnpm test ile regresyon yakalayabilir ve git diff ile değişiklikleri gösterebilir. Bu, ajanın yalnızca kod üretmesini değil, Nuxt’un çalışma zamanı davranışını doğrulamasını sağlar.
Auto-import’un getirdiği belirsizlik nedeniyle birçok geliştirici refactor sırasında import ekleyip çıkarır; Codex, proje tip tanımlarını ve .nuxt çıktısını inceleyerek doğru kapsamı anlayabilir. Aynı şekilde server/api dosyalarında defineEventHandler, readBody, getQuery gibi Nitro yardımcılarını kullanmayı öğrenir. Bu sayede ajan, yalnızca Vue bileşeni değil, tam yığın Nuxt kodu üretebilir.
Nuxt’ta useFetch ve useAsyncData gibi composable’ların istemci-sunucu ayrımı, SSR hataları, middleware akışı ve Nitro’nun istek/yanıt modeli gibi konular bağlam gerektirir. Codex, proje içindeki nuxt.config.ts, mevcut middleware ve test dosyalarını okuyarak bu ayrımı anlayabilir; AGENTS.md ile netleştirilen kurallar sayesinde ilk seferde doğru kapsamı seçer. Bu, özellikle birden fazla developer’ın dokunduğu büyük Nuxt projelerinde tutarlılığı artırır.
Projeyi ajan için hazırlama ve AGENTS.md
Codex, proje kökündeki AGENTS.md dosyasını bağlam olarak okur. Bu dosya ne kadar net olursa ajan Nuxt’un örtük kurallarını o kadar az yanlış anlar. Komutları, klasör sözleşmelerini ve Nuxt’a özgü kuralları tek bir dosyada tutun. Aşağıdaki örnek küçük bir Nuxt 3 projesi için uygundur; ekibinizdeki script adları farklıysa onları kullanın.
# AGENTS.md
## Komutlar
- Kurulum: `pnpm install`
- Geliştirme: `pnpm dev`
- Test: `pnpm test`
- Lint: `pnpm lint`
- Tip kontrolü: `pnpm typecheck`
- Build: `pnpm build`
## Klasör sözleşmeleri
- `pages/` dosya tabanlı yönlendirme; yeni sayfa eklerken dosya adını route olarak düşün.
- `server/api/` Nitro handler'ları; istemci tarafına taşınacak verileri burada hazırla.
- `composables/` otomatik import edilen `use*` fonksiyonları; yan etkisi olanları `onMounted` içinde çağır.
- `utils/` saf yardımcılar; otomatik import kapsamındadır, manuel `import` yazma.
## Nuxt'a özel kurallar
- `useFetch`, `useAsyncData`, `navigateTo`, `useRoute` gibi Nuxt composable'larını asla manuel import etme.
- `server/` içindeki kodu istemci tarafına taşıma; `process.server` kontrolünü zorunlu olmadıkça kullanma.
- Her değişiklikten sonra `pnpm test` çalıştır; dosya tabanlı yapıyı bozmadığından emin ol.
- `nuxt.config.ts` içinde modül veya seçenek değiştirirken önce mevcut ayarı oku, sonra ekle.AGENTS.md dosyasını kısa tutun; onlarca kural yerine sık kullanılan komutları ve Nuxt’un farklı davranan üç-dört noktasını yazın. Örneğin Nitro handler’larının event parametresiyle çalıştığını, istemcide window erişiminin SSR sırasında hata verdiğini ve route middleware’inin middleware/ klasöründe yer aldığını belirtmek, ajanın ilk denemede doğru kodu üretme oranını artırır. Bağlamı bilinçli şekilde yönetmek için bağlam mühendisliği yazısındaki pratikleri uygulayabilirsiniz.
Çalışma döngüsü ve örnek promptlar
Planla, küçük adım at, test çalıştır, diff’i incele. Codex’e geniş bir görev vermek yerine dosya veya özellik bazında sınırlı istekler iletin. Ajan her turda değişiklik yaptıktan sonra git diff ile neyi değiştirdiğini gösterin; Nuxt’ta özellikle pages/, server/ ve composables/ altındaki değişiklikleri beraber okuyun. Aşağıdaki promptlar tipik Nuxt görevleri için başlangıç noktası olabilir:
pages/checkout.vueiçindeki form doğrulamasını refactor et; mevcut kullanıcı akışını bozmadanuseFormcomposable’ı oluştur vecheckout.vue’da kullan.server/api/products.get.tsendpoint’ini ekle;getQueryilecategoryfiltrelesin, tip tanımlarınıtypes/altına koy.composables/useCart.tsiçindekiuseStatemantığınıuseCookieile değiştir; SSR sırasında hydration hatası olmaması için gerekli kontrolleri ekle.pages/index.vueiçin Vitest ile iki test yaz: başlık render ve buton tıklama;@nuxt/test-utilskullan.nuxt.config.tsiçine yeni bir modül ekleme adımını tarif et; önce mevcut ayarları göster, sonra değişiklik öner.
Tipik Nuxt görevleri ve dikkat edilecek yerler
Codex, Nuxt’ta sık tekrarlanan işleri hızlıca yapar: yeni sayfa ekleme, server/api altında CRUD endpoint’leri oluşturma, composable ayıklama, route middleware yazma ve test ekleme. Ancak bazı noktalarda çıktıyı yakından incelemek gerekir. Aşağıdaki tablo, ajanın iyi olduğu görevlerle dikkat edilecek tuzakları özetler.
| Görev | Codex’in yaklaşımı | Dikkat edilecek nokta |
|---|---|---|
Yeni pages/ dosyası | Dosya adından route üretir, definePageMeta ile middleware bağlar | Route parametreleri ([id].vue) ve nested route’ları yanlış adlandırabilir |
server/api endpoint | defineEventHandler ile handler yazar, readBody/getQuery kullanır | İstemci tarafına veri sızdırmamak için dönüş değerini daraltmayabilir |
| Composable refactor | useState yerine useCookie veya useLocalStorage önerebilir | SSR sırasında window erişimi ekleyebilir; onMounted içinde tutulmalı |
| Test ekleme | Vitest ve @nuxt/test-utils ile yazar | mountSuspended yerine mount kullanarak SSR bağlamını kaçırabilir |
Yaygın tuzaklar arasında auto-import kapsamının dışına taşınmış fonksiyonlar, server/ klasöründeki kodun istemcide kullanılması, Nitro handler’ında event.context erişiminin yanlış tip kaybı ve useFetch döndüren data/pending/error üçlüsünün hatalı destructuring’i yer alır. Codex bazen server/ içindeki bir utility’yi doğrudan pages/ altına import edebilir; bunu pnpm build veya pnpm typecheck yakalar. Ayrıca ajan, dosya tabanlı yönlendirme değişikliklerinde eski route’lar için yönlendirme veya silme önermeyebilir.
Nuxt’ta test ve doğrulama ajanla
Codex ile çalışırken her turdan sonra pnpm test ve pnpm typecheck çalıştırın. Vitest ve @nuxt/test-utils, Vue bileşenlerini SSR bağlamında test etmenizi sağlar; ajan, mountSuspended kullanarak sayfa ve bileşen render testleri yazabilir. Ayrıca server/api endpoint’lerini doğrulamak için $fetch veya useTestServer gibi araçlar kullanılabilir. Kodun Nitro derlemesinden geçtiğinden emin olmak için pnpm build şarttır; ajan bazen istemci tarafına taşınan bir helper’ı server/ altında bırakabilir, build bu hatayı yakalar.
Refactor sonrası pnpm lint ile stil ve kural ihlallerini kontrol edin; Nuxt’un ESLint yapılandırması auto-import’a özel kurallar içerebilir. Ajan, kendi ürettiği testleri çalıştırıp başarısız olursa hatayı kendisi düzeltebilir; codex komutunu tekrar çağırmadan aynı oturumda şimdi testleri çalıştır ve hataları düzelt diyerek döngüyü kapatabilirsiniz. Codex CLI nasıl kullanılır rehberi, komut akışını daha ayrıntılı ele alır.
AgentVera ile paralel ajanlar
Nuxt projesinde birden fazla Codex oturumunu paralel çalıştırmak istediğinizde AgentVera devreye girer. Her ajan kendi git worktree’sinde çalıştığı için pages/ ve server/ üzerinde çakışma olmaz. Bir ajanın turu bittiğinde ikinci bir model kodu otomatik inceler ve bulguları dosya:satır olarak işaretler; bu, auto-import veya Nitro handler’larındaki hataları yakalar. Ayrıca her turun anlık görüntüsü alınır, böylece yanlış bir refactor tek tıkla geri alınıp oturum adım adım yeniden oynatılabilir. AgentVera nasıl kullanılır sayfası paralel çalışma düzenini gösterir.
Kapanış
Codex, Nuxt’un sözleşme temelli yapısını iyi kullanır; ancak asıl fark, AGENTS.md ile netleştirilmiş bağlam ve düzenli test döngüsüdür. Küçük adımlar atın, diff’i okuyun, Nitro ve SSR hatalarını yakalamak için build ve typecheck’i ihmal etmeyin. Paralel çalışmada işleri ayrı worktree’lere bölmek Nuxt’ta hız ve güvenlik sağlar.