Codex ile Spring Boot projesinde verimli çalışma rehberi

Spring Boot projesinde terminalden codex çalıştırdığınızda ajan, bulunduğu klasördeki AGENTS.md dosyasını okuyarak Maven veya Gradle komutlarını, paket yapısını ve test alışkanlıklarınızı izler. Bu rehber; Codex’i Spring Boot’a özel olarak kurmayı, güvenli bir çalışma döngüsü oluşturmayı ve JPA, controller, service ile test işlerini nasıl devredeceğinizi anlatır. Amaç, ajanın rastgele kod üretmesini önleyip mevcut mimariye uygun, test edilebilir parçalar eklemektir.

Codex neden Spring Boot işlerine uygun?

Spring Boot projeleri katmanlı ve kural tabanlıdır. Controller, service, repository ayrımı, DTO kullanımı ve application.yml yapılandırması belirgin olduğu için ajan, kısa bir AGENTS.md ile bu kalıpları uygulayabilir. Kod üretiminden çok derleme ve test çıktılarına tepki veren codex, Maven veya Gradle hatalarını okuyup JUnit sonuçlarına göre düzeltme önerir. Java ve Spring Boot’ta tip hataları derleme aşamasında yakalandığından, terminal döngüsü ajan için güçlü bir geri bildirim kanalı oluşturur. Codex hakkında genel bakış için ilgili sayfaya göz atabilirsiniz.

Spring Boot projesinde AGENTS.md kurulumu

Proje kök dizininde AGENTS.md oluşturun. Ajan bunu her oturumda okur; bu nedenle gerçek komutları ve proje kurallarını kısa tutun. Spring Boot için aşağıdaki gibi bir dosya çoğu durumda yeterlidir:

# AGENTS.md

## Proje komutları
- Build: `./mvnw -q -DskipTests package`
- Test: `./mvnw test`
- Tek test: `./mvnw -Dtest=UserServiceTest test`
- Çalıştır: `./mvnw spring-boot:run`
- Stil: `./mvnw spotless:check` (varsa)

## Klasör düzeni
- `src/main/java/com/acme/order/controller`: REST controller'lar; yalnızca HTTP ve dönüşüm
- `.../service`: iş mantığı ve transaction sınırı
- `.../repository`: Spring Data JPA repository'leri
- `.../dto`: API'ye giren ve çıkan kayıtlar
- `src/test/java`: JUnit 5, AssertJ, Testcontainers

## Spring Boot kuralları
- Constructor injection kullan, field injection yapma.
- Controller asla entity döndürme; DTO kullan.
- Service metotları `@Transactional` olmalı; controller'da transaction açma.
- JPA `@OneToMany` ilişkilerinde `fetch = LAZY` bırak; N+1 riskini fetch join ile çöz.
- `@Entity` sınıflarında Lombok kullanma; getter/setter açık yaz.
- `application.yml` dışında sihirli profil oluşturma; test profilleri için `application-test.yml` kullan.

Klasör yollarını kendi paket adınıza göre güncelleyin. Gradle kullanıyorsanız ./mvnw yerine ./gradlew yazın. AGENTS.md dosyasını her yeni modül veya profil eklediğinizde güncel tutun; uzun ve alakasız kurallar ajanın dikkatini dağıtır. Daha geniş bağlam yönetimi için bağlam mühendisliği rehberine bakabilirsiniz.

Güvenli çalışma döngüsü ve örnek komutlar

Kod yazdırmadan önce plan isteyin; ardından küçük adımlarla ilerleyin. Her adımdan sonra testleri çalıştırın ve git diff çıktısını inceleyin. Spring Boot’ta işe yarayan örnek komutlar:

• “Mevcut UserController’ı incele; GET /users/{id} endpoint’ine 404 için ProblemDetail döndüren hata yönetimi ekle. Önce plan çıkar, kod değiştirme.”
• “UserService.getUser içinde UserNotFoundException fırlat; UserController’da @ExceptionHandler ekle. Sadece bu iki dosyayı değiştir.”
• “Şimdi ./mvnw -Dtest=UserControllerTest,UserServiceTest test çalıştır; hata varsa düzelt ve çıktıyı özetle.”
• “Yapılan değişiklikleri özetle, git diff çıktısını göster; güvenlik ve transaction açısından risk var mı?”
• “JPA repository’de yeni bir sorgu ekle; service katmanını güncelle. Testcontainers ile entegrasyon testi yaz.”

