# Cursor Agent ile NestJS Projelerinde Pratik Rehber

Adres: https://agentvera.dev/blog/cursor-agent-ile-nestjs/ · Yayın: 2026-11-01

NestJS projelerinde Cursor Agent ile modül, controller, DTO ve test üretimi; AGENTS.md kuralları, yaygın hatalar ve doğrulama ipuçları.

**Kısaca:**

- Cursor Agent, NestJS’te modül ve DTO gibi tekrarlayan yapıları proje kurallarına uygun şekilde hızla üretir.
- AGENTS.md ve .cursor/rules dosyalarına komutlar, klasör düzeni ve DI güncelleme kuralları yazılmalıdır.
- Her ajan çıktısından sonra birim testler, e2e testler ve git diff ayrı ayrı doğrulanmalıdır.

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

```markdown
# 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:

| Görev | İyi prompt |
|---|---|
| Yeni modül | "ProductsModule oluştur; controller, service ve DTO dosyalarını ekle, app.module içine import et." |
| Yeni endpoint | "UsersController’a GET /users/:id endpoint’i ekle, DTO’suz veya gerekli parametre doğrulamasıyla birlikte çalışsın." |
| DTO doğrulama | "CreateUserDto’ya class-validator decorator’larını ekle: name zorunlu string, age optional number, email email formatında." |
| Repository/ORM | "TypeORM repository kullanarak UsersService’e findOneByEmail metodu ekle, UsersModule’de gerekli imports’ları güncelle." |
| Test yazma | "UsersService için birim testi yaz, mock repository kullan, başarılı ve hata durumlarını test et." |

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?](/blog/cursor-cli-nasil-kullanilir/) 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](/blog/paralel-yapay-zeka-kodlama-ajani-araclari/) 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.

## Sık sorulanlar

**Cursor Agent NestJS projesinde nasıl başlatılır?** Proje klasöründe terminal açıp cursor-agent komutunu çalıştırmanız yeterlidir. Ajan, AGENTS.md ve .cursor/rules dosyalarını okuyarak proje bağlamını yükler. Daha sonra yapmak istediğiniz değişikliği doğal dille yazabilirsiniz.

**AGENTS.md dosyasına NestJS için neler yazılmalı?** NestJS komutları (npm run test, npm run test:e2e, npm run lint), klasör düzeni ve modül bağlama kuralları yazılmalıdır. Ayrıca DTO doğrulama, repository enjeksiyonu ve migration dosyalarıyla ilgili sınırlamalar eklenmelidir.

**Cursor Agent ile oluşturulan DTO ve controller kodları nasıl test edilir?** Önce npm run test ile birim testleri, sonra npm run test:e2e ile uçtan uca testleri çalıştırın. ValidationPipe ayarlarını main.ts içinde doğrulayın ve git diff ile modül dosyalarındaki değişiklikleri inceleyin.

**Cursor Agent aynı anda birden fazla NestJS modülünde çalışabilir mi?** Evet, ancak aynı dosyalara yazılmaması için ayrı oturumlarda veya AgentVera gibi git worktree izolasyonu sağlayan bir araçla çalıştırılmalıdır. Aksi takdirde app.module.ts gibi ortak dosyalarda çakışma riski artar.

---

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