opencode ile NestJS geliştirme: pratik rehber

opencode ile NestJS projelerinde modül ekleme, controller yazma, class-validator DTO’ları oluşturma ve Jest testlerini genişletme gibi işler hızlanır. Proje klasöründe opencode komutu çalıştırıldığında ajan, AGENTS.md dosyasındaki talimatları okur ve NestJS konvansiyonlarına göre hareket eder. Bu rehber, deneyimli NestJS geliştiricileri için ajanı verimli kullanma pratiklerini anlatır; daha genel kurulum için opencode sayfasına bakabilirsiniz. Ajan, terminal içinde çalıştığı için NestJS CLI komutlarını doğrudan çalıştırabilir; böylece manuel dosya oluşturma yerine komut satırı üzerinden hızlı bir geri bildirim döngüsü kurarsınız.

Neden opencode NestJS tarafında iyi çalışır

NestJS projeleri katı bir yapı sunar: modüller, controller’lar, provider’lar ve DTO’lar belirli klasörlerde durur. opencode terminal içinde çalıştığı için npm run test, npm run build gibi komutları doğrudan çalıştırabilir, hata çıktılarını okuyup kodu düzeltebilir. Model sağlayıcısı ne olursa olsun aynı döngüyü kullanır: dosyaları okur, değişiklik yapar, testleri koşar. Bu, NestJS’in DI ve modül sınırları gibi alanlarda hata yakalamayı kolaylaştırır. Ajan, mevcut bir UsersModule kalıbını alıp OrdersModule için benzer yapıyı üretebilir; class-validator dekoratörlerini tutarlı biçimde uygular. Örneğin CreateUserDto içinde @IsEmail(), @MinLength(8) gibi dekoratörlerin aynı düzende yeni DTO’lara eklenmesini isteyebilirsiniz. Prisma kullanan projelerde schema.prisma değişiklikleri sonrası prisma generate çalıştırması gerekir; ajan bunu hatırlayabilir ancak migration komutunu sizin onayınız olmadan çalıştırmamalıdır. Ayrıca NestJS’in modüler yapısı, ajanın bir bölümü değiştirirken diğer bölümleri etkileme riskini azaltır; çünkü her özellik kendi modülünde izole kalır. Bu da opencode’un çıktısının daha öngörülebilir olmasını sağlar.

Projeyi ajan için hazırlamak

opencode proje kökündeki AGENTS.md dosyasını okur. Bu dosya kısa ve net olmalı; NestJS’e özgü kurallar, komutlar ve klasör düzeni içermeli. Aşağıdaki örnek, TypeORM kullanan bir NestJS projesi için yeterlidir. Kurulumla ilgili genel adımlar için opencode nasıl kullanılır? Adım adım rehber sayfasına bakılabilir.

# NestJS proje kuralları

## Komutlar
- Build: `npm run build`
- Test: `npm run test` (Jest)
- Lint: `npm run lint`
- Dev: `npm run start:dev`

## Klasör düzeni
- `src/modules/<feature>/`: modül, controller, servis
- `src/modules/<feature>/dto/`: class-validator DTO'ları
- `src/common/`: paylaşılan guard, pipe, interceptor
- `test/`: e2e testleri

## NestJS kuralları
- Yeni özellik daima ayrı modülde olmalı; başka modüle doğrudan servis import etme, gerekirse modül export kullan.
- DTO'larda class-validator dekoratörleri zorunludur; çıplak interface kullanma.
- Controller sadece HTTP katmanı; iş mantığı provider'da.
- TypeORM entity değişikliğinde migration üretmeden önce dur ve kullanıcıya sor.
- Testlerde her modül kendi spec dosyasına sahip olmalı; Jest --runInBand kullanılabilir.

Bu dosyayı sürüm kontrolüne ekleyin; ajan her oturumda onu okuyacaktır. Kuralları muğlak bırakmayın: örneğin DTO'larda class-validator şart gibi kısa ve denetlenebilir cümleler kullanın. Komutlar bölümü sayesinde ajan, projede hangi paket yöneticisinin kullanıldığını (npm, yarn veya pnpm) anlar; böylece yanlış komutla build veya test çalıştırmaz. Klasör düzeni, ajanın yeni dosyaları doğru yere koymasını sağlar; aksi halde src/users gibi düz klasörler oluşturabilir. TypeORM yerine Prisma kullanıyorsanız aynı dosyada prisma migrate ve prisma generate komutlarını ayrıca belirtin; ajan entity modeli ile migration arasındaki farkı net görür. Ayrıca e2e testleri için test veritabanı bağlantısını açıklayan bir satır eklemek, ajanın yanlışlıkla geliştirme veritabanına bağlanmasını önler. Unutmayın: AGENTS.md ne kadar net olursa, ajanın çıktısı o kadar tutarlı olur.

Çalışma döngüsü

opencode ile verimli çalışma, planı ajanla paylaşmak, küçük adımlar istemek, her adımda testleri koşturmak ve git diff çıktısını incelemekten geçer. Önce yapılacak işi bir cümleyle tanımlayın; örneğin “UsersModule’e yeni bir update-profile endpoint’i ekleyeceğiz”. Ardından ajanın bu işi hangi dosyalarda yapacağını netleştirin; böylece gereksiz dosyalara dokunmaz. Her adımdan sonra testleri çalıştırmasını isteyin; ajan test hatası alırsa kendisi düzeltmeye çalışacaktır. Son olarak git diff ile değişiklikleri gözden geçirin. Ajan tek seferde büyük bir refactor yaparsa NestJS modül sınırları kolayca bozulabilir; bu yüzden aşağıdaki gibi net promptlar kullanın.