Bu döngü, ajanın uzun dosyalar üretmesini önler ve her değişikliğin derleme ile testten geçmesini sağlar. İlk adımda büyük bir refactor istemek yerine tek bir endpoint veya servis üzerinde çalışın; sonuçları görüp kapsamı genişletin.

Codex’in iyi yaptığı Spring Boot işleri ve riskli noktalar

Aşağıdaki tablo, sık kullanılan görevler için iyi komutları ve dikkat edilmesi gereken noktaları özetler:

Codex en çok, mevcut kalıpları izleyerek CRUD, DTO dönüşümü, exception handler ve temel JUnit testleri üretmede başarılıdır. Buna karşın şu noktalarda ajanı yakından izleyin:

• JPA lazy loading hatasını çözmek için ilişkiyi EAGER yapabilir; bu N+1 ve bellek sorunları doğurur. fetch join veya DTO projeksiyonu isteyin.
• Çift yönlü ilişkilerde equals/hashCode veya Lombok @Data kullanmak yanlış olabilir; ajan bazen entity’ye Lombok ekler.
• Döngüsel bağımlılık oluşursa @Lazy ekleyebilir; bunun yerine arayüz veya mimari düzeltme isteyin.
• Testcontainers testlerinde Docker bağlantısını kontrol etmeden imaj başlatmayı deneyebilir; hata mesajını okuyup düzeltmesini isteyin.
• Ortam değişkenleri yerine application.yml içine sabit credential yazabilir; bu değişikliği reddedin.
• Maven veya Gradle sürüm farklarını göz ardı edebilir; Java sürümünü ve build aracını AGENTS.md içinde belirtin.

Spring Boot’ta test ve doğrulama

Ajanın ürettiği kodu kabul etmeden önce her zaman testleri çalıştırın. ./mvnw test tüm testleri koşar; tek test için -Dtest=... kullanmasını isteyin. Spring Boot’ta tam bağlam ayağa kaldıran testler yavaşlar; @WebMvcTest, @DataJpaTest gibi dilim testlerini tercih etmesini söyleyin. Testcontainers kullanıyorsanız Docker’ın açık olduğundan emin olun ve ajanın @ServiceConnection veya @DynamicPropertySource kullanıp kullanmadığını kontrol edin. Derleme kontrolü için ./mvnw -q -DskipTests package yeterlidir; bunu testlerden önce çalıştırıp paketleme hatalarını ayıklayın. CI’da oluşan başarısız testleri Codex’e okutmak için CI hatasını yapay zeka düzeltsin yazısındaki yaklaşımı uygulayabilirsiniz.

Spring Boot projesinde çoklu ajan: AgentVera

Birden fazla Spring Boot görevini paralel yürütmek istediğinizde AgentVera, her ajanı kendi gerçek terminal panelinde çalıştırır ve ajanların ayrı git worktree kullanmasını sağlar. Bu sayede biri User modülünde, diğeri Order modülünde çalışırken dosyalar üst üste binmez; Spring Boot katmanları izole kalır. Ajanın turu bittiğinde ikinci model otomatik kod incelemesi yapar ve JPA transaction, lazy loading veya eksik test gibi bulguları file:line ile gösterir. Belirlediğiniz token bütçesi, ajanın koca bir Spring Boot refactoründe kontrolsüz harcama yapmasını önler. AgentVera nasıl kullanılır sayfasında kurulumu görebilirsiniz.

Özet

Spring Boot ile Codex kullanırken başarının anahtarı AGENTS.md dosyasını gerçek ve kısa tutmak, küçük adımlarla ilerlemek, her adımda test çalıştırmak ve JPA ile transaction konularında diff’i dikkatle incelemektir. Ajanı serbest bırakmak yerine net sınırlar koyduğunuzda controller-service-repository düzeninde tutarlı, test edilebilir kod üretir. Çok sayıda paralel değişiklik gerekiyorsa AgentVera ile git worktree ve otomatik inceleme, Spring Boot projesinde güvenli bir ölçeklenme sağlar.