# Codex ile Next.js projelerinde pratik rehber

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

Codex ile Next.js projelerinde AGENTS.md kurulumu, çalışma döngüsü, test ve doğrulama ipuçları. Sunucu/istemci bileşenleri ve route handler’lar için pratik öneriler.

**Kısaca:**

- Codex’i Next.js projesinde kullanmak için AGENTS.md dosyasına build, test ve lint komutlarıyla klasör kurallarını ekleyin.
- Sunucu/istemci bileşeni sınırlarını ve route handler değişikliklerini küçük adımlarla planlayıp her adımda testleri çalıştırın.
- Kod incelemesi, test ve çoklu ajan yönetimi için AgentVera iş akışını kullanabilirsiniz.

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](/ajanlar/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:

```markdown
# 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](/blog/baglam-muhendisligi/) 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](/blog/codex-cli-nasil-kullanilir/) 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](/blog/agentvera-nasil-kullanilir/) 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.

## Sık sorulanlar

**Codex’i Next.js projesinde nasıl başlatırım?** Proje klasöründe terminalde codex komutunu çalıştırın. Codex, AGENTS.md dosyasını okur ve proje yapısını anlamak için dosyaları inceler. İlk kullanımda oturum açmanız gerekebilir.

**Codex Next.js’te server ve client component ayrımını anlıyor mu?** Codex, Next.js dokümantasyonunu ve proje kodunu analiz ederek \"use client\" direktiflerini ve sunucu/istemci sınırlarını genellikle doğru uygular. Yine de kritik değişikliklerde hataları gözden geçirmek gerekir.

**Codex ile Next.js’te testleri nasıl çalıştırırım?** Codex’e \"npm test\" gibi test komutunu çalıştırmasını söyleyebilirsiniz. Test hatası çıktılarını okuyup düzeltme önerebilir. Test komutları AGENTS.md içinde tanımlıysa daha tutarlı davranır.

**AGENTS.md dosyası Codex için neden önemli?** AGENTS.md, proje komutları, klasör yapısı ve kurallar gibi bağlamı Codex’e tek seferde verir. Böylece Codex her seferinde aynı komutları ve kuralları tekrar keşfetmek zorunda kalmaz.

---

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