Gemini CLI ile NestJS: Pratik Kullanım Rehberi

Gemini CLI, NestJS projelerinde terminalden gemini komutuyla çalışan bir kodlama ajanıdır. Gemini CLI hakkında genel bilgiye ve Gemini CLI nasıl kullanılır? adım adım rehberine bakabilirsiniz. NestJS’in modül sistemi, dependency injection ve decorator ağırlıklı yapısına uygun şekilde GEMINI.md ile yapılandırıldığında; DTO, controller, provider ve test üretiminde ciddi zaman kazandırır. Bu rehberde kurulum, çalışma döngüsü ve doğrulama pratikleri anlatılıyor.

Neden Gemini CLI NestJS işlerine uygun?

NestJS projeleri TypeScript, decorator ve katmanlı mimari üzerine kuruludur; bu da ajanın statik analiz ve örüntü eşleştirme yapmasını kolaylaştırır. Gemini CLI mevcut kodu okuyup projeye özgü kalıpları takip edebilir: örneğin UsersModule içindeki bir controller’ın nasıl yazıldığını görüp yeni bir endpoint için aynı stili uygular. Böylece her seferinde sıfırdan açıklama yapmak yerine, class-validator dekoratörleri, constructor injection ve @Module metadata’sı gibi NestJS’e özgü kuralları GEMINI.md üzerinden hatırlatırsınız. Ajan özellikle tekrar eden işlerde iyidir: DTO üretimi, provider kaydı, guard/interceptor ekleme ve Jest test iskeleti. Ancak NestJS’in çalışma zamanı davranışını (lifecycle hook sırası, request-scoped provider’lar, modül çözümleme) tahmin etmekte zorlanabilir; bu yüzden her değişiklik test ve diff ile doğrulanmalıdır. Ajan, ayrıca büyük refactorlerde mevcut dosya bağımlılıklarını analiz edip hangi modüllerin etkileneceğini çıkarabilir; bu, DI grafiği karmaşık projelerde planlama süresini kısaltır.

Projeyi ajan için hazırlamak: GEMINI.md

Gemini CLI, proje kökündeki GEMINI.md dosyasını otomatik olarak okur. Bu dosya, ajanın projeyi nasıl kurup test edeceğini ve hangi kurallara uyacağını bilmesini sağlar. NestJS projesi için GEMINI.md kısa ama net olmalıdır; build, test, lint komutları, klasör düzeni ve NestJS’e özgü DI/DTO kuralları yer almalıdır. Aşağıdaki örnek, orta ölçekli bir proje için yeterli bir başlangıçtır.

## Komutlar
- Kurulum: `npm install`
- Geliştirme: `npm run start:dev`
- Test: `npm run test`
- Lint: `npm run lint`
- Derleme: `npm run build`

## Klasör yapısı
- `src/modules/<modül>/` altında controller, service, dto, entity/repository
- Ortak kod `src/common/` içinde

## NestJS kuralları
- Tüm DTO'larda class-validator dekoratörleri kullan; `whitelist: true` ve `transform: true` global ValidationPipe ile uygula.
- Provider'lar yalnızca constructor injection ile alınır; property injection kullanma.
- Her yeni provider ilgili `@Module` içindeki `providers` dizisine eklenmeli; gerekirse `exports` yapılmalı.
- Dairesel bağımlılık oluşturma; gerekiyorsa `forwardRef` kullan ama önce tasarımı gözden geçir.
- Veritabanı erişiminde TypeORM repository veya Prisma service kullan; servis dışında doğrudan veritabanı çağrısı yapma.
- Testler Jest ile `*.spec.ts` dosyalarında; servis birim testlerinde repository mock'lanır.

Bu dosyayı güncel tutmak önemlidir; örneğin yeni bir global exception filter eklediyseniz, bu kuralı da GEMINI.md’ye yazın. Ajan, bu kurallara uymadığında doğrudan düzeltme isteyin; böylece proje tutarlılığı korunur. Ayrıca, proje büyüdükçe GEMINI.md’yi bölümlere ayırabilirsiniz: mimari notlar, ortak servislerin kullanımı, API yanıt formatı gibi. Önemli olan, ajanın her oturumda aynı bağlamı alması ve tutarsız kod üretmemesidir.

Çalışma döngüsü: planla, küçük adım at, test et, diff’i incele

Gemini CLI ile verimli çalışmak için her isteği tek bir sorumluluğa indirin. Ajanın önce ilgili dosyaları okumasını, ardından değişiklik önerisini göstermesini isteyin. Değişiklik sonrası git diff ile inceleyin ve npm run test ile doğrulayın. Aşağıdaki promptlar tipik NestJS görevlerini kapsar; hepsi Türkçe yazılmıştır.

• Mevcut UsersModule’ü incele; eksik olan DELETE /users/:id endpoint’ini ekle, UsersController içinde method oluştur ve UsersService.delete metodunu repository ile uygula.
• CreateUserDto’ya email için @IsEmail() ve password için @MinLength(8) dekoratörlerini ekle; UsersController’da global ValidationPipe zaten var, dokunma.
• UsersService için Jest birim testleri yaz; repository’yi mockla, findOne ve save davranışlarını test et.
• AuthModule’de JwtModule.registerAsync kullanarak ConfigService’ten secret çek; AuthService’e giriş metodunu ekle ve UsersService’i inject et.
• npm run test ve npm run lint çalıştır; çıkan hataları tek tek düzelt, her düzeltmeden sonra ilgili testi tekrar koş.
• UsersModule’e yeni bir özellik olarak ‘lastLoginAt’ alanı ekle; DTO, entity ve service methodlarını güncelle, migration veya Prisma schema değişikliğini de hatırlat.
• Tüm controller’larda hata yanıtlarını standartlaştırmak için global bir exception filter oluştur; mevcut hata fırlatma noktalarını tespit et ve uyumlu hale getir.

