# Gemini CLI ile Next.js Projelerinde Kodlama Rehberi

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

Next.js projelerinde Gemini CLI ile nasıl çalışılır: GEMINI.md kurulumu, etkili promptlar, test ve doğrulama, paralel ajan kullanımı ve sık yapılan hatalar.

**Kısaca:**

- Gemini CLI, Next.js projesinde GEMINI.md talimatlarını okuyarak App Router, route handler ve test süreçlerinde hız kazandırır.
- Etkili kullanım için küçük adımlarla ilerleyin, her değişiklikten sonra lint, test ve build çıktılarını birlikte yorumlayın.
- Paralel ajanlarla çalışırken git worktree ve otomatik kod incelemesi Next.js’te çakışmaları azaltır.

Next.js projenizin kök dizininde terminalden `gemini` komutunu çalıştırdığınızda Gemini CLI, proje talimatlarını GEMINI.md dosyasından okur ve App Router, route handler, test ve lint işlerinde sizinle birlikte çalışır. Bu rehber; GEMINI.md kurulumu, etkili prompt yazımı, doğrulama adımları ve paralel ajan kullanımını Next.js özelinde ele alıyor. Daha temel kullanım için [Gemini CLI](/ajanlar/gemini-cli/) sayfasına göz atabilirsiniz.

## Gemini CLI neden Next.js işine uygun

Gemini CLI’nın Next.js projelerinde işe yaramasının birkaç somut nedeni var. Öncelikle dosya tabanlı yönlendirme ve klasör sözleşmelerine hâkim: `app/` altında `page.tsx`, `layout.tsx`, `loading.tsx`, `error.tsx`, `route.ts` gibi dosyaların rollerini bilir, yeni sayfa ve API uçları eklerken doğru dosyayı oluşturur. İkinci olarak, `next build` ve `tsc --noEmit` gibi komutların çıktısındaki hataları okuyup ilgili satıra müdahale edebilir; böylece TypeScript ve lint hatalarını hızlıca giderir. Üçüncüsü, Server Component ve Client Component ayrımını GEMINI.md kurallarıyla netleştirdiğinizde yanlış `use client` kullanımını azaltır. Pages Router kullanıyorsanız `getServerSideProps`, `getStaticProps`, `getStaticPaths` ve `_app.tsx`, `_document.tsx` gibi özel dosyaları da tanır.

## Projeyi ajan için hazırlama

Gemini CLI’nın en büyük avantajı, aynı depoda tekrar tekrar kullanılabilen bir GEMINI.md dosyasıdır. Dosyayı proje köküne koyun; komutlar, klasör düzeni ve Next.js kurallarını kısa ve net yazın. GEMINI.md’nin genel kullanımı için [Gemini CLI nasıl kullanılır? Adım adım rehber](/blog/gemini-cli-nasil-kullanilir/) yazısına göz atabilirsiniz.

```markdown
# GEMINI.md
## Komutlar
- Geliştirme: npm run dev
- Derleme: npm run build
- Lint: npm run lint
- Test: npm run test
- E2E: npm run test:e2e

## Klasör kuralları
- app/ altında App Router sayfaları ve route handler'ları
- components/ altında paylaşılan React bileşenleri
- lib/ altında veri erişimi ve yardımcılar

## Next.js kuralları
- Varsayılan olarak Server Component kullan; yalnızca etkileşim gerektiren kısımları 'use client' ile işaretle.
- Route handler'larda cookie, header veya searchParams kullanıyorsan dinamik davranışı göz önünde bulundur.
- next.config.js, middleware.ts ve ortam değişkenlerini değiştirmeden önce açıklama iste.
- ESLint kurallarına uy; import sırası ve kullanılmayan değişkenleri temizle.
- Tip kontrolü için her değişiklikten sonra npx tsc --noEmit çalıştır.
```

Bu dosyadaki komutlar ajana projenin standart iş akışını verir. `npm run test:e2e` gibi komutlar Playwright kullanıyorsanız e2e çalıştırma sürecini netleştirir. Klasör kuralları ajanın dosya oluştururken nereye koyacağını bilmesini sağlar. Next.js kuralları bölümünde özellikle varsayılan Server Component kullanımı, `'use client'` yalnızca gerçekten etkileşimli bileşenlere eklenmesi gerektiğini hatırlatır. Route handler dinamikliği kuralı, `cookies()` ve `searchParams` kullanıldığında Next.js’in otomatik olarak dinamik davranışa geçeceğini, ancak bunu statik olarak işaretlerseniz hata alacağınızı ajana öğretir. ESLint ve tip kontrolü komutlarını eklemek, ajanın her değişiklik sonrası doğrulama yapmasını sağlar. Ayrıca `middleware.ts` ve `next.config.js` gibi kritik dosyalarda değişiklik öncesi onay istemesi, yanlış yapılandırma riskini azaltır. Dosyayı zamanla, ajanın yaptığı hatalara göre güncelleyin; örneğin sürekli aynı hydration hatasını yapıyorsa ilgili kuralı ekleyin.

