Codex ile NestJS projesinde verimli çalışma rehberi

Codex, NestJS projesinde codex komutuyla doğrudan terminalde çalışır; modül, controller, DTO ve provider dosyalarının net sınırları sayesinde değişiklikler denetlenebilir kalır. Projeye özel kuralları AGENTS.md dosyasına yazıp küçük görevlerle test-diff döngüsü kurduğunuzda NestJS işleri ciddi hızlanır. Bu rehberde kurulum, çalışma düzeni ve doğrulamayı TypeORM ile Prisma kullanımına uygun şekilde anlatıyorum.

Codex NestJS işlerinde neden iyi çalışır?

NestJS kuralcı bir yapı sunar; controller, service, module ve DTO ayrımı ajan için tahmin edilebilir dosya sınırları oluşturur. Decorator tabanlı dependency injection, validation pipe ve modül metadata’sı gibi tekrarlı kalıplar Codex’in hızlı ve tutarlı ürettiği bölümlerdir. Örneğin, @Module içinde provider listesini güncellerken import/export dengesini korur; class-validator dekoratörlerini mevcut DTO ile tutarlı üretir. Ayrıca npm run lint, npm run test ve npm run build komutları deterministik olduğundan ajan kendi çıktısını doğrulayabilir; bu döngü NestJS’in katı tip sistemine uygundur. Katmanlar arası bağımlılık net olduğu için ajanın yaptığı hata da hızlı fark edilir: eksik exports, yanlış inject token’ı veya unutulan ValidationPipe genellikle derleme veya test aşamasında yakalanır.

Projeyi ajana hazırlama: AGENTS.md

AGENTS.md dosyası Codex’in her görevde okuduğu proje sözleşmesidir. İçine build, test, lint komutlarını; modül ve dosya sözleşmesini; NestJS’e özgü geçerli kuralları yazın. Kısa ve net bir dosya, uzun sohbet geçmişinden daha güvenilirdir; bu pratiği bağlam mühendisliği olarak da düşünebilirsiniz. Aşağıdaki örnek TypeORM kullanan bir proje içindir; Prisma kullanıyorsanız aynı komutlar geçerlidir, ayrıca prisma.schema dosyasının src dışında olduğunu, PrismaService sağlayıcısının global modülden export edildiğini ve migration komutlarını (npx prisma migrate dev, npx prisma generate) ekleyin.

# AGENTS.md

## Komutlar
- Kurulum: `npm ci`
- Geliştirme: `npm run start:dev`
- Test: `npm run test`
- E2E test: `npm run test:e2e`
- Lint: `npm run lint`
- Build: `npm run build`

## Klasör sözleşmesi
- Her özellik `src/modules/<feature>/` altında modül olarak durur.
- `controller`, `service`, `module`, `dto`, `entity` dosyaları ayrı tutulur.
- Ortak guard, pipe, interceptor `src/common/` altındadır.
- E2E testler `test/` altında, unit testler ilgili dosyanın yanında `*.spec.ts` olur.

## NestJS kuralları
- Tüm gelen istekler `main.ts` içinde `app.useGlobalPipes(new ValidationPipe({ whitelist: true, transform: true }))` ile doğrulanır.
- DTO alanlarında `class-validator` dekoratörleri zorunludur; boş DTO kabul edilmez.
- Servisler yalnızca aynı modülden import edilir; başka modüle lazımsa provider `exports` içine eklenir.
- TypeORM repository işlemleri serviste yapılır; controller doğrudan repository bilmez.
- Değişiklik sonrası `npm run lint`, `npm run test` ve `npm run build` geçmelidir.

Bu dosyayı her değişiklikten önce güncelleyin: yeni bir modül eklendiğinde, yeni bir global pipe devreye girdiğinde veya test komutu değiştiğinde AGENTS.md de güncellensin. Ajan eski kurallarla çalışırsa NestJS’in DI hataları ve yanlış import’ları artar.

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

Görevleri küçük parçalara bölün: önce DTO’yu, sonra servis metodunu, sonra testi yazdırın. Her adımda git diff ile değişiklikleri inceleyin; npm run lint, npm run test ve gerekirse npm run build çalıştırın. Hata çıktısını ajana gösterip düzeltmesini isteyin; plan istemeden büyük refactor yaptırmayın. Ajan bir modülün tamamını tek seferde yazarsa, DI token hataları ve test eksikleri aynı anda ortaya çıkar; küçük adımlar hatayı izole etmeyi kolaylaştırır.

Örnek komutlar:

