Claude Code ile NestJS Projelerinde Pratik Kullanım Rehberi

Claude Code, proje klasöründe claude komutuyla başlayan bir kodlama ajanıdır. NestJS projelerinde modül, controller, provider ve DTO katmanlarını doğrudan dosya sistemi üzerinde oluşturup düzenleyebilir. Bu rehber, NestJS’e özgü kurulum, çalışma döngüsü, test ve paralel ajan kullanımını pratik biçimde anlatır. Daha genel kurulum için Claude Code sayfasına bakabilirsiniz.

Claude Code NestJS projelerinde neden iyi çalışır

NestJS katmanlı yapısı ve güçlü konvansiyonları sayesinde ajan için elverişli bir hedeftir. @Module, @Controller, @Injectable gibi decorator’lar dosya içeriğinden niyeti açıkça gösterir; TypeScript tipleri de üretilen kodun şeklini sınırlar. Claude Code, tekrar eden boilerplate’i hızlı üretebilir: yeni bir modül, controller, service, DTO ve test iskeleti birkaç istemde hazır olur. Ayrıca dependency injection hatalarını, eksik provider kayıtlarını ve class-validator dekoratör eksiklerini tespit edip düzeltebilir. Örneğin ajan, yeni bir OrdersModule oluştururken servis ve controller’ı doğru klasöre koyabilir, module metadata’ya ekleyebilir ve DTO’yu class-validator ile donatabilir. Bu, geliştiricinin el yazımıyla geçen süreyi ciddi biçimde azaltır. Ancak bu değeri görmek için projeye özgü kuralların CLAUDE.md içinde net yazılması gerekir.

Claude Code’un NestJS’e uyumunun bir nedeni de ajanın çalışma biçimidir: dosya okur, dosya yazar ve terminal komutu çalıştırır. NestJS projeleri genellikle src/modules altında küçük dosyalara bölündüğü için ajan bir modülü değiştirirken tüm projeyi değil yalnızca ilgili dosyaları okur. Bu, context penceresinin verimli kullanılmasını sağlar. Öte yandan ajan, import yollarını ve modül exports listesini güncelleme konusunda bazen yanılabilir; bu yüzden her değişiklikten sonra derleme ve test şarttır. TypeORM ve Prisma gibi ORM’lerle çalışırken de entity tanımlarındaki dekoratörler veya Prisma schema dosyası ajan tarafından kolayca düzenlenebilir, ancak migration üretimi gibi geri dönüşü zor adımları manuel kontrol etmek gerekir.

Projeyi Claude Code için hazırlama ve CLAUDE.md

Ajan proje kökündeki CLAUDE.md dosyasını okur. NestJS projesinde bu dosyaya en az üç şey girin: kullanılan komutlar, klasör düzeni ve NestJS’e özgü kurallar. Aşağıdaki örnek küçük bir API projesi için yeterlidir.

# CLAUDE.md

## Komutlar
- Kurulum: `pnpm install`
- Build: `pnpm build`
- Test: `pnpm test`
- Test tek dosya: `pnpm test -- src/users/users.service.spec.ts`
- Lint: `pnpm lint`

## Klasör düzeni
- `src/` altında her modül kendi klasöründe: `users/`, `auth/`, `orders/`.
- Her modülde: `*.module.ts`, `*.controller.ts`, `*.service.ts`, `dto/`, `entities/` veya `repositories/`.
- Paylaşılan guard, interceptor ve decorator'lar `src/common/` altında.

## Kurallar
- Dependency injection'ı constructor üzerinden yap; asla `new` ile provider üretme.
- DTO'larda her alan için class-validator dekoratörü kullan.
- Controller sadece HTTP katmanıdır; iş mantığını service'e yaz.
- Modül metadata'sında controller ve provider listesini eksiksiz tut.
- Testlerde `Test.createTestingModule` kullan; gerçek veritabanına bağlanma.

Bu dosya, ajan yanlış bir import yolu seçtiğinde veya new UsersService() yazdığında kendini düzeltmesini sağlar. Kurallar kısa ve kesin olmalı; çok uzun CLAUDE.md ajanın dikkatini dağıtabilir. CLAUDE.md ayrıca ajan yanlış varsayım yaptığında düzeltme maliyetini düşürür. Örneğin pnpm yerine npm kullanmaya çalışırsa komut satırından hata alır; dosyayı kontrol edip doğru komuta döner. NestJS’te app.useGlobalPipes(new ValidationPipe()) gibi global ayarlar da burada belirtilebilir; böylece ajan DTO doğrulamasının nerede yapıldığını bilir.

