GitHub Copilot CLI ile NestJS projelerinde verimli çalışma

GitHub Copilot CLI, NestJS projelerinde terminalden copilot komutuyla çalışır ve modül, controller, provider, DTO, test gibi yapıları hızla üretmeye yardımcı olur. Verimli kullanım için .github/copilot-instructions.md veya AGENTS.md dosyasına projeye özgü talimatlar ekleyin ve ajanı küçük, test edilebilir adımlarla yönlendirin. Bu rehberde kurulum, çalışma döngüsü, tipik görevler ve sık yapılan hataları ele alıyoruz. Ajanı daha yakından tanımak için GitHub Copilot CLI’ye göz atabilirsiniz.

NestJS işleri için neden GitHub Copilot CLI

NestJS’in katmanlı yapısı ve decorator tabanlı sözdizimi, ajanın kalıpları hızlı yakalamasını sağlar. DI sayesinde provider’ları tanımlamak, DTO’larda class-validator kuralları eklemek, TypeORM veya Prisma repository’leri genişletmek gibi tekrarlayan işleri komutla yapabilir. Ajan, mevcut modül yapısını okuyup uygun dosyaları oluşturur; Jest testlerini güncelleyerek regresyonu azaltır. Örneğin, users modülünde yeni bir endpoint eklerken controller, servis metodu, DTO ve ilgili spec dosyasını tek seferde üretebilir. Böylece geliştirici, iş mantığına odaklanırken tekrarlayan kod yazımı azalır. Ajanın proje bağlamını anlaması için talimat dosyası kritik öneme sahiptir; bu dosya sayesinde NestJS’e özgü kurallar her oturumda hatırlanır. Ayrıca ajan, TypeORM’de find koşulları, Prisma’da where/include gibi sık kullanılan sorgu kalıplarını doğru şekilde yazar. Özellikle mevcut kod tabanındaki desenleri taklit etme yeteneği, yeni modüller eklerken tutarlılığı korur. Ajan aynı zamanda @Controller, @Get, @Post, @Body, @Param gibi decorator’ları kullanarak controller metodlarını oluşturur, ValidationPipe ile DTO doğrulamasını bağlar. GitHub Copilot CLI’yi adım adım kullanmayı öğrenmek için rehberi inceleyebilirsiniz.

Projeyi ajan için hazırlamak

.github/copilot-instructions.md veya AGENTS.md dosyasına build, test, lint komutları; klasör düzeni; modül başına sorumluluk; DTO doğrulama ve hata formatı; TypeORM/Prisma tercihini yazın. Kısa ve net olun. Bu dosya, ajanın her oturumda projeye özgü kuralları hatırlamasını sağlar. Örneğin, controller’ın sadece HTTP katmanı olduğunu, iş mantığının serviste tutulması gerektiğini, provider’ların asla new ile oluşturulmayacağını, TypeORM entity’lerinin forFeature ile import edileceğini belirtin. Ayrıca testlerde Test.createTestingModule kullanılması gerektiğini yazın. Dosya adlandırma kuralları (kebab-case dosyalar, PascalCase sınıflar), async/await zorunluluğu, exception’ların HttpException ile fırlatılması, logger olarak NestLogger kullanımı gibi detaylar da eklenebilir. Örnek dosya:

# NestJS proje talimatları

## Komutlar
- Kurulum: `npm install`
- Geliştirme: `npm run start:dev`
- Build: `npm run build`
- Lint: `npm run lint`
- Format: `npm run format`
- Birim test: `npm test -- <dosya>`
- E2E test: `npm run test:e2e`
- Migration: `npm run migration:generate`

## Klasör düzeni
- `src/modules/<modul>` her modül için
- `src/common` filtreler, guardlar, interceptorlar
- `src/config` yapılandırma
- `test` e2e testleri

## NestJS kuralları
- Controller sadece HTTP katmanı, iş mantığı serviste.
- DTO'lar class-validator decorator'ları ile doğrulanır; global ValidationPipe kullanılır.
- Provider'lar her zaman module `providers` listesine eklenir; asla doğrudan `new` ile oluşturulmaz.
- TypeORM entity'leri `forFeature` ile, Prisma servisi `PrismaModule` ile import edilir.
- Exception'lar `HttpException` veya türevleri ile fırlatılır; ham hata döndürme.
- Testlerde `Test.createTestingModule` kullanılır ve harici servisler mock'lanır.
- Tüm asenkron metodlar `async/await` kullanır, callback yok.
- Loglama için `Logger` sınıfı enjekte edilir, `console.log` kullanılmaz.
- Dosya adları kebab-case, sınıf adları PascalCase olmalı.

Bu dosyayı hazırlarken CLAUDE.md nasıl yazılır? rehberindeki ilkeleri uygulayabilirsiniz. Talimatlar ne kadar net olursa ajan o kadar tutarlı kod üretir.

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

Planı önce siz yapın. Ajanla şu döngüyü izleyin: hedefi tek cümleyle yazın, ajanın plan önermesini isteyin, küçük adımlara bölün, her adımda ilgili testi çalıştırın, diff’i inceleyin, sonra bir sonraki adıma geçin. Bu döngü, hem ajanın yanlış yönlenmesini önler hem de geri dönüşü kolaylaştırır. Ajanın ürettiği kodu gözden geçirirken özellikle modül importları, DI token’ları ve validation kurallarını kontrol edin. Diff’i incelemek için git diff kullanabilirsiniz; ajanın yalnızca istenen dosyaları değiştirdiğinden emin olun. Ajan bir adımı tamamladıktan sonra test çıktısını paylaşmasını isteyin. Örnek promptlar:

