Claude Code ve Next.js: Uygulamalı Geliştirme Rehberi

Claude Code’u bir Next.js projesinde kullanmak için proje klasöründe claude komutunu çalıştırmanız yeterlidir; ajan proje bağlamını okur ve sizinle aynı terminal üzerinden kod üretir, dosyaları düzenler ve testleri çalıştırır. Bu rehber, App Router ve Pages Router farklarını bilen geliştiriciler için CLAUDE.md kurulumu, çalışma döngüsü ve Next.js’e özgü tuzakları pratik biçimde ele alır. Claude Code’un genel kullanımı için Claude Code sayfasına bakabilirsiniz.

Neden Claude Code Next.js İşine Uygun?

Next.js projeleri dosya yapısıyla yönlendirilen, net sınırları olan bir mimariye sahiptir. Claude Code klasör ağacını, package.json’ı, tsconfig.json’u ve next.config dosyalarını okuyarak projeyi hızlı kavrar. App Router’da app/ altındaki sayfa, layout, loading ve error dosyalarını tanır; Pages Router’da pages/ ve getServerSideProps gibi kavramlara aşinadır. En önemlisi, siz CLAUDE.md içinde server/client bileşen kurallarını net tanımlarsanız, ajan bu sınırlara uygun kod üretir; "use client" eklemesi gereken yeri genellikle doğru tespit eder. Route handler’lar, metadata, fetch cache’i gibi Next.js’e özgü konularda da bağlam verildiğinde tutarlı öneriler sunar. Ayrıca, Next.js’in karmaşık build sürecini anlamak için next.config içindeki redirects, rewrites veya image ayarlarını okuyabilir; bu sayede ürettiği kod projenin mevcut yapılandırmasıyla çelişmez. Örneğin, next/image ile ilgili bir bileşen yazarken uzak sunucu izinlerini otomatik olarak göz önünde bulundurur.

Projeyi Ajana Hazırlama: CLAUDE.md

Claude Code, proje kökündeki CLAUDE.md dosyasını her oturumda okur. Bu dosya ne kadar net olursa ajan o kadar az yanlış varsayım yapar. Next.js projesi için en az şunları yazın:

• Kullanılan yönlendirici: App Router mı, Pages Router mı, yoksa ikisi birden mi?
• Komutlar: geliştirme, build, lint, birim test, E2E test.
• Klasör kuralları: bileşenler, route handler’lar, yardımcı fonksiyonlar nerede durur?
• Next.js’e özgü kurallar: server/client sınırı, fetch cache/revalidate, metadata, görsel optimizasyonu.
• Kod stili: ESLint, format, import sıralaması.

Gerçekçi bir CLAUDE.md örneği:

# CLAUDE.md

## Komutlar
- Geliştirme: `npm run dev`
- Derleme: `npm run build`
- Lint: `npm run lint`
- Birim test: `npm run test` (Vitest)
- E2E test: `npx playwright test`

## Next.js Kuralları
- Bu proje App Router kullanır; `app/` altındaki dosyalar varsayılan olarak Server Component’tir.
- State, effect veya tarayıcı API’si gerektiren bileşenlere dosyanın en üstüne `"use client"` ekle; bu direktifi gereksiz yere üst layout’a koyma.
- Route handler’lar `app/api/.../route.ts` içinde yer alır; her handler giriş verisini doğrula ve uygun HTTP durum kodu döndür.
- Fetch işlemlerinde Next.js’in varsayılan cache davranışını göz önünde bulundur; gerektiğinde `revalidate` veya `cache: 'no-store'` kullan.
- Metadata için `generateMetadata` fonksiyonunu server component’te kullan; client component’e metadata koyma.
- Görseller `next/image` ile kullanılır; uzak kaynaklar `next.config` içinde tanımlı olmalı.
- UI bileşenleri `components/ui`, sayfa bileşenleri `app/(routes)` altında tutulur.
- ESLint (`next/core-web-vitals`) kurallarına uy; hata varsa commit etme.

Pages Router kullanıyorsanız pages/api, getServerSideProps ve getStaticProps ile ilgili kuralları ayrıca ekleyin. Ayrıca, monorepo veya özel alias kullanıyorsanız bunları da belirtin; çünkü ajan import yollarını doğru üretmelidir. CLAUDE.md’yi güncel tutmak, her yeni geliştirici veya ajan oturumu için bağlamın taze kalmasını sağlar.

Çalışma Döngüsü: Planla, Küçük Adımlarla İlerle, Doğrula

Next.js’te büyük bir değişikliği tek seferde istemek yerine şu döngüyü kullanın:

1. Önce ajandan mevcut dosyaları incelemesini ve kısa bir plan çıkarmasını isteyin. Bu yaklaşımı Claude Code plan modu: önce planla, sonra yaptır yazısındaki gibi uygulayabilirsiniz. Plan, değişecek dosyalar, testler ve muhtemel riskler içermelidir.
2. Planı onayladıktan sonra tek bir görev verin; örneğin yalnızca route handler’ı değiştirmesini veya yalnızca client bileşeni eklemesini isteyin. Görevi ne kadar dar tutarsanız ajanın hata yapma olasılığı o kadar azalır.
3. Her adımdan sonra ilgili komutu çalıştırın: npm run lint, npm run test veya npx playwright test. Ajanın kendiliğinden test çalıştırmasını beklemeyin; siz isteyin ve çıktıyı birlikte yorumlayın.
4. git diff ile değişiklikleri inceleyin; özellikle server/client sınırı, cache davranışı ve route handler güvenliğini kontrol edin. Yanlış "use client" kullanımı veya eksik doğrulama varsa hemen düzeltme isteyin.
5. Sorun varsa düzeltme isteyin, yoksa bir sonraki küçük göreve geçin. Bu döngü, büyük bir özelliği yönetilebilir parçalara böler ve her aşamada doğrulama sağlar.