CLAUDE.md’ye ayrıca ortam değişkenleri ve yapılandırma dosyalarının yerlerini eklemek faydalıdır. Örneğin .env dosyasının kökte olduğunu ve ConfigModule.forRoot({ isGlobal: true }) kullanıldığını belirtin. Eğer e2e testler varsa komutlarını (pnpm test:e2e) ve çalıştırma ön koşullarını (veritabanı gerektirip gerektirmediği) yazın. Lint kuralları katıysa (no-explicit-any gibi) ajanın any kullanmaması için bunu açıkça söyleyin. Ajan, bu dosyayı her turda yeniden okuyabilir; bu nedenle güncel tutmak önemlidir. Proje büyüdükçe yeni kuralları ekleyin, eskiyen komutları kaldırın.

NestJS’te çalışma döngüsü ve örnek istemler

Claude Code ile çalışırken en verimli döngü şudur: önce ajanın neyi değiştireceğini kısa bir planla özetlemesini isteyin, sonra küçük bir diff üretmesini söyleyin, test ve build komutlarını çalıştırın, ardından git diff ile değişiklikleri okuyun. Her turda yalnızca bir modül veya bir davranış üzerinde çalışın. Plan aşaması için Claude Code plan modu yazısındaki yöntemleri kullanabilirsiniz.

NestJS için kullanabileceğiniz örnek istemler:

• Yeni bir ProductsModule oluştur; ProductsController ve ProductsService ekle. CreateProductDto içinde name zorunlu string, price pozitif number olsun ve class-validator ile doğrula. Unit testleri Test.createTestingModule ile yaz.
• Mevcut UsersService.create metoduna e-posta çakışması kontrolü ekle. Çakışma varsa ConflictException fırlat, yoksa kullanıcıyı oluştur. İlgili unit testleri güncelle.
• JwtAuthGuard sınıfını src/common/guards altına taşı ve UsersController üzerinde @UseGuards(JwtAuthGuard) olarak uygula. Eksik importları module metadata’da düzelt.
• TypeORM Order ve OrderItem entity’leri arasına one-to-many ilişkisi kur; DTO’ları ve servis metodlarını buna göre güncelle, migration üretme.
• AppModule içinde ConfigModule yapılandırmasını global hale getir; UsersService içinde ConfigService enjekte edip JWT_SECRET değerini oku. Testte ConfigService mock’la.

Bu istemlerin ortak noktası kapsamın dar tutulmasıdır. Ajan aynı anda üç modülü değiştirdiğinde diff karmaşıklaşır ve NestJS DI hatalarını tespit etmek zorlaşır. Ajan çalışırken terminalde ne yaptığını izleyin; uzun süren bir işlem görürseniz durdurup daha küçük bir görev verin. Her tur sonunda git diff çıktısını okuyun ve değişen dosyaları tek tek açıp inceleyin. Ajan doğru görünen ama NestJS konvansiyonlarına aykırı bir şey yaptıysa, düzeltmek için spesifik bir geri bildirim verin.

Claude Code’un iyi yaptığı NestJS işleri ve dikkat edilecek yerler

Claude Code; yeni modül iskeleti çıkarma, DTO’lara class-validator ekleme, repository enjeksiyonu, Jest ile provider mock’lama ve modül import/export düzeltmelerinde oldukça başarılıdır. Buna karşılık NestJS’e özgü birkaç noktada yakından izlemek gerekir. En sık sorun, iki servisin birbirini enjekte etmesiyle oluşan dairesel bağımlılıktır; ajan forwardRef kullanmadan çözmeye çalışabilir veya çözümü karmaşıklaştırabilir. Bir diğer nokta global ValidationPipe kullanılmıyorsa, DTO doğrulamasının çalışmadığını fark etmeden sadece decorator ekleyebilir. TypeORM veya Prisma ile çalışırken migration dosyalarını elinizle incelemeden kabul etmeyin; ajan bazen şema değişikliğini yanlış sırayla üretebilir. Ayrıca testlerde gerçek veritabanına bağlanmak isteyebilir; bunu CLAUDE.md’de yasaklayın. Ajan ayrıca @Injectable() dekoratörünü unutabilir veya exports listesine bir provider’ı eklemeyi atlayabilir. Modül sınırları arasında enjeksiyon yaparken exports listesini her zaman kontrol edin.

