Cursor Agent ile Spring Boot Projelerinde Verimli Kodlama

Cursor Agent, Spring Boot projesinde terminalden cursor-agent komutuyla başlatılan bir kodlama ajanıdır; proje klasöründeki kodu okur, değişiklik önerir ve test komutlarını çalıştırabilir. Spring Boot’un net controller-service-repository ayrımı ve güçlü test altyapısı, ajana küçük, doğrulanabilir adımlarla iş yaptırmak için uygundur. Bu rehberde Cursor Agent ile bir Spring Boot projesini nasıl hazırlayacağınızı, hangi görevleri güvenle vereceğinizi ve sonuçları nasıl doğrulayacağınızı anlatıyorum.

Cursor Agent Spring Boot projelerinde neden işe yarar

Spring Boot’un öngörülebilir iskeleti, Cursor Agent’ın bağlamı daha az kaybetmesini sağlar. Controller, service ve repository katmanları arasındaki geçişler standart olduğu için ajan tekrarlayan kodu tutarlı biçimde üretir. Maven veya Gradle wrapper komutları üzerinden test çalıştırabilmesi, her değişiklikten sonra hızlı geri bildirim almayı mümkün kılar. Spring Data JPA derived query’leri, DTO mapping ve doğrulama anotasyonları gibi sık kullanılan parçalar da ajana iyi oturur. Buna karşın transaction sınırları, lazy loading ve profil bazlı konfigürasyon gibi bağlama duyarlı konularda ajanın önerileri her zaman projeye uygun olmaz; bu yüzden kuralları önceden yazmak önemlidir. Ayrıca Spring Boot’un otomatik konfigürasyonu sayesinde ajan, bean tanımlarını ve property bağlamalarını kolayca üretebilir; ancak bu otomasyon bazen beklenmedik bağımlılık çatışmalarına yol açabilir. Bu yüzden ajanın her değişikliğini mutlaka testlerle doğrulamak gerekir.

Projeyi ajan için hazırlama: AGENTS.md ve .cursor/rules

Projeyi ajan için hazırlarken AGENTS.md dosyasını proje köküne koyun; .cursor/rules altında da ek kural dosyaları tutabilirsiniz. Bu dosyada komutlar, klasör sözleşmeleri ve Spring Boot’a özgü kurallar açıkça yazılmalı. Kısa ve deterministik tutun; uzun talimatlarda ajan önemli satırları atlayabilir. Maven projesi için aşağıdaki örnek yeterli bir başlangıçtır; Gradle kullanıyorsanız komutları ./gradlew ile değiştirin. Temel terminal kullanımı için Cursor CLI nasıl kullanılır? Adım adım rehber yazısına da göz atabilirsiniz; burada Spring Boot odaklı kurallara devam ediyorum.

# AGENTS.md

## Komutlar
- Test: ./mvnw test
- Tek test sınıfı: ./mvnw -Dtest=UserServiceTest test
- Derleme ve doğrulama: ./mvnw clean verify
- Çalıştırma: ./mvnw spring-boot:run -Dspring-boot.run.profiles=local

## Katman kuralları
- Controller yalnızca DTO alır ve DTO döner; entity sızdırma.
- Service katmanı iş mantığını ve transaction sınırlarını yönetir.
- Repository arayüzleri Spring Data JPA ile yazılır; türetilmiş sorgu veya @Query kullan.
- Constructor injection zorunlu; field injection (@Autowired) kullanma.
- Entity'lerde equals/hashCode için yalnızca immutable unique key kullan.
- JSON döngüsünü önlemek için bidirectional ilişkilerde @JsonIgnore veya DTO mapping uygula.

## Testler
- JUnit 5, Mockito ve AssertJ kullan.
- Entegrasyon testleri Testcontainers ile gerçek veritabanında çalışır.
- Her service ve controller için en az bir mutlu yol ve bir hata senaryosu yaz.