## Çalışma döngüsü ve örnek promptlar

Next.js’te Gemini CLI ile verimli çalışmanın yolu; görevi küçük adımlara bölmek, her adımda lint/test/build çıktısını görmek ve diff’i incelemektir. Her görev için yeni bir git branch açın, değişiklikleri küçük commit’lerle kaydedin. Ajanın tüm komutları kendisinin çalıştırmasına izin vermek yerine kritik komutları birlikte çalıştırın; örneğin `npm run dev` uzun süreli bir süreç başlatır, bunun yerine build ve test komutlarını isteyin. Prompt yazımı konusunda daha fazla ipucu için [Kodlama ajanları için prompt nasıl yazılır?](/blog/kodlama-ajanlari-icin-prompt-yazmak/) rehberine göz atın.

Tipik Next.js görevleri için kullanabileceğiniz promptlar:
- '`app/dashboard/page.tsx` içinde async Sunucu Bileşeni olarak kullanıcı listesini çek, yükleme durumunu `loading.tsx` ile göster ve `npm run lint` ile doğrula.'
- '`/api/users` route handler’ına GET ve POST ekle; `searchParams` okuyorsan Next.js dinamik davranışı koru, birim testini Vitest ile yaz.'
- '`pages/` altındaki eski sayfayı App Router’a taşı; `getServerSideProps` mantığını async Server Component’e çevir ve e2e testini çalıştır.'
- 'Bu client bileşenindeki useState ve useEffect mantığını gereksiz yere server’dan veri çekmeyecek şekilde düzenle, hydration uyarısı olmadığını doğrula.'
- 'Next.js middleware.ts içindeki basit auth yönlendirmesini yaz; çerez kontrolü yap ve `npm run build` ile doğrula.'
- '`app/api/products/route.ts` dosyasına hem GET hem POST ekle, GET’in `searchParams` desteklediğinden emin ol, `cache: no-store` gerektiren durumları yorumla ve Vitest ile birim testi yaz.'
- 'Yeni `app/products/[id]/page.tsx` sayfasını oluştur, `generateStaticParams` ile statik üretim yap, `loading.tsx` ve `error.tsx` ekle, `npm run build` ile doğrula.'
- '`components/UserAvatar.tsx` client bileşenini `useEffect` ile veri çekmekten kurtar, veriyi server component’ten props olarak geçir, hydration uyarısı olmadığını doğrula.'
- '`app/login` sayfasına server action ile form ekle, `useFormState` kullan, `revalidatePath` çağrısını ekle, Playwright ile form gönderimini test et.'

Her prompt sonrası ajanın ürettiği diff’i inceleyin; özellikle server/client sınırı ve dosya yapısı değişikliklerine dikkat edin. Ajan bazen gereksiz `'use client'` ekleyebilir veya dosyayı yanlış klasöre koyabilir.

## İyi olduğu işler ve dikkat edilmesi gerekenler

Gemini CLI; yeni sayfa ve route handler oluşturma, bileşenleri server/client olarak ayırma, ESLint hatalarını temizleme, test yazma, basit veri çekme fonksiyonlarını `lib/` altına taşıma gibi işlerde iyi sonuç verir. Ayrıca `next/link` ve `next/image` kullanımı, metadata API’si (`generateMetadata`), `next/font` entegrasyonu, ortam değişkenlerinin `NEXT_PUBLIC_` öneki ile client tarafına geçirilmesi gibi konularda da yardımcı olur. Pages Router’dan App Router’a dönüşümlerde de genellikle başarılıdır.

Ancak şu noktalarda diff’i dikkatle inceleyin:
- Client/server sınırı: ajan, `useEffect` veya `useState` kullanan bir bileşeni server component olarak bırakabilir; bu derleme hatasına veya runtime hatasına yol açar. Ayrıca server-only modülleri client’a import edebilir.
- Hydration hataları: `Date.now()`, `Math.random()`, `localStorage` veya `window` gibi tarayıcıya özgü değerleri server ve client’ta farklı üretebilir. Ajan bu durumu tespit etmekte zorlanabilir; doğrulamayı `npm run build` ve tarayıcı konsolu ile yapın.
- Caching ve dinamiklik: `fetch` ile veri çekerken `cache: 'no-store'` veya `revalidate` seçeneklerini doğru ayarlamayabilir; `cookies()`, `headers()`, `searchParams` kullanımı dinamik davranışı tetikler ama ajan bunu gözden kaçırabilir.
- Server action’larda `revalidatePath`, `redirect`, `notFound` çağrıları unutulabilir; form akışını e2e ile test edin.
- `middleware.ts` ve `next.config.js` değişiklikleri: ajan büyük yapılandırma değişiklikleri önerebilir; her değişikliği ayrı commit ile gözden geçirin.
- Test yanıltmacası: ajan testi geçirecek şekilde kodu değiştirebilir; testin anlamını koruyup korumadığını kontrol edin.

