Cursor Agent ile NestJS Projelerinde Pratik Rehber

NestJS projesinde cursor-agent komutuyla başlatılan Cursor Agent, modül, controller, provider, DTO ve test gibi yapı taşlarını proje bağlamına uygun şekilde üretmek için kullanılır. Bu rehber, ajana NestJS projesinde nasıl talimat vereceğinizi, hangi dosyaları hazırlayacağınızı ve çıktıları nasıl doğrulayacağınızı adım adım gösterir. Amaç, sürekli aynı DI (Dependency Injection) ve modül bağlama hatalarını tekrarlamadan güvenli bir iş akışı kurmaktır.

Neden Cursor Agent NestJS işleri için uygundur?

NestJS kodu güçlü bir yapıya sahiptir: modül sınırları, decorator tabanlı controller’lar, provider’lar ve DTO doğrulama. Cursor Agent bu yapıyı AGENTS.md ve .cursor/rules dosyalarından okuyarak yeni eklediği kodları mevcut desenlerle uyumlu hale getirir. Örneğin bir UsersModule içinde yeni bir UsersController üretirken sadece controller dosyasını oluşturmakla kalmaz; UsersModule’ün controllers listesine ekler, UsersService’i provider olarak kullanır ve gerekli DTO’ları class-validator decorator’larıyla birlikte yazar. Bu, NestJS’in en çok vakit alan kısımlarından biri olan modül kablolamasını büyük ölçüde azaltır. Ayrıca TypeScript tipleri sayesinde ajan, Prisma veya TypeORM entity’lerinden DTO üretirken alan adlarını ve tiplerini doğru yakalar. Modül tabanlı yapı, ajanın dosya değişikliği yaparken kapsamı sınırlamasını kolaylaştırır; tek bir endpoint ekleme işi genellikle tek modül içinde kalır. Genel kullanım ayrıntıları için Cursor Agent sayfasına göz atabilirsiniz.

Projeyi ajan için hazırlamak: AGENTS.md ve .cursor/rules

Cursor Agent proje kökündeki AGENTS.md dosyasını, ayrıca .cursor/rules altındaki kural dosyalarını okur. NestJS projesi için bu dosyalara üç şey girmelisiniz: komutlar, klasör düzeni ve NestJS’e özgü sınırlamalar. Bu sayede ajan npm run start:dev yerine yanlış bir script çalıştırmaz, dosyaları yanlış klasöre koymaz ve DI güncellemelerini unutmaz. Aşağıdaki örnek, orta ölçekli bir NestJS projesi için iyi bir başlangıçtır:

# AGENTS.md

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

## Klasör düzeni
- Modül bazlı yapı: `src/modules/<module-name>/`
  - `controllers/`, `services/`, `dto/`, `entities/` (veya `repositories/`)
- DTO'lar class-validator decorator'ları ile doğrulanır.
- Test dosyaları: `*.spec.ts` birim, `test/*.e2e-spec.ts` uçtan uca.

## NestJS'e özgü kurallar
- Yeni bir controller veya provider eklerken ilgili modülün `controllers`, `providers` ve `exports` listelerini güncelle.
- Controller'larda iş mantığı yazma; her şey service katmanında olsun.
- DTO'larda `@IsString`, `@IsNumber`, `@IsOptional`, `@ValidateNested` kullan; nested DTO'larda `@Type(() => ...)` ekle.
- Veritabanı erişimini controller'a enjekte etme; repository veya Prisma servisini yalnızca service katmanına enjekte et.
- Global `ValidationPipe` kullanıyorsan `transform: true` ve `whitelist: true` ayarlarını koru.
- TypeORM migration veya Prisma schema değişikliklerinde önce migration dosyasını oluştur, sonra entity'yi güncelle.
- Her yeni endpoint için en az bir birim testi ve gerekirse bir e2e testi yaz.

Bu kurallar ajanın NestJS projesine ilk bakışta doğru desenleri öğrenmesini sağlar. Ayrıca .cursor/rules içine kısa, modül bazlı kural dosyaları koyabilirsiniz; örneğin validation.rules dosyasına DTO doğrulama kurallarını yazarsanız ajan her DTO üretiminde bunları uygular.

Çalışma döngüsü: planla, küçük adımlar at, testleri çalıştır, diff’i incele

Cursor Agent ile verimli çalışmanın anahtarı, büyük görevleri küçük parçalara bölmektir. Aşağıdaki döngüyü izleyin:

1. Plan: İstediğiniz değişikliği tek bir modül veya özellik olarak tanımlayın. Ajanın oluşturacağı dosyaları ve değiştireceği modül dosyalarını önceden düşünün.
2. Küçük adım: Ajandan tek bir iş yapmasını isteyin, örneğin “UsersModule içinde POST /users endpoint’i ekle, DTO’su ile birlikte”.
3. Testleri çalıştır: Ajan bitirdikten sonra hemen npm run test (birim) ve gerekirse npm run test:e2e çalıştırın.
4. Diff’i incele: git diff ile değişiklikleri gözden geçirin, özellikle modül dosyalarındaki değişiklikleri ve DI hatalarını kontrol edin.