Bu kurallar sayesinde ajan entity’leri controller’a sızdırmaz, field injection üretmez ve testlerde gerçek veritabanı kullanılması gerektiğini bilir. AGENTS.md dosyasına ek olarak .cursor/rules altında spring-boot.md gibi ayrı dosyalar oluşturup bu kuralları modüler tutabilirsiniz. Örneğin, validation anotasyonlarını (jakarta.validation) her DTO’da kullanmasını, @RestControllerAdvice ile global exception handler yazmasını ve hata yanıtlarını standart bir ErrorResponse yapısına sarmasını şart koşun. Eğer projede Lombok kullanıyorsanız, @Data yerine @Getter @Setter kombinasyonunu tercih etmesini belirtin; çünkü @Data entity ilişkilerinde equals/hashCode ve toString sorunlarına yol açabilir. MapStruct veya manuel mapping kullanıyorsanız, ajanın DTO-entity dönüşümlerinde hangi yöntemi izleyeceğini açıkça yazın. Ayrıca paket yapısını netleştirin: controller, service, repository, entity, dto, exception, config gibi. Bu detaylar, ajanın projeye özgü kod yerine genel şablonlar üretmesini engeller.

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

Çalışma döngüsü şöyle olmalı: görevi planla, küçük adımlara böl, ajanın ürettiği değişikliği çalıştır, testleri koş ve git diff ile farkı incele. Cursor Agent’a “tüm modülü yaz” demek yerine tek bir controller, service veya repository görevi verin. Ajan her adımda dosyaları düzenler; siz de değişikliği onaylamadan önce testleri çalıştırın. Örneğin bir kullanıcı kayıt özelliği için önce repository’ye findByEmail metodunu ekletin, sonra service’te duplicate kontrolü yaptırın, ardından controller’da 409 dönüşünü ve DTO mapping’i yazdırın. Her adımda ilgili testi çalıştırıp sonraki adıma geçin. Aşağıdaki örnek görevler Spring Boot işlerinde sık kullanılır ve tek başına birer iş paketi olarak verilebilir:

• “UserService içinde createUser metodunu yaz: UserRequest DTO’sunu al, email benzersizliğini kontrol et, User entity’sine map et, repository’ye kaydet, duplicate email durumunda 409 döndür.”
• “OrderController’a GET /orders/{id} endpoint’ini ekle; service katmanına delege et, bulunamazsa 404 fırlat, response olarak OrderResponse DTO döndür.”
• “ProductRepository’ye isim ile arama için derived query ekle ve ProductService’te bu metodu çağıran sayfalama destekli bir metod yaz.”
• “UserServiceTest için JUnit 5 testleri yaz: Mockito ile repository’yi mockla, başarılı kayıt ve duplicate email durumlarını doğrula.”
• “OrderRepository için Testcontainers tabanlı entegrasyon testi yaz: PostgreSQL container başlat, save ve find işlemlerini AssertJ ile doğrula.”
• “CustomerController’da POST /customers endpoint’ine jakarta.validation anotasyonları ekle ve geçersiz veride 400 dönecek şekilde @Valid kullan; hata mesajlarını standart ErrorResponse içine al.”
• “ProductService’te listProducts metoduna Redis cache ekle; @Cacheable ve @CacheEvict anotasyonlarını doğru yerlere koy ve cache konfigürasyonunu CacheManager ile tanımla.”
• “OrderController için MockMvc tabanlı bir web katmanı testi yaz; service’i mockla, JSON istek gönder ve response body ile status kodunu doğrula.”

Bu görevlerin her biri, ajanın Spring Boot kalıplarını doğru uygulamasını sağlar ve sizin de diff’i küçük parçalar halinde incelemenize olanak tanır.

İyi gittiği işler ve dikkat edilmesi gerekenler

Spring Boot projelerinde Cursor Agent bazı alanlarda çok iyi çalışır; bazı alanlarda ise ürettiği kodu dikkatle incelemeniz gerekir. Aşağıdaki tablo bu ayrımı özetler:

Controller ve DTO katmanlarında ajan hızlıdır; ancak entity’yi doğrudan JSON olarak döndürme alışkanlığı olabilir. Bu yüzden AGENTS.md’ye DTO kuralını ekleyin. Spring Data JPA tarafında basit türetilmiş sorgular iyi çalışır; findByEmail veya findByStatusAndCreatedAtAfter gibi. Ancak çoklu ilişki içeren sorgularda N+1 sorunu yaratabilir; @EntityGraph veya fetch join gerekip gerekmediğini kontrol edin. Transaction sınırları da kritik: ajan @Transactional(readOnly = true) eklemeyi unutabilir veya yanlış katmana koyabilir. Ayrıca @Modifying sorgularında clearAutomatically ve flushAutomatically gibi detayları atlayabilir. Güvenlik konfigürasyonlarında ise genel çözümler üretebilir; mevcut SecurityFilterChain yapınızı ajanın koduna mutlaka eşleştirin.