• “users modülünde PATCH /users/:id endpoint’i ekle. UpdateUserDto içinde class-validator ile kısmi güncelleme kurallarını tanımla; mevcut users.service.spec.ts testlerini güncelle.”
• “TypeORM kullanarak iki tabloyu transaction içinde güncelleyen bir servis metodu yaz; hata durumunda rollback yap ve BadRequestException fırlat.”
• “Prisma şemasındaki User modeline deletedAt alanı ekle, migration oluştur ve servis katmanına soft delete davranışını uygula; ilgili e2e testini güncelle.”
• “Mevcut AuthModule içinde JWT guard’ı global olarak uygula; public route’lar için @Public() decorator’ı ekle ve testleri çalıştır.”
• “ProductsController içindeki listeleme metoduna sayfalama ve sıralama query parametreleri ekle; DTO’da IsInt, Min, IsIn kurallarını kullan.”
• “OrdersModule için CQRS pattern’i uygula; command, query, handler sınıflarını ve event’leri oluştur, mevcut testleri güncelle.”
• “Mevcut UserEntity üzerinde @BeforeInsert hook’u ile şifre hash’leme ekle; ilgili servis ve testleri güncelle.”

Bu promptlar, ajanın tipik NestJS görevlerini anladığını gösterir; ancak her zaman sonucu test edin. Ajanın ürettiği planı inceleyip gerekirse düzeltin; ajanın önerdiği dosya değişikliklerini onaylayın.

Ajanın iyi yaptığı işler ve dikkat edilecekler

Ajan, modül iskeleti, DTO, entity, repository, servis ve test şablonlarını hızlı üretir. TypeORM’de find koşulları, Prisma’da where/include yazımı gibi tekrarlayan sorguları doğru yapar. Ayrıca @Controller, @Get, @Post, @Body, @Param gibi decorator’ları kullanarak controller metodlarını oluşturur, ValidationPipe ile DTO doğrulamasını bağlar. Dikkat edilecekler: DI token uyumsuzluğu, module imports/providers eksikleri, class-validator gruplarının (groups) göz ardı edilmesi, e2e testlerinde gerçek veritabanına bağlanma, ConfigService kullanmadan process.env okuma, lifecycle hook’ların yanlış yerde kullanılması. Ayrıca büyük diff’lerde ajanın ilgisiz dosyaları değiştirmesi riski vardır; yapay zeka ajanları için kod haritası yaklaşımıyla ajanın nereye bakacağını sınırlayabilirsiniz. Özellikle circular dependency durumlarında ajan yanlış import yapabilir; forwardRef kullanımı gerektiğinde mutlaka kontrol edin. Ajan bazen any tipi kullanabilir, bu da NestJS’in DI ve tip güvenliğini bozar; tip tanımlarını inceleyin. Ajanın ürettiği exception’ların doğru HTTP durum kodlarını taşıdığından emin olun. Ayrıca ajan, büyük refactor işlerinde mevcut testleri yanlışlıkla silebilir veya güncellemeyi unutabilir; her değişiklikten sonra ilgili test suite’ini çalıştırın.

Test ve doğrulama

Ajan her değişiklikten sonra en az ilgili spec dosyasını çalıştırmalı. Siz de npm test -- <module> çalıştırıp çıktıyı inceleyin. E2E testlerde npm run test:e2e kullanın; ajanın test ortamını kirletmediğinden emin olun. Lint hatalarını npm run lint ile yakalayın. Özellikle NestJS’te TestingModule importlarının eksiksiz olduğunu, mock’ların gerçek repository yerine kullanıldığını ve ValidationPipe’un e2e testlerinde de aktif olduğunu doğrulayın. Ajanın testleri atlamasına izin vermeyin; “önce testi yaz, sonra kodu” promptu genellikle daha sağlam sonuç verir. Ayrıca test coverage raporunu kontrol ederek yeni eklenen kodun kapsandığından emin olun. Jest ile yazılan testlerde jest.spyOn veya mockResolvedValue kullanımını ajan doğru yapabilir; ancak mock’un kaldırılmadığı durumları gözden geçirin. Birim testlerinde Test.createTestingModule kullanarak provider’ları izole edin; gerçek veritabanı yerine in-memory repository veya mock kullanın. E2E testlerde supertest ile HTTP çağrıları yapın ve gerçek bir veritabanı bağlantısı gerekiyorsa test ortamı için ayrı bir veritabanı kullanın. Ajanın test verilerini temizlediğinden emin olun; afterAll hook’u ile bağlantıyı kapatın. Böylece testler tekrarlanabilir kalır.

Aynı projede birden fazla ajan: AgentVera

Birden fazla ajanı aynı NestJS projesinde koştururken AgentVera’nın ayrı git worktree desteği, modül bazlı paralel çalışmayı mümkün kılar; her ajan kendi worktree’sinde users veya products modülünü geliştirir, dosyalar çakışmaz. Ajan turu bittiğinde ikinci bir modelin otomatik kod incelemesi, DI ve import hatalarını file:line ile gösterir. Checkpoint’ler sayesinde hatalı bir değişiklik tek tıkla geri alınabilir. Token bütçeleri ise uzun NestJS görevlerinde maliyetin öngörülebilir kalmasını sağlar.

Sonuç

GitHub Copilot CLI, NestJS projelerinde talimat dosyası ve disiplinli döngüyle güçlü bir yardımcıdır. Küçük, test edilebilir adımlar verin; diff ve testleri her adımda kontrol edin; NestJS’e özgü DI, modül import ve doğrulama hatalarını yakından izleyin. Böylece ajan, tekrarlayan işleri alırken mimari bütünlük sizde kalır.