## Next.js için test ve doğrulama

Değişiklik yaptıktan sonra mutlaka lint, tip kontrolü, birim testleri ve build çalıştırın. Ajan bu komutları sizin adınıza çalıştırabilir, ancak çıktıları birlikte yorumlayın. Next.js için sunucu davranışını e2e (Playwright) ile, yükleme durumlarını ve hata sınırlarını da göz önünde bulundurarak test edin. Aşağıdaki tablo doğrulama hedeflerini ve Gemini CLI’nın rolünü özetler.

| Doğrulama hedefi | Komut | Gemini CLI’nin rolü |
|------------------|-------|---------------------|
| Lint hataları | `npm run lint` | Hataları listeler, düzeltme önerir ve değişiklik sonrası tekrar çalıştırır. |
| Tip güvenliği | `npx tsc --noEmit` | Tip hatalarını bulur, düzeltmek için dosyaları düzenler. |
| Birim testleri | `npm run test` | Testleri çalıştırır, başarısız olanları düzeltir, eksik testleri yazar. |
| Derleme | `npm run build` | Derleme hatalarını ve statik analiz uyarılarını gösterir, düzeltir. |
| E2E akışları | `npm run test:e2e` | Playwright testlerini çalıştırır, selector veya bekleme hatalarını düzeltir. |

Next.js projelerinde test stratejisini katmanlara ayırın: birim testler (Vitest veya Jest) `lib/` altındaki yardımcı fonksiyonları ve route handler’ları kapsar; bileşen testleri kullanıcı etkileşimini test eder; e2e testleri Playwright ile gerçek akışları doğrular. Gemini CLI, test dosyalarını oluşturmada ve başarısız testleri düzeltmede başarılıdır. Ancak ajanın yazdığı testin kalitesini her zaman kontrol edin: gerçek kullanıcı akışını taklit ediyor mu, yalnızca mutasyonu mu test ediyor, yoksa gereksiz mock’lar mı içeriyor? Sunucu bileşenlerini doğrudan test etmek zor olduğundan, veri çekme fonksiyonlarını ayrı modüllere taşıyın ve ajanın bu modülleri test etmesini isteyin. `next build` sonrası `next start` ile manuel doğrulama yapın; çünkü bazı hatalar yalnızca production ortamında görünür.

## Next.js projesinde birden fazla ajanla çalışmak

AgentVera, Gemini CLI gibi ajanları gerçek komut satırı araçlarıyla aynı pencerede yan yana çalıştırır. Next.js projelerinde en kritik özellikler: her ajanın kendi git worktree’sinde çalışarak dosyaları ezmemesi, iş bitiminde ikinci bir modelin kodu inceleyip file:line bulguları sunması ve token bütçeleriyle ajanın kontrolden çıkmasını engellemesidir. Böylece biri App Router geçişini yaparken diğeri route handler testlerini yazabilir; kod incelemesi server/client sınırı ihlallerini yakalar, token sınırı ise sonsuz döngüleri durdurur.

## Sonuç

Gemini CLI, Next.js projelerinde GEMINI.md ile doğru yönlendirildiğinde yeni sayfalar, route handler’lar, testler ve refactor işlerinde ciddi hız kazandırır. Ajanın önerilerini her zaman lint, tip kontrolü, test ve build ile doğrulayın; server/client sınırı ve hydration hatalarına karşı diff’e dikkat edin. Küçük adımlarla ilerleyip her değişikliği ayrı commit’te incelemek, Next.js projelerinde güvenli ve sürdürülebilir bir iş akışı sağlar.

## Sık sorulanlar

**Gemini CLI’yı Next.js projesinde nasıl başlatırım?** Proje kök dizininde terminalde gemini komutunu çalıştırmanız yeterlidir. Ajan, GEMINI.md dosyasındaki talimatları okur ve sizinle komut satırında etkileşimli çalışır.

**Gemini CLI Next.js App Router’ı ve Pages Router’ı destekliyor mu?** Evet, her iki yönlendirme yapısını da anlayabilir. Proje kökünde app/ veya pages/ klasörlerini algılayarak ilgili dosya düzenine göre öneriler üretir.

**Next.js projesinde GEMINI.md dosyasına neler yazmalıyım?** Build, lint, test komutları, klasör sözleşmeleri ve server/client bileşen kuralları gibi projeye özgü değişmez davranışları yazın. Ajan, her çalıştırmada bu dosyayı referans alır.

**Gemini CLI Next.js’te testleri çalıştırabilir mi?** Evet, npm run lint, npx tsc --noEmit, npm run test ve npm run build gibi komutları sizin adınıza çalıştırabilir. Başarısız testleri düzeltebilir, ancak son kararı e2e ve diff incelemesiyle siz verin.

---

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