Tipik Next.js görevleri için kullanabileceğiniz örnek istekler:

• “app/dashboard altındaki kullanıcı listesini server component olarak yaz, veriyi fetch ile al, loading.tsx ekle ve hataları error.tsx ile yakala.”
• “Sepet bağlamını client component’e taşı; "use client" direktifini ekle, localStorage’a yalnızca useEffect içinde eriş.”
• “app/api/products/route.ts içinde GET handler oluştur, sorgu parametrelerini doğrula, eksikse 400 döndür, başarılıysa Response.json ile listeyi döndür.”
• “Kullanıcı formunda React Hook Form ile doğrulama ekle; gönderim sırasında hata mesajlarını Türkçe göster.”
• “Bu sayfanın erişilebilirlik sorunlarını gider, ardından npm run lint çalıştırıp temiz olduğunu doğrula.”

Bu istekleri verirken beklentinizi netleştirin: örneğin loading.tsx ve error.tsx kullanılmasını istiyorsanız açıkça belirtin. Ajan, istenmeyen optimizasyonlar yapabilir; bu yüzden görevi bitecek şekilde tanımlayın.

Tipik Next.js Görevleri ve Dikkat Edilmesi Gerekenler

Claude Code şu Next.js işlerinde iyi sonuç verir: server/client bileşen ayrımı, route handler yazımı, metadata ve SEO dosyaları, form doğrulama, fetch ile veri çekme, basit Playwright test senaryoları. Ancak aşağıdaki alanlarda mutlaka gözden geçirin; ajan bazen ince Next.js davranışlarını atlayabilir.

Özellikle hydration hataları Next.js’te en sık rastlanan sorundur; sunucu ve istemci çıktısı farklı olduğunda ajan bu hatayı tespit edemeyebilir. Bu yüzden her değişiklikten sonra tarayıcı konsolunu kontrol edin. Route handler’larda yetkilendirme ve hata durum kodları atlanabilir; bu nedenle tüm handler’ları güvenlik açısından inceleyin. Fetch cache’ini göz ardı edip bayat veri sunabilir; revalidate veya dynamic ayarlarını kontrol edin. Ajan "use client" eklemeyi unutabilir veya tam tersine gereksiz yere tüm bileşeni client’a çevirebilir; bu durum bundle boyutunu artırır.

Test ve Doğrulama

Claude Code, test komutlarını çalıştırabilir ve çıktıyı yorumlayabilir. Ancak ajanın her değişiklikten sonra testleri kendiliğinden çalıştırmasını beklemeyin; siz isteyin. CLAUDE.md’ye birim test ve E2E komutlarını yazdıysanız ajan doğru komutu bilir. Örneğin, bir route handler değişikliğinden sonra npm run test ile Vitest birim testlerini, kullanıcı akışı değişikliğinden sonra npx playwright test ile E2E testlerini çalıştırmasını isteyin. Ajan test yazarken Next.js’in asenkron server component’lerini ve route handler’larını doğru şekilde mock’lamalıdır; bu noktada test dosyalarını gözden geçirin. Doğrulama için Claude Code en iyi pratikler: uygulamalı kontrol listesi sayfasındaki kontrol listesini uygulayabilirsiniz. Ek olarak, Playwright testlerinde Next.js’in dev server’ını veya production build’ini kullanma farkını ajana hatırlatın; bazen dev server’da geçen test prod build’de başarısız olabilir. Vitest ile çalışırken server component’ler doğrudan test edilemez; bunları route handler veya API çağrıları üzerinden test etmek daha doğrudur. Ajan bu tür mimari kısıtları bilmediği için siz ipucu vermelisiniz.

Tek Projede Birden Fazla Ajan: AgentVera

Next.js projelerinde birden fazla özelliği paralel geliştirmek için AgentVera, her Claude Code ajanını kendi git worktree’sinde çalıştırarak dosya çakışmalarını önler; bu, aynı anda farklı route, bileşen veya API üzerinde çalışırken kritik önem taşır. Ajanın turu bittiğinde ikinci model kodu otomatik inceler ve server/client sınırı, route handler güvenliği gibi Next.js’e özgü hataları file:line ile işaretler, böylece manuel inceleme süresi kısalır. Token bütçeleri, ajanın kontrolsuz uzun oturumlar açmasını engeller; checkpoint’ler ise yanlış bir değişikliği tek tıkla geri almayı sağlar, önceki duruma hızla dönebilirsiniz. Bu yaklaşımı Birden fazla Claude Code ajanını paralel çalıştırma yazısındaki paralel çalıştırma örnekleriyle kurabilirsiniz.

Sonuç

Claude Code, doğru proje talimatları ve küçük adımlı çalışma döngüsüyle Next.js geliştirmede güçlü bir yardımcıdır. CLAUDE.md’ye harcadığınız on dakika, ajanın yanlış varsayımlarını büyük ölçüde azaltır. Her değişiklikten sonra lint, test ve diff incelemesi yaparak Next.js’e özgü hataları erken yakalayın; paralel işler için ayrı worktree’ler kullanın. Böylece ajan hem hız kazandırır hem de kod kalitesini korur. Unutmayın ki ajan bir yardımcıdır; nihai karar ve güvenlik denetimi sizde olmalıdır.