Daha etkili prompt kalıpları için kodlama ajanları için prompt yazmak yazısına göz atabilirsiniz. Ajan her adımda çalıştırdığı komutların çıktısını size gösterebilir; test hatalarını kendisi düzeltebilir. Ancak düzeltmelerin kapsamını siz belirleyin, ajanın projede istenmeyen değişiklikler yapmasına izin vermeyin.

Tipik NestJS görevleri ve dikkat edilecek tuzaklar

Ajan; CRUD modülü üretimi, DTO doğrulama, provider kaydı ve birim testleri gibi işleri genellikle iyi yapar. Ancak NestJS’in modül metadata’sı, dependency injection çözümlemesi ve lifecycle sırası hata üretmeye açıktır. Aşağıdaki tablo, en sık karşılaşılan durumları özetler.

| Görev | Ajan genelde iyi | Dikkat edilecek nokta | | CRUD modülü üretimi | Controller/service/DTO iskeletini tutarlı üretir | Modül metadata’sına provider eklemeyi unutabilir | | DTO doğrulama | class-validator dekoratörlerini doğru uygular | Global pipe ayarları yoksa hata mesajları farklı olur | | Birim testleri | Jest ve Nest testing module kullanımını bilir | Mock’lar aşırı basit kalabilir, gerçek davranışı kaçırabilir | | TypeORM/Prisma entegrasyonu | Repository enjeksiyonu ve sorguları yazar | Migration veya şema değişikliği yapmadan kod üretebilir |

Özellikle dairesel bağımlılıklarda ajan forwardRef önerebilir; bu geçerli bir çözüm olsa da önce modül sınırlarını yeniden düşünmek daha sağlıklıdır. Request-scoped provider’lar, guard/interceptor sırası ve exception filter kapsamı gibi konularda ajanın ürettiği kod çalışsa bile davranış beklendiği gibi olmayabilir; bu yüzden her değişiklikten sonra e2e testi veya manuel istek atarak doğrulayın. Bir diğer tuzak, ajanın mevcut global ayarları (validation pipe, interceptors, filters) göz ardı edip yeni bir controller’a gereksiz yerel pipe eklemesidir. Bu tür tutarsızlıkları diff incelerken fark edebilirsiniz. Ajan ayrıca veritabanı şeması ve entity arasındaki senkronizasyonu tam kuramayabilir; bu yüzden TypeORM migration veya Prisma migrate komutlarını ajanın önerdiği değişikliklerden sonra kendiniz çalıştırın.

Test ve doğrulama

NestJS projelerinde test, ajanla çalışmanın en kritik adımıdır. Ajan test yazdıktan sonra mutlaka kendiniz npm run test, npm run lint ve npm run build komutlarını çalıştırın. Birim testlerinde Test.createTestingModule kullanımı, NestJS’in DI konteynerini taklit ettiği için ajanın ürettiği mock’lar gerçek repository davranışını tam yansıtmayabilir; bu yüzden kritik servisler için ek test senaryoları isteyin. E2E testlerinde supertest ile controller seviyesinde doğrulama yapın. Ajanın npm run test çıktısını okumasını ve hataları kendisinin düzeltmesini isteyebilirsiniz; ancak son onayı git diff ile siz verin. Doğrulama sırasında yalnızca testlerin geçmesine değil, üretilen kodun mevcut mimariyle uyumuna da bakın. Özellikle DI hataları genellikle test sırasında ortaya çıkar; ajan bu hataları çözmek için eksik provider’ı eklemek yerine gereksiz forwardRef ekleyebilir. Bu durumda ajanı uyarın ve modül tasarımını birlikte düzeltin.

Birden çok ajanı AgentVera ile yönetmek

AgentVera, Gemini CLI gibi terminal ajanlarını aynı pencerede paralel çalıştırır; her ajan kendi git worktree’sinde ilerleyebildiği için aynı NestJS projesinde modüller çakışmadan geliştirilebilir. Ajan turu bittiğinde ikinci bir model kod incelemesi yapar; bu, DI hataları veya eksik provider kayıtları gibi NestJS’e özgü sorunları yakalar. Her turun checkpoint’i alınır ve tek tıkla geri alınabilir; token bütçeleri ise ajan başına maliyet ve kapsam kontrolü sağlar. Bu sayede paralel çalışma güvenli hale gelir.

Gemini CLI, doğru GEMINI.md ve disiplinli bir çalışma döngüsüyle NestJS projelerinde güvenilir bir yardımcıdır. Küçük adımlar atın, testleri sürekli çalıştırın ve diff’i inceleyin. Birden çok ajan kullanacaksanız, git worktree ve kod incelemesi gibi mekanizmalarla değişiklikleri izole edin. Böylece NestJS’in DI ve modül karmaşıklığını ajanla birlikte yönetebilirsiniz.