Gemini CLI ile Next.js Projelerinde Kodlama Rehberi

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 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 yazısına göz atabilirsiniz.

# 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? 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.

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.