Aşağıdaki tablo, tipik görevler için iyi yazılmış Türkçe prompt örneklerini göstermektedir:

Bu promptlar, ajanın tam olarak ne istediğinizi anlamasını sağlar. Ajan her seferinde değişiklikleri kendi içinde doğrulamaz; çıktıyı siz test ederek kabul edin. Terminal tabanlı ajan kullanımı hakkında daha fazla pratik bilgi için Cursor CLI nasıl kullanılır? yazısına bakabilirsiniz.

Tipik görevlerde güçlü yönler ve dikkat edilmesi gerekenler

Cursor Agent, NestJS’te şu görevlerde oldukça iyidir:

• Yeni modül, controller ve service iskeleti oluşturma.
• Mevcut entity veya DTO’lardan yola çıkarak CRUD endpoint’leri üretme.
• class-validator decorator’larını doğru şekilde ekleme.
• Jest birim testleri için mock’lu test şablonları yazma.
• Prisma schema veya TypeORM entity değişikliklerine göre migration dosyalarını güncelleme.

Ancak şu noktalarda ajanı yakından izleyin:

• DI bağlama hataları: Ajan bazen yeni bir provider eklerken providers listesine eklemeyi unutabilir. Diff’te modül dosyalarını özellikle kontrol edin.
• Circular dependency: Ajan iki modül arasında dairesel bağımlılık oluşturabilir. forwardRef kullanımı gerektiğinde uyarın.
• Validation pipe ayarları: Ajan global pipe ayarlarını değiştirmeye kalkarsa dikkatli olun; whitelist: true özelliğini sessizce kaldırmamalı.
• E2E testleri: Ajan bazen e2e testlerinde gerçek veritabanı bağlantısı gerektiren kod yazar. Test ortamını izole edin.
• Ortak dosyalar: app.module.ts, main.ts gibi dosyalar birden fazla değişiklikte çakışabilir; ajanı paralel çalıştırırken her ajanı kendi worktree’sinde tutun.

Bu hataların çoğu, düzenli test ve diff incelemesiyle yakalanır.

Test ve doğrulama

NestJS’te ajan çıktısını doğrulamak için üç katman kullanın:

1. Birim testler: npm run test ile service ve controller testlerini çalıştırın. Ajanın yazdığı testler yeşil mi, yoksa kırılıyor mu? Kırılıyorsa ajan muhtemelen DI veya mock yapısını yanlış kurmuştur.
2. E2E testler: npm run test:e2e ile uçtan uca senaryoları doğrulayın. Özellikle yeni endpoint’ler için bir e2e testi yazıp ajanın bu testi geçtiğinden emin olun.
3. Lint ve derleme: npm run lint ve npm run build ile tip hatalarını ve kod stili sorunlarını yakalayın. NestJS projelerinde decorator’ların doğru kullanılmaması derleme hatasına yol açar.

Ajan her çalıştırmadan sonra bu üç adımı manuel veya script ile çalıştırın. Ajanın kendi kendine test çalıştırmasını istiyorsanız, AGENTS.md içine “her değişiklikten sonra testleri çalıştır ve hata varsa düzelt” gibi bir kural ekleyebilirsiniz.

Birden fazla ajanı aynı NestJS projesinde çalıştırmak: AgentVera

Tek bir NestJS projesinde birden fazla Cursor Agent oturumu açtığınızda, aynı dosyalara yazmaları çakışmalara yol açar. AgentVera, her ajanı kendi git worktree’sinde çalıştırarak bu sorunu çözer; böylece ajanlar paralel olarak farklı modüller üzerinde çalışırken birbirlerinin dosyalarını ezmez. Ayrıca otomatik kod incelemesi sayesinde bir ajanın işi bittiğinde ikinci bir model değişiklikleri gözden geçirir ve hataları dosya:satır olarak gösterir. Token bütçeleri, ajanın uzun süreli görevlerde bütçeyi aşmasını engeller ve bildirimler sayesinde onay bekleyen ajanları tek kuyruktan yönetirsiniz. Bu özellikler, NestJS projelerinde modül başına paralel görev dağıtımı için kritik öneme sahiptir.

Sonuç

Cursor Agent, NestJS projelerinde tekrarlayan yapıları hızla üretmek ve modül bağlamını korumak için güçlü bir yardımcıdır. Başarılı bir kullanım için proje kurallarını AGENTS.md dosyasına yazın, görevleri küçük parçalara bölün ve her çıktıyı test edip diff’ini inceleyin. Paralel çalışma gerektiğinde paralel kodlama ajanları için en iyi araçlar listesine göz atabilirsiniz. Böylece NestJS geliştirme hızınızı artırırken DI ve modül hatalarını minimumda tutarsınız.