Cursor Agent Kotlin ve Android ile Verimli Kodlama Rehberi

cursor-agent komutunu Kotlin ve Android proje klasöründe çalıştırdığınızda Cursor Agent, Gradle yapılarını, Kotlin kaynaklarını ve testleri doğrudan okuyup değiştirebilir. Bu rehber, Jetpack Compose, ViewModel, coroutines, JUnit ve Espresso içeren tipik bir projede agent ile güvenli ve hızlı çalışma düzenini uçtan uca gösterir. Odak; somut komutlar, proje talimatları ve doğrulama döngüsüdür.

Cursor Agent neden Kotlin ve Android işine uygun

Cursor Agent terminalde çalıştığı için Android Studio açık olmasa da projeyle etkileşime girer. Gradle wrapper’ı çalıştırabilir (./gradlew assembleDebug), derleme hatalarını okuyabilir, kaynak kodda düzeltme yapabilir ve aynı oturumda testleri yeniden çalıştırabilir. Kotlin tarafında coroutines, StateFlow ve Compose gibi API’leri anlaması, ViewModel’i repository’den ayıran yapıyı bozmadan refactor yapmasını kolaylaştırır. Android projelerinde sık kullanılan modül yapısını (app, core, feature) ve libs.versions.toml gibi sürüm kataloğunu tanır. Ayrıca AGENTS.md veya .cursor/rules içindeki talimatlara uyar; böylece projeye özel kuralları (minSdk, test komutları, yasak desenler) her çalıştırmada uygular. Bu, özellikle Android’e özgü tuzaklarda tutarlılık sağlar.

Agent, Gradle Kotlin DSL (build.gradle.kts) dosyalarını da düzenleyebilir; bağımlılık eklerken libs.versions.toml üzerinden eklemeyi tercih eder. Compose önizleme fonksiyonlarını ve @Preview etiketlerini tanır, böylece UI değişikliklerinde ekranı statik olarak doğrulamaya yardımcı olur. Kotlin’in null safety ve immutable data class kullanımına uyum sağlar; örneğin, data class ile UI state tanımlamasını standartlaştırır. Tüm bunlar, Android geliştirme iş akışına uyum sağlar.

Projeyi agent için hazırlamak

Agent’in en önemli avantajı, proje kökündeki AGENTS.md veya .cursor/rules dosyasını her oturumda okumasıdır. Bu dosyaya Android’e özgü komutları, klasör düzenini ve kod stillerini yazarsanız agent her değişiklikte doğru doğrulamayı yapar. Aşağıdaki örnek, tipik bir Kotlin/Android projesi için yeterli bir başlangıçtır:

# Android / Kotlin Proje Talimatları

## Komutlar
- Derleme: ./gradlew assembleDebug
- Birim test: ./gradlew testDebugUnitTest
- Lint: ./gradlew lintDebug
- Cihaz testi: ./gradlew connectedDebugAndroidTest

## Klasör kuralları
- Uygulama kodu: app/src/main/java/...
- Birim testleri: app/src/test/java/... (JUnit + MockK veya Mockito)
- Cihaz testleri: app/src/androidTest/java/... (Espresso + Compose test kütüphanesi)
- Compose ekranları feature bazında: ui/<feature>/ paketinde tutulur.

## Kod kuralları
- Yeni UI yalnızca Jetpack Compose ile yazılır; XML layout ekleme.
- ViewModel'ler StateFlow kullanır, UI state immutable data class olur.
- Coroutines'lar viewModelScope veya rememberCoroutineScope içinde başlatılır; GlobalScope kullanma.
- Min SDK 26; uyumluluk için gerekmedikçe API seviyesi yükseltme.
- Renk ve tema değişiklikleri yalnızca MaterialTheme üzerinden yapılır.
- Her mantık değişikliğinden sonra ilgili birim testi ve lintDebug çalıştır.

Bu dosyayı sürüm kontrolüne ekleyin; agent, değişiklik yapmadan önce ve sonra bu komutları kullanır. Terminalde cursor-agent komutunu çalıştırmadan önce dosyanın güncel olduğundan emin olun. Daha geniş kurulum adımları için Cursor CLI nasıl kullanılır? Adım adım rehber’e bakabilirsiniz. Ayrıca, projede çok modül varsa, her modülün test ve lint komutlarını da ekleyin; örneğin ./gradlew :feature:login:testDebugUnitTest gibi. Agent bu komutları, yalnızca ilgili modülde değişiklik yaptığında kullanabilir. Kurallara ek olarak, local.properties içindeki SDK yolunun doğru olduğundan ve ANDROID_HOME ortam değişkeninin ayarlı olduğundan emin olun; aksi halde agent derleme hatası alır.

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

Cursor Agent ile verimli döngü dört adımdır: plan, küçük adım, testi çalıştır, diff’i incele. Büyük bir özelliği tek prompt’ta istemek yerine, önce hedefi netleştirin, sonra agent’a tek bir endişeyi verin. Her değişiklikten sonra ./gradlew testDebugUnitTest veya lintDebug çalıştırın ve git diff’i gözden geçirin. Aşağıdaki promptlar tipik Kotlin/Android görevleri için başlangıçtır:

• “MainActivity’de Compose Navigation kurulu değil. Basit iki ekranlı (liste/detay) navigation ekle, ViewModel ile liste state’ini yönet.”
• “Mevcut UserRepository’yi Flow döndürecek şekilde refactor et ve birim testini güncelle.”
• “Şu ViewModel’deki state birleştirme mantığını test etmek için JUnit testi yaz; sahte repository kullan.”
• “androidTest içinde bir ekranın Compose testini yaz: butona tıklayınca metin görünür.”
• “lintDebug çıktısındaki UnusedResources uyarılarını temizle; yalnızca güvenli silmeleri yap.”

