# opencode ile Spring Boot projeleri: pratik kullanım rehberi

Adres: https://agentvera.dev/blog/opencode-ile-spring-boot/ · Yayın: 2026-11-01

opencode ile Spring Boot projelerinde pratik çalışma: AGENTS.md kurulumu, çalışma döngüsü, örnek görevler, test doğrulama ve dikkat edilecek tuzaklar.

**Kısaca:**

- opencode, AGENTS.md ile komutları ve kuralları öğrenir; Spring Boot’ta katmanlı değişiklikleri hızlandırır.
- Doğru döngü: küçük görev, plan, test, diff incelemesi; migration ve transaction değişikliklerinde denetim şart.
- Testcontainers ve Maven/Gradle testlerini çalıştırır; Docker ve ddl-auto gibi Spring Boot tuzaklarına dikkat edin.

`opencode` ile bir Spring Boot projesinde çalışmak, terminalde proje klasöründe [`opencode`](/ajanlar/opencode/) komutunu çalıştırmakla başlar. Ajan, AGENTS.md dosyanızdaki talimatları okur ve Maven veya Gradle komutlarını, test çalıştırmayı ve kod düzenini bu bağlama göre yürütür. Bu rehber, Spring Boot bilen geliştiriciler için ajandan en verimli şekilde yararlanmanın pratik yollarını anlatır.

## Neden opencode Spring Boot için uygun

opencode, Spring Boot işleri için iki nedenle iyi çalışır: çok dosyalı değişiklikleri planlayabilir ve test/döngü komutlarını gerçekten çalıştırabilir. Controller’dan service’e, repository’den DTO’ya uzanan bir değişiklikte dosya dosya geçiş yapmak yerine ajan, ilgili sınıfları birlikte okur ve tutarlı bir yama üretir. Maven/Gradle çıktısını anlar; başarısız bir testi stack trace ile birleştirip hatayı düzeltebilir. Ayrıca Spring’in yaygın kalıplarını tanır: `@Transactional` sınırları, `@Entity` ilişkileri, `@ControllerAdvice`, `@ConfigurationProperties`, bean yaşam döngüsü ve test slice’ları. Bu, onu yalnızca kod üreten bir araçtan çok, Spring Boot bağlamını bilen bir çift programcı gibi kullanmanıza olanak tanır.

## Projeyi ajan için hazırlama

opencode’un en büyük avantajı, proje kökündeki `AGENTS.md` dosyasını okumasıdır. Bu dosyaya Spring Boot projesinin komutlarını, paket yapısını ve sizin takım kurallarınızı yazın; ajan her görevde bunlara uyar. Aşağıdaki örnek, Maven kullanan tipik bir sipariş servisi için kısa ve gerçekçi bir `AGENTS.md` içeriğidir. [`opencode` kullanımının genel adımları](/blog/opencode-nasil-kullanilir/) için ayrıca rehbere bakabilirsiniz.

```
# AGENTS.md
## Komutlar
- build: ./mvnw -q -DskipTests package
- test: ./mvnw test
- tek test: ./mvnw -Dtest=OrderServiceTest test
- lint: ./mvnw checkstyle:check

## Paket yapısı
com.example.order
├── controller   # HTTP katmanı, yalnızca DTO alır/döner
├── service      # iş mantığı ve transaction sınırı
├── repository   # Spring Data JPA arayüzleri
├── domain       # JPA entity'leri
├── dto          # request/response kayıtları
└── exception    # @ControllerAdvice ile yakalanan hatalar

## Kurallar
- Controller'da entity döndürme; DTO'ya map et.
- Service metotları gerekliyse @Transactional kullan; salt okuma sorguları readOnly=true.
- Repository testleri Testcontainers ile gerçek PostgreSQL kullanır.
- Lombok kullanma; getter/setter veya Java record yaz.
- Bean validation anotasyonlarını DTO'da kullan.
```

Bu dosya, ajanın her yeni görevde 'Acaba bu projede nasıl test koşuluyor?' diye sormasını engeller. Maven yerine Gradle kullanıyorsanız komutları `./gradlew test` gibi yazın. `lint` komutunu atlamayın; ajanın ürettiği kodda format sorunlarını kendiliğinden düzeltebilmesi için `./mvnw spotless:apply` gibi bir komut da ekleyebilirsiniz.

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

Denenmiş döngü şudur: kısa bir görev verin, ajanın planını okuyun, küçük değişiklik yapmasını isteyin, testleri çalıştırın, diff’i inceleyin. Tek seferde büyük refactor istemeyin. Her adımdan sonra `git diff` çıktısını gözden geçirin. Ajanın söylediği her şeyi doğrulayın; özellikle migration ve transaction değişikliklerinde testleri atlamasına izin vermeyin.

