GitHub Copilot CLI, Spring Boot projelerinde terminalden copilot komutuyla başlattığınız bir kodlama ajanıdır. Bu rehber, Maven veya Gradle kullanan, Spring Data JPA ve JUnit 5 içeren bir projede ajanı nasıl yapılandıracağınızı ve güvenli bir çalışma döngüsü kuracağınızı gösterir. Genel kurulum ve komutlar için GitHub Copilot CLI sayfasına bakabilirsiniz.
Neden Spring Boot işlerine uygun
Spring Boot projeleri katmanlı ve kurala dayalıdır; controller, service, repository, DTO ve entity paketleri belirli bir düzen izler. GitHub Copilot CLI, proje talimatlarını ve mevcut kodu okuyarak bu yapıya uyum sağlar. pom.xml veya build.gradle üzerinden bağımlılıkları görür, src/main/java altındaki paket düzenini takip eder. Uygulamanın application.yml veya application.properties dosyalarındaki profil ve veritabanı ayarlarını okur; böylece test konfigürasyonu önerirken gerçek ayarlara sadık kalır. Maven wrapper veya Gradle wrapper komutlarını kullanarak test çalıştırabilir, hata mesajlarını yorumlayıp düzeltebilir. JPA repository türetilmiş sorguları, DTO eşleme ve validation ekleme gibi tekrar eden işleri hızlandırır. Özellikle Testcontainers ile entegrasyon testi yazarken container konfigürasyonunu proje bağlamına göre üretir. Ayrıca Spring Boot’un otomatik konfigürasyonu sayesinde ajan, yeni bir bağımlılık eklediğinizde hangi bean’lerin etkileneceğini anlayabilir ve buna göre öneriler sunar.
Projeyi ajan için hazırlama: talimat dosyaları
GitHub Copilot CLI, proje kökündeki .github/copilot-instructions.md veya AGENTS.md dosyasını okur. Bu dosyaya Spring Boot’a özel kuralları yazmak, ajanın tahmin yürütmesini azaltır ve çıktıyı standartlaştırır. Talimat dosyasına build komutlarını, test komutlarını, lint/format kontrollerini, paket yapısını ve Spring Boot’a özgü kuralları ekleyin. Örneğin controller’ların yalnızca DTO alıp döndürmesi, entity’lerin doğrudan serialize edilmemesi, @Transactional kullanımının yazma işlemleriyle sınırlandırılması ve JPA ilişkilerinde lazy loading’in yönetimi gibi konuları netleştirin. Aşağıdaki örnek, Maven ve Gradle seçenekleriyle birlikte paket yapısını ve kuralları içerir.
# Spring Boot projesi için Copilot talimatları
## Build ve test
- Maven: `./mvnw clean verify`
- Gradle: `./gradlew clean test`
- Tek test: `./mvnw -Dtest=UserControllerTest test` veya `./gradlew test --tests UserControllerTest`
- Lint/format: `./mvnw spotless:check` (kuruluysa)
## Paket yapısı
- `com.example.demo.controller` REST controller'lar
- `com.example.demo.service` iş mantığı
- `com.example.demo.repository` Spring Data JPA repository'ler
- `com.example.demo.dto` request/response DTO'lar
- `com.example.demo.entity` JPA entity'ler
- `com.example.demo.exception` özel exception sınıfları ve `@ControllerAdvice`
## Kurallar
- Controller'lar yalnızca DTO alır/döner; entity'yi doğrudan serialize etme.
- Service katmanında `@Transactional` yalnızca yazma işlemlerinde kullan.
- Entity'lerde `FetchType.LAZY` varsayılan; DTO eşleme service içinde transaction açıkken yap.
- Validation için `spring-boot-starter-validation` kullan, `@Valid` ekle.
- Testlerde Testcontainers kullan; gerçek veritabanı yerine PostgreSQL container başlat.
- Migration için Flyway veya Liquibase kullan; yeni şema değişikliklerinde migration dosyası ekle.
- Hata yönetimi için `@RestControllerAdvice` kullan; standart hata formatı döndür.Talimat dosyasını kısa ve spesifik tutun; uzun genel yapay zeka metinleri eklemek ajanın odaklanmasını zorlaştırır. Proje geliştikçe dosyayı güncelleyin; örneğin yeni bir modül eklediğinizde paket yapısını ve test komutlarını güncelleyin. Talimat dosyası yazımıyla ilgili genel ipuçları için CLAUDE.md nasıl yazılır? AGENTS.md ve GEMINI.md rehberi’ne bakabilirsiniz.
Çalışma döngüsü: planla, küçük adım at, testi çalıştır, diff’i incele
Her görevi tek bir büyük komutla vermeyin. Ajanla şu sırayla çalışın: önce mevcut kodu ve testleri incelemesini isteyin; sonra küçük bir değişiklik yaptırın; ./mvnw test veya ./gradlew test çalıştırın; diff’i inceleyip kabul edin. Değişiklik yapmasını istediğiniz dosyayı ve beklenen davranışı açıkça yazın; mvn clean verify çalıştırmasını istemek, sadece test et demekten daha nettir. Kod tabanını hızlı tanımak için Yapay zeka ajanları için kod haritası yaklaşımını kullanabilirsiniz. Aşağıdaki örnek komutlar Spring Boot’ta sık kullanılan görevler için başlangıç noktasıdır.
- Mevcut
UserControllersınıfını incele;GET /users/{id}endpoint’ine 404 durumunda özel hata mesajı döndüren@ExceptionHandlerekle. OrderServiceiçindecreateOrdermetodunu yaz; stok kontrolü yap, yetersiz stoktaInsufficientStockExceptionfırlat ve@Transactionalkullan.ProductRepositoryiçinfindByCategoryAndActiveTruemetodunu ekle ve bunu kullanan bir service testi yaz.- Testcontainers ile PostgreSQL kullanan bir entegrasyon testi oluştur;
OrderRepositoryiçin save ve find testlerini yaz. - Maven build hatalarını düzelt;
mvn clean verifyçalıştır ve tüm testleri geçir.
Her adımdan sonra ajanın yaptığı değişiklikleri git diff ile inceleyin; özellikle otomatik oluşturulan kodda import’ların doğru olduğundan ve gereksiz dosya eklenmediğinden emin olun. Küçük adımlar, bir hatanın kaynağını bulmayı kolaylaştırır ve transaction yönetimi gibi ince konularda regresyon riskini azaltır.
Tipik Spring Boot görevleri ve dikkat edilecek noktalar
GitHub Copilot CLI özellikle controller endpoint ekleme, DTO ve validation, JPA repository metodları, JUnit 5 testleri ve Testcontainers konfigürasyonunda güvenilirdir. Bu görevlerde ajan, mevcut pattern’leri takip ederek tutarlı kod üretir. Buna karşılık transaction sınırları, lazy loading, veritabanı şeması değişiklikleri ve test izolasyonu gibi alanlarda her diff’i dikkatle inceleyin. Örneğin ajan bir service metoduna @Transactional eklerken read-only olması gereken sorguları atlayabilir veya transaction içinde DTO eşleme yaparken lazy loading hatasına yol açabilir. Veritabanı şeması değişikliklerinde Flyway migration dosyası oluşturmak yerine doğrudan ddl-auto: update kullanmayı önerebilir; bu yaklaşım production’da risklidir. Test izolasyonunda ise Testcontainers container’larının her test sınıfı için yeniden başlatılması maliyetli olabilir. Aşağıdaki tablo sık karşılaşılan tuzakları özetler.
| Alan | Copilot CLI’nin tipik davranışı | Kontrol etmeniz gereken |
|---|---|---|
@Transactional | Service metoduna ekler ama bazen read-only’yi atlar | Yazma işlemlerinde sınırları ve rollback kurallarını doğrulayın |
| JPA ilişkileri | FetchType.LAZY bırakır ancak DTO dönüşümünde LazyInitializationException oluşabilir | Dönüşümü transaction içinde yapın veya fetch join kullanın |
| Testcontainers | @Container tanımlar ancak bekleme stratejisi eksik olabilir | waiting for ve withReuse ayarlarını kontrol edin |
| Validation | @Valid ekler ama grup veya custom validator unutabilir | Request DTO’larında tüm alanları ve iş kurallarını inceleyin |
Bu tuzakların çoğu, talimat dosyasına net kurallar ekleyerek ve her değişiklikten sonra testleri çalıştırarak önlenebilir.
Spring Boot’ta test ve doğrulama
Her adımdan sonra testleri çalıştırmak pazarlık konusu değildir. Ajanın önerdiği kodu kabul etmeden önce ./mvnw clean verify veya ./gradlew clean test çalıştırın. Tek bir testi hedeflemek için ./mvnw -Dtest=OrderServiceTest test kullanın; Gradle için ./gradlew test --tests OrderServiceTest. Ajan test yazarken @DataJpaTest ile repository katmanını, @WebMvcTest ile controller katmanını izole test etmeyi tercih etmelidir. Tam entegrasyon senaryolarında @SpringBootTest ve Testcontainers kullanılabilir. Bu ayrımı talimat dosyasına yazarsanız ajan daha tutarlı testler üretir. Entegrasyon testlerinde ajanın @Container tanımını ve bekleme stratejisini kontrol edin; waiting for ve withReuse ayarlarını doğrulayın. Ajanın testleri geçirmek için üretim kodunu gevşetmesine izin vermeyin; testlerin anlamlı assertion’lar içerdiğini, exception durumlarını ve sınır koşullarını kapsadığını doğrulayın.
Aynı Spring Boot projesinde birden fazla ajan: AgentVera
AgentVera, GitHub Copilot CLI dahil birden fazla CLI ajanını aynı pencerede gerçek terminal panellerinde çalıştıran bir masaüstü uygulamasıdır. Spring Boot projelerinde paralel işler için her ajanı kendi git worktree’sinde çalıştırmak dosya çakışmalarını önler; örneğin biri yeni bir controller üzerinde çalışırken diğeri repository ve migration işlerini yürütebilir. Ajanın turu bittiğinde ikinci bir modelin otomatik kod incelemesi yapması, JPA transaction hatalarını ve eksik validation’ları file:line bağlantılarıyla yakalar. Her turun checkpoint olarak saklanması ise riskli bir refactor’ü tek tıkla geri almayı ve oturumu adım adım yeniden oynatmayı sağlar.
Sonuç
GitHub Copilot CLI, Spring Boot projelerinde doğru talimatlar ve disiplinli bir test döngüsüyle ciddi zaman kazandırır. En büyük değer, tekrar eden katman kodunu ve test taslaklarını üretmekte; risk ise transaction ve veri erişimi detaylarında. Ajanın önerdiği her diff’i inceleyin, testleri çalıştırın ve gerekirse AgentVera gibi araçlarla paralel çalışmayı kontrollü hale getirin.