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

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

Claude Code’u Next.js projelerinde nasıl kullanacağınızı öğrenin: CLAUDE.md kurulumu, App Router kuralları, test doğrulama ve paralel ajan iş akışları.

**Kısaca:**

- Claude Code, Next.js projelerinde CLAUDE.md ile bağlamı okuyarak server/client sınırlarına uygun kod önerir.
- Çalışma döngüsü plan, küçük adım, test ve diff incelemesi üzerine kurulmalıdır.
- AgentVera ile birden fazla ajanı ayrı worktree’lerde paralel çalıştırarak çakışmaları önleyebilirsiniz.

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

```markdown
# 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](/blog/claude-code-plan-modu/) 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.

| Alan | Dikkat edilecek nokta |
| --- | --- |
| Server Component | Node.js API’leri ve `fs` kullanılabilir; hook veya tarayıcı API’si kullanılamaz. |
| Client Component | `"use client"` en üstte olmalı; server’dan geçen prop’lar serileştirilebilir olmalı. |
| Route Handler | Giriş doğrulaması, yetki kontrolü ve hata durum kodları atlanmamalı; gizli anahtarlar istemciye sızmasın. |
| Fetch/Cache | `fetch` varsayılan olarak cache’lenebilir; dinamik veri için `revalidate` veya `cache: 'no-store'` gerekebilir. |
| Metadata | `generateMetadata` yalnızca server component’te çalışır; client tarafında metadata üretilemez. |
| Hydration | Sunucu ve istemci çıktısı farklıysa hydration hatası oluşur; `Date`, `Math.random` gibi değerleri client tarafında üretin. |
| Dynamic Routes | `params` ve `searchParams` doğru şekilde okunmalı; tip güvenliği için generics kullanın. |
| Middleware | `middleware.ts` yalnızca Edge çalışma zamanında çalışır; ajanın Node API kullanmadığından emin olun. |

Ö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](/blog/claude-code-en-iyi-pratikler/) 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](/blog/birden-fazla-claude-code-ajani/) 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.

## Sık sorulanlar

**Claude Code Next.js projesinde nasıl başlatılır?** Proje klasöründe terminal açıp claude komutunu çalıştırmanız yeterlidir. Ajan proje dosyalarını ve CLAUDE.md talimatlarını okuyarak bağlamı anlar; ilk görev olarak mevcut yapıyı özetlemesini isteyebilirsiniz.

**CLAUDE.md’ye Next.js için neler yazılmalı?** Build, test, lint komutları; App Router veya Pages Router tercihi; server/client component kuralları; route handler, fetch cache ve metadata kullanımı; klasör yapısı ve ESLint kuralları yazılmalıdır.

**Claude Code, Next.js’in server ve client bileşen ayrımını anlar mı?** Evet, CLAUDE.md’de kurallar verildiğinde ajan server/client sınırını genellikle doğru uygular. Yine de "use client" eklenmesi gereken yerler ile hydration risklerini her değişiklikten sonra gözden geçirmek gerekir.

**Birden fazla Claude Code ajanı aynı Next.js projesinde çalışabilir mi?** Evet, ayrı git worktree’leri veya farklı özellik dalları kullanılarak paralel çalıştırılabilir. AgentVera gibi araçlar bu süreci tek pencerede yöneterek dosya çakışmalarını önler.

---

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