Her prompt’ta beklenen girdi/çıktıyı küçük tutun. Örneğin “şu dosyada şu fonksiyonu ekle” yerine “şu ekran için şu state’i tanımla ve test et” deyin. Agent her adımda yalnızca bir dosya grubunu değiştirmeli; böylece diff incelemesi kısa kalır. Ayrıca, güvenli bir iş akışı için Vibe coding nasıl yapılır? Güvenli bir iş akışı’ndaki küçük doğrulama adımlarını uygulayın.

Bir prompt verirken, agent’in hangi dosyaları değiştirebileceğini sınırlayın. Örneğin, “Yalnızca LoginViewModel.kt ve LoginScreen.kt dosyalarını değiştir” gibi bir cümle, kapsamı netleştirir. Agent’in plan oluşturmasına izin verin, ancak planı onaylamadan kod üretmesine izin vermeyin. Çoğu zaman, önce “ne yapacaksın? dosya listesi ver” diye sorarak planı görebilirsiniz. Daha sonra “go” veya “devam et” diyerek uygulamasını isteyin. Bu, beklenmedik büyük değişiklikleri önler.

Agent’in iyi yaptığı işler ve dikkat edilecek noktalar

Cursor Agent, Kotlin/Android projelerinde özellikle şu görevlerde güvenilirdir: yeni Compose ekranı eklemek, ViewModel’de StateFlow’a geçmek, repository’yi coroutines ile refactor etmek, bağımlılıkları libs.versions.toml üzerinden güncellemek ve JUnit testlerini genişletmek. Ayrıca lint uyarılarını kategorize edip güvenli olanları düzeltebilir.

Ancak Android’e özgü tuzaklarda agent’i yakından izleyin:

Ek olarak, Activity yaşam döngüsü, configuration change (örneğin ekran döndürme) ve process death senaryolarında state kaybı riski vardır. Agent bazen state’i rememberSaveable yerine remember ile tutabilir; bu, döndürme sonrası veri kaybına yol açar. Navigation argument’leri için type-safe navigation kullanmak yerine string route’lara dönebilir; bu da kırılganlık yaratır. Agent’in ürettiği kodu, özellikle yaşam döngüsü ve config change senaryoları için elle doğrulayın. Ayrıca, coroutines’lerde launch yerine async kullanımı, exception handling eksikliği veya collect yerine collectLatest yanlış anlayışı gibi hatalar oluşabilir. Bu yüzden her coroutines değişikliğinde mutlaka unit test ve lint çalıştırın.

Kotlin ve Android için test ve doğrulama

Agent’den istenen her değişiklikten sonra en az üç doğrulama yapın: birim testleri (./gradlew testDebugUnitTest), lint (./gradlew lintDebug) ve derleme (./gradlew assembleDebug). Cihaz testleri gerekiyorsa bir emülatör açıp ./gradlew connectedDebugAndroidTest çalıştırın veya testi agent’a “emülatörde çalıştır” diye tarif edin. Agent’in yalnızca test çıktısına bakıp “geçti” demesine izin vermeyin; raporları app/build/reports altında kontrol edin. Espresso testleri için IdlingResource veya Compose test waitUntil kullanımı gibi senkronizasyon detaylarını agent’a net verin.

Birim testlerinde MockK veya Mockito kullanımı yaygındır; agent’e hangi mocking kütüphanesini kullanacağını söyleyin. Örneğin, “MockK ile coEvery ve coVerify kullan” gibi. ViewModel testlerinde MainDispatcherRule veya Dispatchers.setMain gibi coroutines test kurallarını belirtin, aksi takdirde test çalışmayabilir. Compose testlerinde createComposeRule() kullanımı ve onNodeWithText gibi matcher’ları hatırlatın. Son olarak, her commit öncesi git diff ile yalnızca istenen dosyaların değiştiğinden emin olun. Agent’in dokunmaması gereken dosyalar arasında local.properties, gradle.properties (özellikle JVM args) ve imzalama anahtarları sayılabilir.

Birden fazla agent ile çalışmak: AgentVera

AgentVera, Cursor Agent dahil birden çok kodlama ajanının gerçek komut satırı araçlarını tek pencerede, her biri kendi terminal panelinde çalıştırır. Kotlin ve Android projesinde asıl değer; ajanların kendi git worktree’lerinde paralel çalışarak dosya çakışması yaşamaması, her tur sonunda ikinci bir modelin kodu file:line bağlantılarıyla incelemesi ve her turun anlık görüntüsünün tek tıkla geri alınabilmesidir. Ayrıca ajan başına token bütçesi tanımlayarak, yanlış bir refactor’ün tüm günü tüketmesini engellersiniz. Bu üç yetenek, Compose ekranları ve veri katmanını paralel geliştirirken risk azaltır. Bu yaklaşım, paralel kodlama ajanları için en iyi araçlar başlığında da ele alınmıştır.

Sonuç

Cursor Agent’ı Android projenize alıştırmanın en hızlı yolu, AGENTS.md dosyasını doğru komutlarla doldurmak ve küçük, test edilebilir adımlarla çalışmaktır. Bu düzen, agent’in Kotlin ve Android ekosistemine özgü detayları öğrenmesini sağlar; siz de diff’i ve testleri her adımda doğrulayarak kontrolü elinizde tutarsınız. Birden fazla özelliği aynı anda ilerletmeniz gerektiğinde AgentVera gibi paralel çalışma araçları devreye girer.