• src/modules/users/dto altında create-user.dto.ts oluştur; email, password, role alanlarına uygun class-validator dekoratörlerini ekle.
• UsersModule içinde UsersController oluştur; POST /users rotası DTO’yu ValidationPipe ile doğrulasın ve UsersService.create metodunu çağırsın.
• Mevcut UsersService unit testini genişlet; email zaten kayıtlıysa ConflictException fırlattığını doğrula.
• TypeORM User entity’sine isActive: boolean alanı ekle; migration üretmeden önce bana komutu göster.
• npm run lint ve npm run test çalıştır, çıkan hataları düzelt; sonra değişiklikleri kısaca özetle.

Bu promptlar küçük, doğrulanabilir adımlardır. Örneğin ilk prompt sadece DTO oluşturur; ikincisi controller’ı ekler. Böylece hata oluşursa geri almak kolaydır. Ajan aynı oturumda birbiri ardına bu adımları işleyebilir; siz de her adımda durdurup kontrol edebilirsiniz. git diff incelemesi sırasında ajanın gerekmediği halde any kullanıp kullanmadığını veya başka modülden doğrudan servis import edip etmediğini kontrol edin. Ayrıca değişikliklerin AGENTS.md kurallarına uygunluğunu hızlıca gözden geçirin; uygunsuzsa bir sonraki promptta düzeltmesini isteyin.

NestJS görevlerinde güçlü yönler ve riskli noktalar

opencode özellikle tekrarlı ve kural tabanlı işlerde iyidir; ancak NestJS’in DI ve modül grafiği konusunda dikkatli olunması gerekir. Aşağıdaki tablo sık kullanılan görevler için iyi bir prompt ile izlenmesi gereken riski gösterir.

Bu tür görevlerde ajan genellikle hızlı ve doğru sonuç verir. Ancak modüller arası import, dairesel bağımlılık ve migration gibi konular denetim gerektirir. Özellikle @InjectRepository veya Prisma servis enjeksiyonunda token isimlerinin doğru olduğundan emin olun; ajan bazen generic tipi atlayabilir. Ayrıca global ValidationPipe ayarları değiştirildiğinde mevcut endpoint’lerin hata mesajı formatı bozulabilir; bu yüzden her DTO değişikliğinde e2e testlerini de gözden geçirin. Dairesel bağımlılık riski taşıyan modüllerde forwardRef kullanımı ajan tarafından önerilebilir; ancak bunu yalnızca gerçekten gerekliyse kabul edin. Ajanın ürettiği kodu her zaman NestJS best practice’lerine göre değerlendirin; örneğin controller içinde iş mantığı varsa bunu servise taşımasını isteyin.

Test ve doğrulama

NestJS’te ajanla çalışırken testleri her değişiklikten sonra koşturmak esastır. Birim testleri için npm run test -- --runInBand veya doğrudan jest kullanın; e2e testleri genellikle ayrı bir veritabanı gerektirir. opencode’a şu talimatı verin: Sadece unit testleri çalıştır, e2e testlerini başlatma; test ortamı değişkenlerini değiştirme. Ajan, DTO doğrulama hatalarını test ederken ValidationPipe kullanımını da denetleyebilir. Repository mock’ları oluştururken createMock veya elle yazılan sahte nesneler kullanabilir; ancak mock’un gerçek repository davranışını taklit ettiğinden emin olun. Test kapsamını artırmak istiyorsanız npm run test:cov komutunu önerin; ajan, eksik kapsanan dosyaları listeleyip uygun spec dosyalarını doldurabilir. Hata düzeltmelerinde ajanın yalnızca ilgili satırı değiştirdiğinden emin olun; bazen geniş test refactor’larına girişebilir. Ayrıca e2e testleri için ajan bir test/app.e2e-spec.ts dosyasına ihtiyaç duyabilir; bu dosyada test veritabanı bağlantısı ve app.init() ayarlarını kontrol edin. Ajan, supertest kullanarak HTTP isteklerini simüle edebilir; ancak doğru durum kodlarını ve yanıt formatını test ettiğinden emin olun. Son olarak, ajanın testleri geçirmek için üretim kodunu zayıflatmadığını (örneğin any kullanarak) kontrol etmek için git diff üzerinde göz gezdirin.

Birden fazla ajan ile NestJS projesinde çalışmak

AgentVera, opencode dahil birçok CLI ajanını aynı pencerede gerçek terminallerde yan yana çalıştırır. NestJS projelerinde paralel ajanlar, her biri kendi git worktree’sinde çalıştığında modüller arası çakışma yaşamaz; örneğin biri UsersModule, diğeri OrdersModule üzerinde eşzamanlı ilerleyebilir. Otomatik kod incelemesi, eksik class-validator dekoratörü veya bozuk DI bağlamalarını yakalar. Checkpoint’ler, başarısız bir refactor sonrası önceki çalışan duruma dönmeyi sağlar. Token bütçeleri ise uzun süren NestJS görevlerinde maliyeti kontrol altında tutar.

Sonuç

opencode, NestJS projelerinde yapılandırılmış ve tekrarlı işleri hızlandıran pratik bir araçtır. AGENTS.md’ye net kurallar koymak, küçük adımlarla ilerlemek ve her değişiklikte testleri koşmak, ajanın modül sınırlarını korumasını sağlar. Paralel çalışma gerektiğinde git worktree ve otomatik inceleme gibi mekanizmalar riskleri azaltır. Deneyimli bir NestJS geliştiricisi, bu döngüyü oturttuğunda opencode’u günlük geliştirme rutinine sorunsuz entegre edebilir. Ajanın ürettiği kodun kalitesini her zaman kendi NestJS birikiminizle değerlendirin; opencode hız kazandırır ama mimari kararları siz verirsiniz.