Claude Code ile Spring Boot Projelerinde Verimli Çalışma

Claude Code, claude komutuyla proje klasöründe başlatılan ve Spring Boot projelerinde kod üretimi, refactoring, test yazımı ve build yönetimi için kullanılabilen bir kodlama ajanıdır. Bu rehber, Spring Boot bilen geliştiricilerin ajanı verimli kullanması için CLAUDE.md yapılandırmasından çalışma döngüsüne, test doğrulamadan paralel ajan kullanımına kadar pratik bilgiler sunar. Amaç, ajanı rastgele komutlarla değil, projeye özel kurallarla ve disiplinli bir süreçle çalıştırmaktır.

Neden Claude Code Spring Boot işlerine uygun?

Claude Code, terminal üzerinde çalıştığı için Maven veya Gradle komutlarını doğrudan çalıştırabilir, derleme çıktısını okuyabilir ve test sonuçlarını analiz edebilir. Spring Boot’un katmanlı mimarisi (controller, service, repository) ve yaygın anotasyonları (@RestController, @Service, @Repository, @Entity) ajanın bağlamı anlamasını kolaylaştırır. CLAUDE.md dosyası sayesinde projeye özel kuralları öğrenir; örneğin constructor injection zorunluluğu, DTO kullanımı veya Flyway migration düzeni. Bu sayede sıfırdan bir endpoint eklerken bile mevcut kod tabanıyla tutarlı kod üretebilir. Ajan ayrıca popüler kütüphaneleri (Spring Data JPA, Spring Security, MapStruct, Lombok, Testcontainers) tanır ve doğru kullanım önerileri sunar. Maven veya Gradle arasında fark etmeksizin projenin build tool’unu algılar; pom.xml veya build.gradle dosyalarını okuyarak bağımlılık yönetiminde yardımcı olur. Hata durumlarında stack trace’leri yorumlayıp düzeltme önerir. Daha fazla bilgi için Claude Code sayfasına bakılabilir.

Projeyi ajan için hazırlama ve CLAUDE.md

Claude Code her oturumda proje kökündeki CLAUDE.md dosyasını okur. Bu dosyaya build, test ve lint komutları, klasör yapısı ve Spring Boot’a özel kurallar yazılmalıdır. Amaç, ajanın her seferinde aynı komutları kullanmasını ve proje konvansiyonlarına uymasını sağlamaktır. Dosya kısa ve öz olmalı, ancak kritik bilgiler eksik olmamalıdır. Proje çok modüllü ise her modülün çalışma dizinleri ve bağımlılıkları belirtilmelidir. Ayrıca yasaklanmış uygulamalar varsa (örneğin field injection kullanılmamalı, Lombok’un belirli anotasyonları kullanılmamalı) açıkça yazılmalıdır. Aşağıda gerçekçi bir örnek verilmiştir:

# CLAUDE.md

## Komutlar
- Build: `./mvnw clean verify`
- Test: `./mvnw test`
- Tek test: `./mvnw test -Dtest=UserServiceTest`
- Lint: `./mvnw checkstyle:check`
- Uygulama çalıştır: `./mvnw spring-boot:run`

## Klasör yapısı
- `src/main/java/com/example/proje` altında: `controller`, `service`, `repository`, `dto`, `entity`, `exception`, `config`
- `src/main/resources`: `application.yml`, `db/migration`
- `src/test/java`: aynı paket yapısı

## Spring Boot kuralları
- Constructor injection kullan, field injection yapma.
- Entity'leri doğrudan controller'da döndürme; DTO kullan ve map'lemeyi `MapStruct` veya manuel yap.
- Repository interface'leri Spring Data JPA ile tanımla; karmaşık sorgular için `@Query` kullan.
- Global exception handling için `@ControllerAdvice` sınıfı oluştur.
- Testlerde `@WebMvcTest`, `@DataJpaTest`, `@SpringBootTest` ve Testcontainers kullan; unit testlerde Mockito tercih et.
- Veritabanı migration'ları Flyway ile yönetilir; yeni migration dosyaları `V{versiyon}__{açıklama}.sql` formatında olmalı.

Bu dosya ne kadar net olursa ajan o kadar az yanlış varsayım yapar. Özellikle çok modüllü Maven projelerinde modül adları ve çalışma dizinleri belirtilmelidir. Ayrıca ortam değişkenleri veya profil bazlı ayarlar da not edilebilir.

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

Claude Code ile verimli çalışmanın anahtarı küçük adımlar atmak ve her adımda testleri çalıştırmaktır. İlk olarak ajanı plan modunda başlatıp yapılacak işi adımlara bölmesini isteyin (bkz. plan modu). Ardından tek bir görevi yaptırın, testleri çalıştırın ve git diff ile değişiklikleri inceleyin. Hata varsa düzeltmesini isteyin, yoksa bir sonraki adıma geçin. Her görevden sonra ajanın ne yaptığını kısaca özetlemesini isteyebilirsiniz; bu, beklenmeyen değişiklikleri yakalamayı kolaylaştırır. Aşağıda tipik Spring Boot görevleri için örnek komutlar listelenmiştir:

• “Yeni bir ProductController ekle: /api/products GET endpoint’i tüm ürünleri sayfalı olarak döndürsün. ProductService ve ProductRepository oluştur, JUnit testlerini yaz.”
• “Mevcut OrderService içindeki createOrder metodunu transaction içine al, stok kontrolü ekle ve OutOfStockException fırlat. Birim testlerini güncelle.”
• “User ve Role entity’leri arasında many-to-many ilişki kur, Flyway migration dosyası oluştur, repository testlerini Testcontainers ile yaz.”
• “Spring Security ile JWT tabanlı authentication ekle, mevcut public endpoint’leri koru, SecurityConfig’i yaz ve ilgili testleri güncelle.”
• “Projeyi ./mvnw clean verify ile derle, hataları düzelt ve tüm testlerin geçtiğini doğrula.”
• “ProductService’teki karmaşık iş mantığını küçük metodlara ayır ve unit test kapsamını artır, jacoco raporunu incele.”

Bu komutlarda ajanın hem kod üretmesini hem de testleri güncellemesini istemek önemlidir; böylece gerileme riski azalır.

İyi olduğu işler ve dikkat edilmesi gerekenler

Claude Code, tekrarlayan Spring Boot işlerinde oldukça başarılıdır: CRUD endpoint’leri oluşturma, entity-DTO dönüşümleri, repository interface’leri yazma, validation ekleme ve mevcut kodu refactor etme. Ayrıca derleme hatalarını bulup düzeltmede ve eksik testleri tamamlamada etkilidir. Ancak Spring Boot’a özgü bazı tuzaklara dikkat edilmelidir. Ajan bazen aşırı mühendislik yapabilir, gereksiz abstraction katmanları ekleyebilir veya mevcut proje kalıplarını göz ardı edebilir. Transaction sınırları, lazy loading (LazyInitializationException), cascade ayarları ve equals/hashCode implementasyonları hatalı olabilir. Ayrıca application.yml içindeki profil bazlı ayarları karıştırabilir veya Testcontainers konfigürasyonunu eksik bırakabilir. Spring Security eklerken mevcut endpoint’lerin güvenliğini yanlış yapılandırabilir veya CORS ayarlarını atlayabilir. Veritabanı migration’larında geriye dönük uyumluluğu göz ardı edebilir. Cache kullanımında @Cacheable anotasyonunu yanlış parametrelerle uygulayabilir. Aşağıdaki tablo, sık karşılaşılan görevlerde nelere dikkat edilmesi gerektiğini özetler:

Bu noktalarda ajanın ürettiği kodu her zaman manuel olarak gözden geçirmek gerekir. Özellikle veritabanı şemasını etkileyen değişikliklerde migration dosyalarını dikkatle inceleyin.

Test ve doğrulama

Spring Boot projelerinde test, ajanın ürettiği kodun kalitesini doğrulamanın en güvenilir yoludur. Her değişiklikten sonra ajanın ./mvnw test veya ./gradlew test komutunu çalıştırmasını isteyin. Entegrasyon testleri için Testcontainers kullanıyorsanız, ajanın Docker’ın çalıştığından emin olması ve doğru imajı kullanması gerekir. Ajan testleri geçse bile, testlerin gerçekten istenen davranışı doğruladığını kontrol edin; bazen ajan sadece assertion ekleyip geçişi sağlayabilir. Manuel doğrulama için uygulamayı ./mvnw spring-boot:run ile başlatıp curl veya HTTP dosyalarıyla endpoint’leri test edebilirsiniz. Ajan ayrıca git diff çıktısını özetleyebilir; bu özeti inceleyerek beklenmeyen değişiklikleri yakalayın. Birim testlerinde @WebMvcTest ve Mockito ile controller’ları izole edin; @DataJpaTest ile repository katmanını gerçek veritabanı yerine H2 veya Testcontainers ile test edin. Entegrasyon testlerinde @SpringBootTest ve TestRestTemplate veya MockMvc kullanın. Ajanın test yazarken doğru anotasyonları seçmesini sağlamak için CLAUDE.md’e test stratejisi eklemek faydalı olur. Ayrıca test kapsamını artırmak için jacoco raporunu incelemesini isteyebilirsiniz; ancak kapsam yüzdesine takılmayın, kritik iş mantığının test edilmesi daha önemlidir.

Birden fazla ajanla çalışmak: AgentVera

Spring Boot projelerinde farklı özellikleri paralel geliştirmek için AgentVera kullanışlıdır. Her ajan kendi git worktree’sinde çalıştığı için dosya çakışması yaşanmaz; bir ajan controller üzerinde çalışırken diğeri servis katmanını değiştirebilir. Otomatik kod incelemesi, Spring’e özgü hataları (eksik transaction veya yanlış bean kapsamı gibi) yakalar ve dosya:satır bağlantısıyla gösterir. Token bütçeleri, uzun build ve test döngülerinde kaynak tüketimini sınırlar. Böylece ekip, birden çok Spring Boot görevini güvenle paralel yürütebilir; ayrıntılar için AgentVera nasıl kullanılır sayfasına bakılabilir.

Sonuç

Claude Code, doğru CLAUDE.md ve disiplinli bir çalışma döngüsüyle Spring Boot geliştirmeyi belirgin şekilde hızlandırır. Küçük adımlar atmak, her adımda test çalıştırmak ve diff incelemek, ajanın üretkenliğini güvenliğe dönüştürür. Daha fazla ipucu için Claude Code en iyi pratikler kontrol listesine göz atın. Paralel çalışma gerektiğinde AgentVera gibi araçlar işleri ölçeklendirir.