Spring Boot projelerinde işe yarayan örnek komutlar:

- Order entity’sine ORDERED, PAID, CANCELLED değerlerini ekle; enum oluştur, entity’ye alan ekle, gerekli migration’ı hazırla ve repository sorgularını güncelle.
- OrderController’daki createOrder metodunu incele; eksik validasyon, hata mesajları ve HTTP durum kodlarını düzelt.
- ProductService’te stok düşürme işlemini iyimser kilitle (optimistic lock) ile güvenli hale getir; test yaz.
- OrderRepository için Testcontainers kullanarak bir repository testi yaz; PostgreSQL container ayağa kalksın.
- Şu test hatasını çöz: [stack trace yapıştır]. Önce hatanın nedenini açıkla, sonra düzelt.

Bu komutları tek tek verin; ajan her seferinde önce mevcut kodu okusun, sonra değişiklik yapsın. Uzun bir görev verirseniz, aradaki bağlamı kaybedebilir. Ayrıca ajanın planını yazmasını isteyin; eğer plan mantıklıysa onaylayın, değilse düzeltmesini söyleyin. Küçük değişikliklerin ardından ilgili testi koşun; tüm test paketini her seferinde koşturmak zaman kaybı olabilir ama kritik değişikliklerde tam test şarttır.

## Neleri iyi yapar, nerelerde dikkatli olunmalı

opencode tipik CRUD katmanlarını, DTO eşlemelerini, doğrulama anotasyonlarını ve repository testlerini hızlı üretir. Ancak Spring Boot’a özgü bazı tuzaklarda onu yakından izlemek gerekir.

| Görev | İyi prompt | Dikkat |
| CRUD endpoint’leri | 'Product entity’si için controller, service, repository ve DTO oluştur; validation ekle.' | Otomatik kodda `@Transactional` atlanabilir; kontrol et. |
| JPA sorgusu | 'OrderRepository’ye müşteri ID’sine göre son siparişleri getiren derived query ekle.' | N+1 riski; `@EntityGraph` veya fetch join gerekebilir. |
| Exception handling | 'Global exception handler ekle; MethodArgumentNotValidException için alan bazlı hata döndür.' | Spring Security erişim hatalarını da yanlışlıkla 500’e çevirebilir; ayır. |
| Test yazma | 'OrderServiceTest için Mockito ile birim testi yaz; stok azaltma davranışını doğrula.' | `@MockBean` yerine `@MockitoBean` (Spring Boot 3.4+) gerekebilir; sürümü bilmeden eski anotasyonu ekleyebilir. |
| Yapılandırma | 'application.yml içinde veritabanı ve JPA ayarlarını profil bazlı ayır.' | `spring.jpa.hibernate.ddl-auto=update` üretimde kalmasın; `validate` yap ve migration’ı Flyway/Liquibase’e bırak. |

Özellikle şu noktalara dikkat edin: `LazyInitializationException` alıyorsanız DTO mapping muhtemelen transaction dışında yapılıyor; mapping’i service katmanında veya `@EntityGraph` ile çözün. Entity’lerde Lombok `@Data` kullanmayın; ilişkili entity’lerde `equals`/`hashCode` sonsuz döngüye girebilir. Ajan bazen `spring.jpa.hibernate.ddl-auto=update` ile şemayı değiştirmeyi önerebilir; bunu kabul etmeyin, migration yazın. `@Transactional` self-invocation durumunda çalışmaz; aynı sınıf içi çağrıda transactional proxy devre dışı kalır. Ajan bu hatayı bilse bile ürettiği kodda atlayabilir.

Ajanın ürettiği kodda şunları da arayın: `@Cacheable` metotların aynı sınıftan çağrılması, `@Async` metotlarda return type’ın `void` yerine `Future` olması gerektiği, `@Modifying` sorgularında `clearAutomatically` eksikliği, `@Version` alanı olmadan optimistic lock yapılması, `@EntityListeners` ve `@CreatedDate` gibi auditing alanlarının unutulması. Bu tür detaylar, deneyimli Spring Boot geliştiricisinin gözünden kaçmaz; ajanı ona göre yönlendirin.

## Test ve doğrulama