Ek olarak dikkat edilmesi gerekenler: ajan, bean tanımlarında döngüsel bağımlılık oluşturabilir; örneğin iki service birbirini constructor injection ile alırsa uygulama başlamaz. Property binding hataları da yaygındır; @ConfigurationProperties sınıflarında alan adlarını yanlış eşleyebilir. Profil bazlı konfigürasyonlarda application-dev.yml gibi dosyaları yanlış birleştirebilir; özellikle @ActiveProfiles testlerde atlanabilir. Asenkron metodlarda @Async ekleyip thread pool yapılandırmasını unutabilir. Cache kullanımında @Cacheable ekleyip cache isimlerini yanlış yazabilir veya invalidation’ı atlayabilir. Tüm bu durumlarda, ajanın ürettiği kodu çalıştırmadan önce ilgili testleri ve uygulama başlangıcını mutlaka doğrulayın.

Spring Boot’ta test ve doğrulama

Spring Boot’ta doğrulama ajansız da kritik; ajanla birlikte testleri her adımda çalıştırın. Bir görev tamamlandığında önce ./mvnw test veya ./gradlew test komutunu çalıştırın; ajanın yazdığı testlerin de gerçekten çalıştığından emin olun. Testcontainers kullanıyorsanız Docker daemon’unun erişilebilir olduğunu kontrol edin; ajan bazen container başlatma komutlarını atlayabilir. @SpringBootTest ile tüm context ayağa kalkıyorsa test süresi uzar; yalnızca gerekli dilimi @DataJpaTest veya @WebMvcTest ile izole edin. Ajanın ürettiği testleri inceleyip assertion’ları iş kuralına göre güncelleyin; sadece null kontrolü yapan testler yeterli değildir. Özellikle entegrasyon testlerinde veritabanı şemasını Flyway veya Liquibase ile yönetiyorsanız, ajanın migration dosyalarını değiştirmesine izin vermeyin; önce mevcut migration geçmişini koruyun.

Test çalıştırırken profil belirtmek için ./mvnw test -Dspring.profiles.active=test komutunu kullanın; ajanın test sınıflarında @ActiveProfiles("test") eklemesini isteyebilirsiniz. Entegrasyon testlerini ayrı tutmak için Maven Failsafe plugin’i ./mvnw verify ile çalıştırın; ajanın *IT sonekli testleri oluşturmasını sağlayın. Testcontainers’ta @Testcontainers ve @Container anotasyonlarını kullanmasını, DynamicPropertySource ile veritabanı bağlantısını ayarlamasını isteyin. Hızlı geri bildirim için tek test sınıfını çalıştırmak üzere ./mvnw -Dtest=UserControllerTest test komutunu kullanın. Ajan, testleri yazdıktan sonra bu komutları kendisi de çalıştırabilir; ancak çıktıyı siz de inceleyin.

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

Spring Boot projesinde birden fazla işi paralel yürütmek isterseniz AgentVera farklı ajanların gerçek komut satırı araçlarını yan yana çalıştırır; bu yaklaşım Paralel kodlama ajanları için en iyi araçlar (2026) yazısında da ele alınıyor. Her ajan kendi git worktree’sinde ilerleyebildiği için aynı controller veya application.yml dosyasını ezme riski ortadan kalkar. Ajan turu bitince ikinci bir model kodu otomatik inceler ve bulguları file:line olarak gösterir; bu, Spring Boot’taki transaction ve mapping hatalarını erken yakalar. Ayrıca her turun anlık görüntüsü alındığından yanlış bir migration veya config değişikliğini tek tıkla geri alabilirsiniz.

Sonuç

Cursor Agent, Spring Boot projelerinde tekrarlayan katman kodunu hızlandırır; asıl değer, projeye özgü kuralları AGENTS.md ile netleştirdiğinizde ortaya çıkar. Her değişiklikten sonra testleri çalıştırıp diff’i incelemek, transaction ve mapping hatalarını erkenden yakalar. Ajanı bir yardımcı pilot gibi kullanın; son kararı ve mimari tutarlılığı siz verin. Küçük adımlarla ilerleyip her adımı doğruladığınızda, Cursor Agent Spring Boot geliştirme sürecinin güvenilir bir parçası haline gelir.