• UsersModule içinde create-user.dto.ts dosyasını güncelle; email’in formatını @IsEmail ile doğrula, şifre en az 8 karakter olsun; hata mesajlarını Türkçe yaz.
• AuthService içinde JwtService kullanarak login metodunu yaz; JwtModule.registerAsync ile ConfigService’den secret oku; unit testi ekle.
• app.module.ts içinde TypeORM bağlantısını ConfigModule.forRoot({ isGlobal: true }) ile birlikte çevre değişkenlerinden okuyacak şekilde güncelle.
• Jest e2e testinde supertest ile POST /users isteği 201 dönmüyorsa, ValidationPipe eksik mi kontrol et ve düzelt.
• PostsModule içinde PostsService metodlarına NotFoundException ekle; ilgili unit testleri de güncelle.

Her komut sonrası ajanın ürettiği testleri de inceleyin; only veya skip kullanıp kullanmadığına bakın. E2E testlerde gerçek veritabanı yerine test container veya SQLite geçici dosya kullanmasını isteyebilirsiniz.

Codex’in iyi yaptığı ve dikkat edilmesi gereken NestJS işleri

Ajan; modül oluşturma, DTO ve validasyon yazma, standart CRUD servisleri, guard-pipe-interceptor uygulama, TypeORM repository sorguları, Prisma client entegrasyonu ve Jest test taslakları gibi tekrarlı işlerde hızlıdır. Özellikle @Module metadata’sı, provider listesi ve DI token’larını tutarlı üretir. Aynı şekilde class-validator dekoratörlerinin yaygın kullanımlarını ve GlobalPrefix, CORS, helmet gibi bootstrap ayarlarını bilir.

Dikkat edilmesi gerekenler:

• Modül sınırları ve exports unutulması Nest can't resolve dependencies hatasına yol açar; ajanın eklediği her modülü inceleyin.
• Global ValidationPipe main.ts içinde kurulmadıysa DTO doğrulaması sessizce devre dışı kalır; e2e testler 400 yerine 201 dönebilir.
• Decorator tabanlı özelliklerde (@InjectRepository, @Body) tip bilgisi emit edilmediyse derleme hatası oluşabilir; tsconfig ayarlarını değiştirmesine izin vermeyin.
• E2E testlerde app.close() unutulursa Jest açık handle bırakır; test sonunda kapatmayı kontrol edin.
• TypeORM ilişkilerinde @JoinColumn, cascade, lazy seçeneklerini yanlış varsayabilir; repository sorgularını testle doğrulayın.
• DTO’larda @IsOptional ile @IsString birlikte kullanılmalı; ajan bazen yalnızca @IsOptional ekler ve tip doğrulaması zayıflar.
• Prisma’da enum ve relation adlarını schema’dan okumadan tahmin edebilir; schema dosyasını ajana gösterin ve migration üretmesini isteyin.

NestJS’te test ve doğrulama

Ajanın çıktısını yalnızca diff’e bakarak onaylamayın. Sırasıyla npm run lint, npm run test ve npm run build çalıştırın. E2E testlerde veritabanı state’ini temizlemek için beforeEach içinde temizlik yapın veya test veritabanı kullanın. Başarısız test çıktısını Codex’e yapıştırıp düzeltmesini isteyin; ancak ajanın testi zayıflatmadığını diff üzerinden kontrol edin. git diff --stat ile değişen dosya sayısını görün; yalnızca ilgili modülün dosyaları değişmeli.

CI hatasını düzeltme akışını da benzer şekilde kurabilirsiniz; hata logunu ajanla paylaşıp CI hatasını yapay zeka düzeltsin, PR yorumunu da yaklaşımıyla PR üzerinde tartışabilirsiniz. Ajan başarısız bir e2e testi düzeltirken ValidationPipe eklemek yerine test beklentisini gevşetmesin; diff’te expect değişikliklerine dikkat edin.

AgentVera ile paralel ajanlar

AgentVera masaüstü uygulamasında birden fazla Codex oturumu ayrı git worktree’lerde çalışır; böylece biri UsersModule, diğeri OrdersModule üzerinde dosya çakışması yaşamadan ilerler. Tur bitince ikinci model kodu otomatik inceler ve bulgular file:line bağlantısıyla gelir; bu NestJS’te unutulan exports veya eksik pipe gibi hataları yakalamak için pratiktir. Checkpoint’ler sayesinde kötü bir refactor tek tıkla geri alınabilir. Token bütçeleri de uzun e2e denemelerinde bağlamı sınırlı tutar.

Kapanış

Codex, NestJS projesinde sözleşme net olduğunda hızlı ve güvenilir bir yardımcıdır. AGENTS.md, küçük görevler, test ve diff döngüsü disiplinini korursanız modül ekleme, validasyon ve servis işleri ciddi hızlanır. Paralel çalışmaya geçecekseniz AgentVera ile worktree ve otomatik inceleme katmanı eklemek riski azaltır.