Gradle’dan İlk Resmi ‘Agent Skills’ Hamlesi: Yapay Zeka Kodlama Ajanları İçin Deterministik Derleme ve Wrapper Yönetimi

LLM’lerin ‘Eski Gradle’ Yanılsamasına Son: Resmi gradle/gradle-skills Paketi Neyi Çözüyor?

Kurumsal Java, Kotlin ve Android projelerinde otonom kodlama ajanları (Claude Code, Cursor, GitHub Copilot, OpenAI Codex CLI ve Gemini CLI) uygulama kodunu yazmakta yüksek başarı gösterirken, sıra derleme (build) yapılandırmasına geldiğinde ciddi bir eğitim verisi önyargısıyla (training data bias) karşılaşmaktadır. Açık kaynak depolarındaki milyonlarca eski örnek nedeniyle büyük dil modelleri; kullanımdan kaldırılmış compile bildirimlerini, erken görev oluşturma (tasks.create) kalıplarını, sabit metinli bağımlılık tanımlarını veya monolitik buildSrc dizinlerini önermeye devam etmektedir.

Gradle mühendislik ekibi, derleme sistemini doğrudan ajan döngüsüne (agentic loop) entegre etmek amacıyla açık Agent Skills (SKILL.md) spesifikasyonuna uyumlu ilk resmi gradle/gradle-skills paketini yayımladı. Standartlaştırılmış YAML üst verisi ve aşamalı bağlam yükleme (progressive disclosure) mimarisi kullanan paket, yapay zeka ajanlarına güncel Gradle ve Develocity en iyi pratiklerini deterministik olarak öğretiyor.

[!IMPORTANT]
5 Sağlayıcı ve 7 Model Üzerinde Kıyaslama: Gradle ekibi, yayınladığı resmi yetenek paketini 5 farklı yapay zeka sağlayıcısına ait 7 farklı dil modeli ve çoklu ajan çalışma zamanı (harness) üzerinde test etti. Sonuçlar, yapılandırılmış SKILL.md talimatlarıyla donatılan daha küçük ve düşük maliyetli modellerin dahi derleme mühendisliği görevlerinde sınır (frontier) model doğruluğuna ulaştığını kanıtlıyor.

İlk Resmi Yetenekler: gradle-best-practices ve gradle-wrapper-upgrade

github.com/gradle/gradle-skills deposu altında açık kaynak olarak sunulan ilk sürüm, kurumsal projelerde en sık hata yapılan iki kritik iş akışına odaklanıyor:

flowchart TD
    A["Otonom Kodlama Ajanı<br/>(Claude Code / Cursor / Copilot / Gemini CLI)"] --> B{"SKILL.md Bağlam Yönlendiricisi<br/>(gradle/gradle-skills)"}
    B -->|"Derleme Denetimi & Optimizasyon"| C["1. gradle-best-practices Yeteneği"]
    B -->|"Güvenli Sürüm Geçişi"| D["2. gradle-wrapper-upgrade Yeteneği"]
    C --> E["Kotlin DSL, libs.versions.toml, build-logic,<br/>Configuration Cache ve Task Avoidance Analizi"]
    D --> F["İki Aşamalı Wrapper Güncelleme +<br/>distributionSha256Sum Kriptografik Doğrulama"]
    E --> G["Önceliklendirilmiş Etki Raporu & Otomatik Kod Yaması"]
    F --> H{"Derleme Sağlık Kontrolü"}
    H -->|"Başarılı"| I["Yeni Wrapper Sürümü Sabitlenir"]
    H -->|"Hata"| J["Otomatik Geri Alma (Rollback) & Ara Sürüm Önerisi"]

1. gradle-best-practices: Mimari Derleme Denetimi ve Otomatik Onarım

Bu yetenek devreye girdiğinde ajan; projedeki build.gradle.kts / build.gradle betiklerini, settings.gradle.kts dosyasını, gradle.properties parametrelerini, gradle/libs.versions.toml sürüm kataloğunu ve buildSrc/ veya build-logic/ altındaki eklenti kodlarını uçtan uca tarar:

• Yapılandırma Önbelleği (Configuration Cache) ve Görev Kaçınma (Task Configuration Avoidance): tasks.create yerine tembel (lazy) tasks.register ve Provider API kullanımını zorunlu kılar.
• Sürüm Katalogları (libs.versions.toml): Alt projelere dağılmış sabit sürüm dizgilerini merkezi TOML kataloğuna taşır.
• Konvansiyon Eklentileri (build-logic): Kök build.gradle.kts içindeki subprojects / allprojects bloklarını izole ve önbelleklenebilir build-logic bileşik derleme (composite build) eklentilerine dönüştürür.
• Etki Sıralı Raporlama: Tespit edilen darboğazları performans ve bakım etkisine göre sıralayarak onay alındığında doğrudan kod yamalarını uygular.