opencode’a her değişiklikten sonra test komutunu çalıştırmasını söyleyin: `./mvnw test` veya Gradle için `./gradlew test`. Testcontainers testleri Docker gerektirir; ajan bazen Docker daemon çalışmıyorsa testi atlar veya hata verir, bu yüzden önce `docker info` ile kontrol edin. Yanlızca birim testleri değil, `./mvnw verify` ile paketleme ve varsa integration testleri de koşturun. Özellikle `@DataJpaTest` slice testlerinde H2 yerine Testcontainers kullanıyorsanız, ajanın test sınıfına `@AutoConfigureTestDatabase(replace = Replace.NONE)` eklemesini isteyin; aksi halde H2’ye düşüp PostgreSQL’e özgü SQL’i gizler. Kod incelemesinde `git diff` çıktısını tarayın: import kalıntısı, `ddl-auto` değişikliği, `@Transactional` silinmesi, DTO yerine entity dönmesi. Ajan bir testin geçtiğini söylese bile ilgili testi siz de çalıştırın; özellikle Testcontainers başlatma sürelerinde ajan çıktıyı yanlış yorumlayabilir.

Ayrıca `@SpringBootTest` kullanıyorsanız, bağlamı gereksiz yere şişirmemek için `@ActiveProfiles("test")` ile profil verin. Test verisi hazırlamak için `@Sql` veya Flyway migration’larını kullanın. `@DynamicPropertySource` ile Testcontainers bağlantı bilgilerini dinamik olarak verin. Ajanın test düzeltmelerinde yalnızca assert değiştirmek yerine gerçek hatayı çözmesini sağlayın; örneğin bir `NullPointerException` yerine eksik mock’u ekleyin. CI’da çalışacak testler için son adımda `./mvnw clean verify` veya `./gradlew clean build` komutunu koşmasını isteyin.

## Birden çok ajanı tek bir Spring Boot projesinde çalıştırma

Spring Boot projenizde birden fazla işi paralel ilerletmek istediğinizde AgentVera, her ajanın gerçek CLI komutlarını kendi terminal panelinde çalıştırır. Ajanlar ayrı git worktree’lerinde çalışarak dosyaları ezmez; birinin `OrderService` değişikliği diğerinin `ProductController` yamasını bozmaz. Her tur sonunda otomatik kod incelemesi, Spring Boot tuzaklarını dosya:satır olarak işaretler. Checkpoint’ler sayesinde yanlış bir migration değişikliğini tek tıkla geri alıp oturumu adım adım yeniden oynatabilirsiniz. Bu yaklaşım, [`paralel kodlama ajanları`](/blog/paralel-yapay-zeka-kodlama-ajani-araclari/) ile Spring Boot’ta daha güvenli çalışmayı sağlar.

## Sonuç

opencode, Spring Boot projelerinde katmanlı değişiklikleri hızlandıran ama denetim gerektiren bir araçtır. AGENTS.md dosyasını net tutun, görevleri küçük parçalara bölün, testleri her adımda koşturun ve diff’i gözden geçirin. Spring Boot’un kendine özgü tuzaklarında onu yalnızca kod üretici olarak değil, tecrübeli bir yan yana çalışma ortağı gibi yönetin.

## Sık sorulanlar

**opencode ile Spring Boot projesinde nasıl başlarım?** Proje kökünde terminal açıp opencode komutunu çalıştırın. Ajan, AGENTS.md dosyanızdaki build, test ve kod kurallarını okuyarak Spring Boot bağlamına uygun çalışır.

**AGENTS.md dosyasına Spring Boot için ne yazmalıyım?** Maven/Gradle komutlarını, paket yapısını, transaction ve DTO kurallarını, Testcontainers kullanımını ve lint komutunu yazın. Ajan her görevde bu kurallara uyar; böylece controller, service, repository tutarlı olur.

**opencode Testcontainers testlerini çalıştırabilir mi?** Evet, Docker çalışıyorsa ./mvnw test veya ./gradlew test ile Testcontainers testlerini başlatır. Docker daemon yoksa ajan testi atlayabilir veya hata verebilir; önce docker info ile kontrol edin.

**opencode Spring Boot’ta hangi hataları yapabilir?** LazyInitializationException, N+1 sorgu, ddl-auto=update önerisi, @Transactional sınırlarının yanlış yerde olması ve DTO yerine entity dönmesi gibi hatalar olabilir. Bu yüzden diff ve test çıktılarını gözden geçirin.

---

**AgentVera hakkında.** AgentVera, Solviera Teknoloji tarafından geliştirilen macOS, Windows ve Linux masaüstü uygulamasıdır. 18 yapay zeka kodlama ajanını (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) proje bazında, gerçek terminallerde ve kullanıcının kendi CLI kurulum ve girişleriyle yan yana çalıştırır. Ücretsiz planda sınırsız ajan vardır. İndir: https://agentvera.dev/indir/ · Fiyatlar: https://agentvera.dev/fiyatlar/