Flutter projesinde opencode, terminalde proje kökünde opencode komutuyla başlayan ve AGENTS.md dosyasındaki proje özelinde kuralları okuyan bir kodlama ajanıdır. Bu rehber; ajanı widget mimarisine uygun yönlendirmeyi, güvenli bir test döngüsü kurmayı ve paralel ajan kullanımını anlatıyor. Temel kurulum ve komut akışı için opencode nasıl kullanılır? Adım adım rehber sayfasına bakılabilir.
opencode neden Flutter projelerine uygun
opencode, yalnızca tek bir dosyayı değil reponun tamamını bağlam olarak görür; pubspec.yaml, lib altındaki widget ağacı, test klasörleri ve platform kanallarının bulunduğu android/ios klasörleri dahil. Flutter’a özgü komutları (flutter pub get, flutter analyze, flutter test) kendisi çalıştırıp çıktıyı yorumlayabildiği için düzeltme döngüsü kısalır. Riverpod veya Bloc geçişlerinde onlarca dosyada tutarlı düzenleme yapabilir; ConsumerWidget dönüşümü, provider ekleme, dispose çağrıları gibi ayrıntıları atlamaz. Aynı şekilde MethodChannel boilerplate yazarken Dart tarafındaki tip dönüşümü ve hata yönetimini standart hale getirir. Bu tür bir ajan seçerken opencode mu Claude Code mu? Dürüst bir karşılaştırma yazısı da karar vermeye yardımcı olabilir.
Projeyi ajana hazırlama: AGENTS.md
opencode proje kökündeki AGENTS.md dosyasını her çalıştırmada okur; bu yüzden Flutter projesinin komutlarını, klasör düzenini ve değişmez kurallarını buraya yazmak ilk adımdır. Kısa ve kesin bir dosya, ajanın flutter test yerine yanlış komut çalıştırmasını veya feature dışına çıkmasını önler.
# AGENTS.md
## Komutlar
flutter pub get # bağımlılıkları çek
flutter analyze # statik analiz
flutter test # tüm testleri çalıştır
dart format lib test # biçimlendirme
## Klasör düzeni
lib/core/ # tema, router, ağ katmanı
lib/features/<feature>/ # her özellik kendi klasöründe
lib/shared/widgets/ # ortak widget'lar
test/features/<feature>/ # feature bazlı testler
## Flutter kuralları
- Yeni global state için Riverpod kullan; ProviderScope kökte olmalı.
- State tutan widget'larda const constructor fırsatlarını kolla.
- Widget metotları 150 satırı geçmesin; gerekiyorsa extract widget yap.
- Platform kanallarında her MethodChannel çağrısını try-catch içine al ve tip dönüşümünü doğrula.
- freezed/json_serializable kullanıyorsan değişiklikten sonra `dart run build_runner build --delete-conflicting-outputs` çalıştır.Bu örnekte build_runner komutu özellikle önemlidir; çünkü freezed veya json_serializable kullanan projelerde ajan yalnızca .dart dosyasını değiştirip üretilen dosyayı yenilemezse analiz hataları çıkar. AGENTS.md dosyasını güncelledikten sonra opencode ile yeni bir oturum başlatmak yeterlidir.
Çalışma döngüsü ve örnek prompt’lar
opencode ile en verimli döngü, önce plan istemek, sonra küçük bir diff uygulatmak, ardından testleri çalıştırıp git diff çıktısını incelemektir. Ajan tek seferde büyük bir refactor yaparsa Flutter’da hata ayıklamak zorlaşır; bu yüzden her isteği tek bir sorumlulukla sınırlayın.
- “Mevcut auth akışını incele; Riverpod’a taşımak için dosya dosya bir plan çıkar, kod yazma.”
- “Login ekranını ConsumerWidget’e çevir; mevcut widget testlerini bozma ve eksik testleri tamamla.”
- “Ürün listesi widget’ını küçük parçalara ayır; her yeni widget’ta const constructor kullan.”
- “MethodChannel üzerinden batarya seviyesi okuyan servisi yaz; Android ve iOS tarafındaki gerekli değişiklikleri belirt ama sadece Dart tarafını değiştir.”
- “pubspec.yaml’daki bağımlılıkları güncelle; sonra flutter pub get, flutter analyze ve flutter test komutlarını çalıştırıp sonucu özetle.”
Bu prompt’ları açık uçlu “uygulamayı düzelt” yerine kullanmak, ajanın hem Dart tarafında kalmasını hem de testleri göz ardı etmemesini sağlar.
Hangi işlerde iyi, nerelerde dikkatli olmalı
opencode; widget ağacını sadeleştirme, state yönetimi geçişleri, widget ve birim testi yazma, platform kanalı servislerini sarmalama ve pubspec bağımlılıklarını güncelleme işlerinde iyi sonuç verir. Özellikle aynı deseni birçok dosyaya uygulamak gerektiğinde hız kazandırır.
Dikkat edilmesi gereken yerler Flutter’a özgüdür: freezed/json_serializable gibi üretilen dosyalar varsa ajan build_runner çalıştırmayı unutabilir; golden testler piksel farkı nedeniyle kolayca kırılır ve güncelleme bilinçli yapılmalıdır. Android/iOS klasörlerinde yapılan değişiklikler Dart analiziyle yakalanmaz; platform kanalı imza uyumsuzluğu emülatörde patlayabilir. Ayrıca async metotlarda BuildContext kullanımı, mounted kontrolü ve const optimizasyonu gibi ayrıntılarda ajan bazen tembel davranır. Büyük bir widget refactor’ünde ilk turda flutter analyze çalıştırmasını şart koşun.
Flutter’da test ve doğrulama
Her ajan turundan sonra en az flutter analyze ve flutter test çalıştırın; bunları ajanın kendisine de yaptırabilirsiniz. Sonuçları körlemesine kabul etmeyin, git diff ile widget yapısındaki istenmeyen değişiklikleri ayıklayın. Özellikle test yazdırırken mock ve fake’lerin test klasörüyle sınırlı kalmasını isteyin.
| İş | Ajandan istenecek | Doğrulama |
|---|---|---|
| Widget bölme veya UI değişikliği | “İlgili widget testlerini çalıştır; bozulanları düzelt.” | flutter test test/features/... |
| State yönetimi geçişi | “Eski state erişimlerini listele; testleri güncelle.” | flutter analyze && flutter test |
| Platform kanalı değişikliği | “MethodChannel tiplerini ve hata yollarını test et.” | flutter test test/platform/... + cihazda manuel test |
| Bağımlılık güncelleme | “Çakışmaları çöz; komutları çalıştır.” | flutter pub get && flutter analyze && flutter test |
Golden test dosyaları varsa yalnızca bilinçli bir görsel değişiklikten sonra flutter test --update-goldens çalıştırın ve oluşan görüntü farklarını git diff ile inceleyin. Platform kanalları ve navigasyon gibi davranışlar için emülatörde kısa bir manuel tur hâlâ gereklidir.
Bir Flutter projesinde birden fazla ajanla çalışmak
Flutter projesinde biri state yönetimi geçişini, diğeri platform kanalı servisini üstlendiğinde AgentVera’nın paralel düzeni faydalı olur. Her ajan kendi git worktree’sinde çalıştığı için lib/ ve test/ dosyaları çakışmaz; değişiklikler ayrı dallarda birleşir. Ajan turu bitince ikinci modelin yaptığı otomatik kod incelemesi, widget ağacındaki hataları file:line ile gösterir. Checkpoint’ler sayesinde hatalı bir refactor tek tıkla geri alınır ve oturum adım adım izlenir.
Sonuç
opencode’u Flutter projesine bağlamak, aslında projeye net bir AGENTS.md kazandırmakla başlar. Küçük adımlarla ilerleyip her turda flutter analyze ve flutter test çalıştırdığınızda ajan; widget refactor’lerinden platform kanallarına ve bağımlılık güncellemelerine kadar ciddi iş çıkarır. Paralel çalışma gerektiğinde AgentVera ile aynı repoyu güvenle bölebilirsiniz.