Ek olarak ajan, @InjectRepository ile TypeORM repository enjeksiyonunda yanlış entity ismi verebilir veya Prisma servisini module provider olarak eklemeyi unutabilir. Transaction yönetimi konusunda dikkatli olun: ajan, dataSource.transaction kullanmadan birden fazla repo işlemini tek tek yapabilir. NestJS’in yaşam döngüsü hook’ları (OnModuleInit, OnApplicationBootstrap) nadiren kullanılır; ancak ajan bu hook’lara gerek olmayan yerde iş mantığı ekleyebilir. Guard ve interceptor’ları yazarken ExecutionContext tiplerini doğru kullanması önemlidir. Ajanın yazdığı unit testler bazen yalnızca expect(true).toBe(true) gibi anlamsız olabilir; test kalitesini kontrol edin.

NestJS’te test ve doğrulama

Claude Code’un yazdığı kodu kabul etmeden önce üç komutu sırayla çalıştırın. Bu komutlar NestJS’in katmanları arasındaki hataları yakalar: build TypeScript ve decorator hatalarını, test DI ve iş mantığı hatalarını, lint ise import düzeni ve kullanılmayan değişkenleri gösterir.

Gerekirse tek dosya test çalıştırarak hatayı daraltın: pnpm test -- src/users/users.service.spec.ts. Ajan testi geçemediğinde, ona hatayı ve dosya yolunu vererek yalnızca o testi düzeltmesini isteyin; tüm projeyi yeniden düzenlemesine izin vermeyin. Eğer projede e2e test varsa, ajan değişiklik yaptığında pnpm test:e2e komutunu da çalıştırın; özellikle HTTP durum kodlarını ve global pipe’ları doğrular. E2e testler veritabanı gerektiriyorsa test ortamının hazır olduğundan emin olun. Ajan, e2e test yazarken bazen yalnızca basit endpoint çağrısı yapar; siz yan etkileri ve hata durumlarını da kapsamasını isteyebilirsiniz. Test kapsamı düşükse ajan’dan ek testler yazmasını isteyin; ancak her yeni testi mevcut test kalitesiyle karşılaştırın.

Kabul kriteri olarak #(burada bir şey yok) belirlemek faydalıdır: örneğin build hatasız olmalı, tüm unit testler geçmeli, yeni eklenen DTO alanları için doğrulama testleri bulunmalı. Ajan bu kriterleri bilirse ona göre çalışır. Kabul sonrası git diff ile yapılan değişiklikleri satır satır okuyun; özellikle module metadata ve provider listelerindeki değişiklikleri kontrol edin. Küçük bir hata runtime’da DI çözümlenememe olarak patlayabilir.

Birden fazla ajanı AgentVera ile paralel çalıştırma

Birden fazla Claude Code ajanını aynı NestJS projesinde koşmak için AgentVera kullanılabilir. Her ajan ayrı bir git worktree içinde çalıştığı için users ve orders modülleri aynı anda değiştirilirken dosyalar çakışmaz. Tur bitince ikinci bir model ajanın kodunu otomatik inceler; dependency injection hatalarını satır bazında gösterir. Checkpoint’ler sayesinde kötü bir tur tek tıkla geri alınabilir. Token bütçeleri ise ajan başına sınır koyarak uzun migration işlerinde bütçenin aniden tükenmesini önler. Paralel ajan kurulumu için Birden fazla Claude Code ajanını paralel çalıştırma yazısına bakılabilir.

Özet

Claude Code, NestJS’te tekrar eden katmanları hızlandırmak için güçlü bir araçtır; ancak DI, modül metadata ve DTO doğrulaması gibi NestJS’e özgü konuları CLAUDE.md ile netleştirmek gerekir. Küçük adımlarla çalışın, her değişiklikten sonra build ve test alın, diff’i okuyun. Paralel işler için worktree ve otomatik inceleme sunan bir ajan yöneticisi süreci daha güvenli hale getirir.