Codex ile Kotlin ve Android Geliştirme Rehberi

Codex’i bir Kotlin ve Android projesinde kullanmak için proje kökünde codex komutunu çalıştırın; ajan, AGENTS.md dosyanızdaki Gradle komutlarını, paket yapısını ve kuralları okuyarak çalışır. Jetpack Compose, ViewModel, coroutines, JUnit ve Espresso ile yapılan işlerde en verimli sonuç, planla–küçük adım–test et–diff incele döngüsünü uygulamakla gelir. Daha geniş Codex kullanımı için Codex sayfasına bakabilirsiniz.

Codex Kotlin ve Android işlerinde neden iyi çalışır

Codex, Kotlin ve Android tarafına özel iki şeyi iyi kullanır: derleyici hatalarını okuyup düzeltme ve Gradle/Android yapısındaki tekrarlayan kalıpları tanıma. Android projeleri genelde birden çok modül, version catalog, namespace ve resource klasörleri içerir; ajan dosya sisteminde gezinerek build.gradle.kts, AndroidManifest.xml ve libs.versions.toml arasındaki ilişkiyi görebilir. Örneğin bir modüldeki bağımlılığı version catalog’a taşırken hangi libs.* erişiminin hangi sürümü işaret ettiğini çözebilir. Ayrıca ./gradlew testDebugUnitTest gibi komutları kendi çalıştırıp sonuçları yorumlayabildiği için hata çıktısından doğrudan kod düzeltmeye geçebilir. Bu, özellikle coroutines testlerinde runTest ve dispatcher hatalarını hızlı kapatır. Yine de üretkenlik, projeye özgü kuralların açıkça yazılmasına bağlıdır; ajan Android’in runtime davranışını ve Compose compiler uyumunu tahmin etmekte zorlanabilir.

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

Proje kökündeki AGENTS.md, Codex’in her oturumda okuduğu bağlam dosyasıdır. Kotlin ve Android için build, test, lint komutlarını; paket yapısını; state yönetimi ve coroutines kurallarını; yasakları net yazın. Bağlam mühendisliği yaklaşımı için Bağlam mühendisliği: yapay zeka kodlama ajanları rehberi sayfasına bakabilirsiniz. Dosya ne kadar somut olursa ajan o kadar az yanlış varsayım yapar. Aşağıdaki örnek, gerçek bir kurumsal Android projesinde işe yarayan bir yapıyı gösterir:

# AGENTS.md

## Build ve test
- Derleme: ./gradlew assembleDebug
- Birim test: ./gradlew testDebugUnitTest
- Lint: ./gradlew lintDebug
- Cihaz testi: ./gradlew connectedDebugAndroidTest
- Format: ./gradlew ktlintCheck

## Klasör düzeni
- app/src/main/java/com/example/app/feature/... : ekran başına ui/, viewmodel/, data/ alt paketleri
- app/src/main/java/com/example/app/core/... : ortak modül
- Compose ekranları ui/ altında, ViewModel'ler viewmodel/ altında

## Kod kuralları
- ViewModel yalnızca StateFlow veya SharedFlow expose eder; Android sınıflarını import etme.
- UI state toplama için collectAsStateWithLifecycle kullan.
- Coroutines: viewModelScope dışında GlobalScope kullanma; dispatcher'ları inject et.
- Compose BOM ve Kotlin sürümünü değiştirmeden önce sor.
- !! operatörü, yeni modül veya bağımlılık eklemek için onay al.
- Her değişiklikten sonra ilgili testleri ve lint'i çalıştır.

Bu dosyada build ve test komutlarının yanı sıra klasör düzeni, ViewModel kuralı ve coroutines kısıtları vardır. collectAsStateWithLifecycle kullanımı gibi Compose detayları, ajanın modern Android kalıplarını uygulamasını sağlar. Yeni bir ekran istediğinizde ajan bu sözleşmeye göre ui, viewmodel ve data paketlerini doğru yerde oluşturur. Ayrıca yasaklar bölümü, riskli işlemlerde sizi uyarır.

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

Çalışma döngüsü: önce ajanın plan çıkarmasını isteyin; sonra tek bir sorumluluğu olan adımlara bölün; her adımda test ve lint çalıştırın; son olarak git diff ile değişiklikleri inceleyin. Codex’i başlatma ve ilk oturum detayları için Codex CLI nasıl kullanılır? Adım adım rehber sayfasına bakabilirsiniz. Bu döngü, ajanın büyük bir refactor’ü tek seferde yapıp ortalığı karıştırmasını önler. Örneğin ViewModel’den Compose ekranına state akışını değiştirirken önce ViewModel’i düzenletip testleri geçirtin, sonra composable’ı güncelletin. Her adım için somut komutlar:

• “Mevcut CartViewModel içindeki MutableStateFlow alanlarını StateFlow olarak dışarı aç ve updateCart fonksiyonunu viewModelScope.launch ile main-safe hale getir. Önce plan ver.”
• “ProductListScreen composable’ını daha küçük parçalara böl; her composable kendi @Preview fonksiyonuna sahip olsun. Mevcut tema ve typography’yi kullan; state’i yukarı taşı.”
• “OrderRepository için JUnit testlerini ekle. Sahte dispatcher kullan, runTest içinde yaz ve coVerify ile repository çağrılarını doğrula.”
• “Espresso ile checkoutButton tıklanınca ödeme ekranının açıldığını doğrulayan bir test yaz. Test öncesi @Before ile gerekli state’i hazırla, IdlingResource kullan.”
• “build.gradle.kts içinde tekrar eden sürümleri libs.versions.toml içine taşı. Compose BOM sürümünü değiştirme; sadece mevcut sürümleri katalogla.”

Bu komutlarda “önce plan ver” ifadesi kritik; ajanın düşünme adımını kullanarak sürpriz değişiklikleri azaltır. Ayrıca her komutun sonunda test edilebilir bir çıktı istenir.

İyi yaptığı işler ve dikkat edilmesi gerekenler

Codex, tekrarlayan dönüşümleri ve test üretimini iyi yapar; ancak Android’e özgü uyumluluk ve runtime konularında gözünüz üstünde olsun.

Kotlin/Android’e özgü en yaygın hatalar şunlardır: Compose compiler’ın Kotlin sürümüyle eşleşmemesi, ViewModel’de Android context import edilmesi, GlobalScope kullanımı ve Espresso testlerinde Thread.sleep ile bekleme. Ajan bazen collectAsState yerine collectAsStateWithLifecycle kullanmayı atlayabilir; bunu AGENTS.md’ye yazmak gerekir. Ayrıca yeni bir Compose API’si önerdiğinde sürümünün BOM içinde olup olmadığını doğrulayın. Gradle’da implementation(project(":core")) gibi modül bağımlılıklarını düzenlerken döngüsel bağımlılık oluşturmaması gerekir; bu tür değişikliklerde ajanın önerdiği planı siz onaylayın.

Test ve doğrulama

Codex ile çalışırken birim testleri ve lint’i sık çalıştırın. Özellikle her refactor sonrası ./gradlew testDebugUnitTest lintDebug komutunu ajanın kendisine çalıştırtın; ardından git diff ile yalnızca ilgili dosyaların değiştiğinden emin olun. JUnit tarafında runTest, StandardTestDispatcher ve sahte dispatcher kullanımını AGENTS.md’ye yazarsanız testler daha tutarlı olur. Espresso veya Compose UI testleri için emülatör açıkken connectedDebugAndroidTest çalıştırılabilir; ancak ajanın cihaz durumunu bozmadığını ve testleri @FlakyTest gibi etiketlerle yumuşatmadığını denetleyin. Ajan test yazarken sadece mutlu yolu değil, state boş, hata ve yükleme durumlarını da kapsamasını isteyin. ViewModel testlerinde MainDispatcherRule kullanılmadan viewModelScope çalıştırmak hataya yol açar; AGENTS.md’ye bu kuralı ekleyin. Ayrıca ajanın ./gradlew lintDebug çıktısındaki uyarıları görmezden gelmesini önlemek için lint’i her adımda çalıştırın ve kritik hataları engelleyin.

AgentVera ile birden fazla ajanı paralel çalıştırma

Birden fazla Codex oturumunu aynı Kotlin/Android projesinde koşmak istediğinizde AgentVera, ajanları kendi git worktree’sinde paralel çalıştırır. Böylece biri Compose ekranı üzerinde çalışırken diğeri ViewModel testlerini güncelleyebilir ve dosyalar çakışmaz. Bir ajanın turu bitince ikinci model otomatik kod incelemesi yapar; bulgular file:line ile bağlanır, bu özellikle Gradle dosyalarındaki uyumsuzlukları yakalar. Her turun checkpoint’i alınır; kötü bir refactor adımını tek tıkla geri alabilirsiniz. Token bütçeleri de uzun derleme ve test döngülerinde kontrol sağlar. AgentVera nasıl kullanılır: ilk proje, ajanlar ve ızgara sayfası başlangıç için rehberdir.

Sonuç

Codex, Kotlin ve Android projesinde doğru bağlam ve sıkı doğrulama döngüsüyle hızlı bir yardımcıdır; AGENTS.md’yi baştan yazmak, küçük adımlarla ilerlemek ve test/lint çıktılarına güvenmek gerekir. Gradle sürüm uyumları, Compose deneysel API’leri ve Espresso flakiness’i konusunda son kararı siz verin. Ajanı paralel çalıştırmak gerektiğinde AgentVera ile yalıtılmış worktree ve otomatik inceleme düzeni kurun.