2. gradle-wrapper-upgrade: SHA-256 Sabitlemeli ve Otomatik Geri Almalı (Rollback) Yükseltme

Gradle sürüm yükseltmelerinde LLM ajanlarının yaptığı en tehlikeli hata, yalnızca gradle-wrapper.properties içindeki sürüm numarasını metin olarak değiştirip gradlew betiklerini ve JAR dosyasını eski sürümde bırakmalarıdır. gradle-wrapper-upgrade yeteneği bu süreci deterministik bir protokole bağlar:

1. Resmi Gradle dağıtım API'sinden hedef sürümün distributionSha256Sum kriptografik özetini çeker ve gradle-wrapper.properties dosyasına sabitler.
2. Wrapper görevini iki kez çalıştırarak hem yapılandırmayı hem de ikili (gradle-wrapper.jar ve gradlew) betikleri günceller.
3. Projenin yapılandırma aşamasını (help / --dry-run) çalıştırarak uyumluluğu doğrular.
4. Eğer uyumsuz bir eklenti nedeniyle yapılandırma başarısız olursa değişiklikleri otomatik olarak geri alır (rollback), sürüm notlarını analiz eder ve güvenli bir ara geçiş sürümü (step-down version) önerir.

Geleneksel LLM Çıktıları ile gradle-skills Destekli Ajanların Karşılaştırması

Açık SKILL.md standardı sayesinde paket, tek bir komutla farklı IDE ve CLI ajanlarına kurulabiliyor:

• Claude Code: /plugin marketplace add gradle/gradle-skills ve /plugin install gradle-skills@gradle-skills
• Cursor, GitHub Copilot, Codex ve Gemini CLI: npx skills add gradle/gradle-skills

Mühendislik Uygulaması: gradle-best-practices Uyumlu Konvansiyon Eklentisi ve Güvenli Wrapper Yapılandırması

Aşağıdaki referans uygulama, gradle-best-practices ve gradle-wrapper-upgrade yeteneklerinin kurumsal bir Java projesinde zorunlu kıldığı Configuration Cache uyumlu build-logic konvansiyon eklentisini ve SHA-256 sabitlenmiş gradle-wrapper.properties yapısını göstermektedir:

// Dosya: build-logic/convention/src/main/kotlin/com.tastutanlabs.java-service-conventions.gradle.kts
import org.gradle.api.tasks.testing.Test
import org.gradle.jvm.toolchain.JavaLanguageVersion

plugins {
    java
}

// 1. Deterministik JVM Toolchain Tanımı
java {
    toolchain {
        languageVersion.set(JavaLanguageVersion.of(25))
    }
}

// 2. Task Configuration Avoidance API (tasks.create yerine tasks.named / tasks.register)
tasks.withType<Test>().configureEach {
    useJUnitPlatform()
    maxParallelForks = (Runtime.getRuntime().availableProcessors() / 2).coerceAtLeast(1)
    // Configuration Cache uyumu için çalışma zamanında Project nesnesine erişilmez
    systemProperty("java.awt.headless", "true")
}

// 3. Giriş/Çıkışları Önbelleklenebilir (Cacheable) Özel Doğrulama Görevi
@CacheableTask
abstract class VerifyArchitectureManifestTask : DefaultTask() {
    @get:InputFile
    @get:PathSensitive(PathSensitivity.RELATIVE)
    abstract val manifestFile: RegularFileProperty

    @get:OutputFile
    abstract val reportFile: RegularFileProperty

    @TaskAction
    fun verify() {
        val content = manifestFile.get().asFile.readText()
        val isValid = content.contains("schemaVersion=2")
        reportFile.get().asFile.writeText("STATUS=${if (isValid) "VALID" else "INVALID"}\n")
    }
}

tasks.register<VerifyArchitectureManifestTask>("verifyArchitectureManifest") {
    manifestFile.set(layout.projectDirectory.file("config/architecture-manifest.properties"))
    reportFile.set(layout.buildDirectory.file("reports/architecture/verification.txt"))
}

# Dosya: gradle/wrapper/gradle-wrapper.properties
# gradle-wrapper-upgrade yeteneği tarafından SHA-256 sağlama toplamı ile sabitlenmiştir
distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
distributionUrl=https\://services.gradle.org/distributions/gradle-9.1.0-bin.zip
distributionSha256Sum=8b5e3f91a2c4d7e60f123456789abcdef0123456789abcdef0123456789abcde
networkTimeout=10000
validateDistributionUrl=true
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists

[!TIP]
Kurumsal Ekip Entegrasyonu: gradle/gradle-skills paketinin geliştirici makinesine manuel kurulmasına güvenmek yerine, proje deposundaki .claude/settings.json veya .agents/skills/ dizinine doğrudan sabitlenmesi önerilir. Böylece depoyu klonlayan her mühendisin kodlama ajanı, ilk istemden itibaren Configuration Cache ve Version Catalog kurallarını otomatik olarak uygular.