Codex’i bir Next.js projesinde kullanmak için proje kökünde terminalde codex komutunu çalıştırmanız yeterlidir. Kod ajanı, AGENTS.md dosyasındaki talimatları ve proje yapısını okuyarak sunucu/istemci bileşenleri, route handler’lar ve testler üzerinde değişiklik yapabilir. Bu rehber, Codex’i Next.js ile verimli kullanmanın pratik yollarını gösterir.
Codex neden Next.js işlerine uygun
Next.js projeleri büyük ölçüde metin tabanlıdır: dosya yönlendirmesi, bileşen sınırları, route handler’lar ve yapılandırma dosyaları. Codex bu dosyaları okuyup düzenleyebilir, komut çalıştırabilir ve çıktıları yorumlayabilir. App Router’da sayfa, layout, loading ve error dosyaları arasındaki ilişkiler belirgin olduğu için ajan, küçük görevleri yüksek doğrulukla tamamlar. Örneğin, app/api/products/route.ts dosyasına bir POST handler eklemek, istek gövdesini doğrulamak ve yanıt döndürmek gibi işleri Codex tek seferde yapabilir. Ancak iş mantığı ve güvenlik kontrolleri sizin onayınızı gerektirir. Özellikle Next.js’in dosya tabanlı yönlendirmesi, ajanın yeni bir sayfa eklerken doğru klasöre dosya koymasını kolaylaştırır. Codex’in genel kullanımı hakkında Codex sayfasına bakabilirsiniz; burada Next.js’e özgü pratiklere odaklanıyoruz.
Projeyi ajana hazırlama: AGENTS.md
AGENTS.md, proje köküne koyduğunuz ve Codex’in her oturum başında okuduğu talimat dosyasıdır. Next.js için komutlar, klasör yapısı ve kurallar net olmalı. Örnek bir dosya:
# AGENTS.md
## Komutlar
- Kurulum: npm install
- Geliştirme: npm run dev
- Build: npm run build
- Test: npm test
- Lint: npm run lint
## Klasör yapısı
- app/ (App Router): sayfalar, layout'lar, route handler'lar
- components/: paylaşılan React bileşenleri
- lib/: yardımcı fonksiyonlar
- tests/: birim ve entegrasyon testleri
## Kurallar
- Varsayılan olarak server component kullan; yalnızca interaktiflik gerekiyorsa \"use client\" ekle.
- Route handler'larda gelen veriyi doğrulamadan dış API'ye istek gönderme.
- Yeni sayfa eklerken metadata ve loading.tsx dosyalarını unutma.
- Her değişiklik sonrası npm run lint ve npm test çalıştır.Bu dosya, ajanın her seferinde aynı komutları ve kuralları uygulamasını sağlar. Pages Router kullanıyorsanız, klasör yapısını pages/ ve api/ olarak güncelleyin. AGENTS.md dosyasını kısa tutun; 50 satırı aşmasın. Proje yapısı değiştikçe komutları ve klasörleri güncelleyin. Ajan, dosyadaki kurallara uymaya çalışır ama çelişkili talimatlar kafa karıştırır. AGENTS.md, sadece komutları değil, aynı zamanda proje standartlarını da içermelidir. Örneğin, TypeScript strict modu açıksa ajan tip güvenliğine dikkat eder; ESLint kuralları, ajanın stil ve hata yaklaşımını belirler. Next.js’te app/ ve pages/ klasörlerinin birlikte kullanıldığı geçiş projelerinde, her iki router’ın kurallarını ayrı ayrı yazın. Ayrıca ortam değişkenleriyle ilgili kural ekleyin: sunucu tarafında process.env kullanılabilirken istemci tarafında NEXT_PUBLIC_ öneki gerekir. Ajan bu ayrımı bilmezse yanlış değişkeni istemciye sızdırabilir. AGENTS.md’nin ilk satırlarına projenin Next.js sürümünü ve paket yöneticisini not edin; çünkü ajan bazen varsayılan olarak npm kullanır, proje pnpm kullanıyorsa komutlar uyumsuz olur. Ayrıca bağlam mühendisliği hakkında Bağlam mühendisliği: yapay zeka kodlama ajanları rehberi yazısına göz atabilirsiniz.
Çalışma döngüsü ve örnek istemler
Codex ile verimli çalışmak için planlama, küçük adımlar, test ve diff incelemesi döngüsünü izleyin. Önce yapılacak değişikliği bir cümleyle özetleyin, ardından ajanın dosyaları değiştirmesine izin verin, sonra git diff ile değişiklikleri gözden geçirin, testleri çalıştırın ve hataları ajana geri bildirin. git diff --stat ile hangi dosyaların değiştiğini hızlıca görün. Özellikle package.json veya next.config.js değişikliklerini dikkatle inceleyin; bu dosyalar build davranışını değiştirebilir. Çalışma döngüsünde plan adımını atlamayın. Ajan, isteği doğrudan uygulamak yerine önce etkilenecek dosyaları ve çalıştıracağı komutları listeleyebilir; bu listeyi onayladıktan sonra değişiklik yapmasını isteyin. Örneğin, ‘Önce app/dashboard altındaki dosyaları listele, sonra kullanıcı listesi bileşenini oluştur’ gibi iki aşamalı komutlar verin. Hata çıktılarını ajana birebir yapıştırmak, sorunu doğru teşhis etmesini sağlar. Ajan bir hata düzeltmesi önerdiğinde, önce git diff ile neyin değiştiğine bakın; ajan bazen gereksiz bağımlılık ekleyebilir. Aşağıdaki örnek istemler Next.js görevleri için başlangıç noktasıdır:
| Görev | Örnek istem |
|---|---|
| Yeni bir sayfa eklemek | app/urunler sayfasını server component olarak oluştur, ürün listesini getir ve loading.tsx ekle. |
| Route handler oluşturmak | app/api/contact route handler'ına POST isteği için zod doğrulaması ekle ve başarılı/fail yanıtı döndür. |
| İstemci bileşeni eklemek | components/SearchBar.tsx dosyasını client component olarak oluştur ve useState ile arama kutusu yap. |
| Test yazmak | lib/api.ts için Vitest birim testlerini yaz ve mevcut testlerin yanına ekle. |
| Hata ayıklamak | npm run build'de çıkan hatayı incele ve düzelt; hatayı birebir raporla. |
Bu örnekler, ajanın işi küçük parçalara bölmesine yardımcı olur. Her istemden sonra git diff ve test adımlarını tekrarlayın.
Next.js’te Codex’in iyi yaptığı işler ve dikkat edilecek tuzaklar
Codex, tekrarlayan kod üretiminde (boilerplate), dosya yönlendirmesine uygun sayfa oluşturmada, fetch çağrılarını sarmalamada ve temel form işleme mantığında başarılıdır. Route handler’larda standart yanıt formatları üretmek, metadata eklemek ve basit API istemcileri yazmak gibi işler hızlı ve doğru sonuç verir. Ancak Next.js’e özgü bazı tuzaklar vardır. Sunucu/istemci sınırı en kritik noktadır: ajan bazen bir server component’e onClick gibi olay ekleyebilir veya useState kullanmaya çalışabilir; bu derleme hatasına yol açar. Route handler’larda gelen istek gövdesini doğrulamayı atlayabilir; özellikle req.json() çağrısında hata yönetimi eksik kalabilir. Metadatalar ve generateMetadata fonksiyonları bazen yanlış yerde tanımlanabilir. next.config.js içindeki images.remotePatterns gibi ayarlar değiştirilirken dikkatli olun. Ayrıca Page Router’da getServerSideProps ile App Router’da fetch önbellekleme kuralları karışabilir. Kod incelemesinde use client direktifinin gereksiz yere eklendiğini veya kaldırıldığını kontrol edin. Her değişiklikten sonra npm run lint ve npm run build çalıştırarak bu hataları yakalayın. Codex’in genel kullanım ipuçları için Codex CLI nasıl kullanılır? Adım adım rehber sayfasına bakabilirsiniz.
Next.js’te test ve doğrulama
Codex ile testleri çalıştırırken komutları net belirtin. AGENTS.md içinde tanımlı npm test veya npm run test:unit gibi komutları kullanın. Test çıktısında hata varsa, tam hata mesajını ajana yapıştırın; ajan test dosyasını düzeltebilir. Vitest veya Jest ile birim testlerinde, bileşen testlerinde React Testing Library kullanılıyorsa, ajanın userEvent ve screen kullanımını bilmesini bekleyin. Playwright ile uçtan uca testlerde, ajan test senaryosunu yazabilir ama tarayıcı başlatma ve seçici stratejileri konusunda yanlış adımlar atabilir; testleri siz çalıştırıp sonuçları geri besleyin. npm run build ile derleme hatalarını, npm run lint ile ESLint uyarılarını, npx tsc --noEmit ile tip hatalarını kontrol edin. Ajan, hata düzeltmelerini küçük diff’ler halinde sunarsa incelemesi kolay olur. Her test geçtiğinde git diff ile son değişiklikleri gözden geçirin. E2E testlerinde ortam değişkenleri ve veritabanı durumu gibi dış bağımlılıklar varsa, ajan bunları bilmeyebilir; testleri çalıştırmadan önce gerekli servislerin ayakta olduğundan emin olun.
AgentVera ile birden fazla ajanı Next.js projesinde çalıştırma
Birden fazla Codex oturumunu aynı projede yönetmek için AgentVera kullanabilirsiniz. AgentVera, ajanların gerçek komut satırı araçlarını yan yana çalıştırır ve her biri kendi git worktree’sinde çalışarak dosyaların çakışmasını önler. Bir ajanın işi bittiğinde ikinci bir model otomatik kod incelemesi yapar ve bulguları dosya:satır olarak raporlar; bu, Next.js’teki sunucu/istemci sınırı hatalarını yakalamada değerlidir. Ayrıca checkpoints sayesinde her dönüşün anlık görüntüsü alınır ve tek tıkla geri alınabilir; böylece riskli bir refactor sonrası kolayca önceki duruma dönülür. Daha fazla bilgi için AgentVera nasıl kullanılır: ilk proje, ajanlar ve ızgara sayfasına bakın.
Sonuç
Codex, Next.js projelerinde günlük geliştirme hızını artıran pratik bir araçtır. İyi hazırlanmış bir AGENTS.md, küçük adımlı istemler ve düzenli test/diff döngüsü ile ajanın hatalarını en aza indirebilirsiniz. Sunucu/istemci sınırı ve route handler güvenliği gibi Next.js’e özgü konularda elle inceleme yapmayı unutmayın. Birden fazla ajan gerektiğinde AgentVera ile paralel çalışma ve otomatik inceleme süreci yönetilebilir.