Cursor Agent ile Flutter projelerinde verimli çalışma

Cursor Agent’ı Flutter projenizin kök dizininde cursor-agent komutuyla başlatıp, proje kurallarınızı AGENTS.md veya .cursor/rules dosyasına yazarak Dart widget yapısına, state management seçimine ve test komutlarına uygun kod üretmesini sağlayabilirsiniz. Bu yazıda ajanın Flutter ile güvenli ve verimli çalışması için kurulum, döngü ve doğrulama adımlarını pratik olarak anlatıyorum.

Cursor Agent neden Flutter işlerine uygun?

Flutter projeleri güçlü bir klasör disiplini, analizör ve test altyapısı gerektirir; Cursor Agent terminalde gerçek komutlar çalıştırabildiği için flutter pub get, dart run build_runner build veya flutter test gibi adımları kendisi yürütüp sonuçları yorumlayabilir. Widget ağacı, provider veya Bloc gibi katmanlar arası bağımlılıklar yazılı kurallarla netleştirildiğinde ajan, yalnızca kod yazmakla kalmaz; mevcut mimariye uygun dosya ekler, import sıralarını düzeltir ve testleri günceller. Aynı projede birden fazla platform dosyası (Android, iOS) değişeceği zaman bile AGENTS.md içindeki platform kanalı sarmalayıcı kuralı sayesinde ajan dağınık MethodChannel çağrıları üretmek yerine tek bir sınıf altında toplar.

Projeyi ajan için hazırlama: AGENTS.md ve .cursor/rules

Ajan proje kökündeki AGENTS.md dosyasını veya .cursor/rules altındaki kural dosyalarını otomatik okur. Flutter için buraya sadece genel yazılım kuralları değil; komut satırları, klasör sözleşmeleri, state management tercihi ve yasaklar yazılmalıdır. Aşağıdaki örnek, Riverpod tabanlı bir proje için başlangıç noktasıdır:

# AGENTS.md

## Komutlar
- Bağımlılık kurulumu: `flutter pub get`
- Kod üretimi: `dart run build_runner build --delete-conflicting-outputs`
- Lint: `flutter analyze`
- Test: `flutter test`
- Tek test dosyası: `flutter test test/unit/auth_service_test.dart`

## Klasör düzeni
- `lib/features/<feature>/presentation`: widget'lar, ekranlar
- `lib/features/<feature>/application`: riverpod provider'lar, notifier'lar
- `lib/features/<feature>/domain`: entity, repository arayüzleri
- `lib/features/<feature>/data`: repository implementasyonları, model, veri kaynakları
- `test/`: `test/unit` ve `test/widget` altında tutulur

## Kurallar
- State management için Riverpod kullan; `setState` yalnızca lokal UI state'i için.
- Widget dosyalarında iş mantığı yazma; provider veya repository'e taşı.
- Model sınıflarında `copyWith`, `==` ve `hashCode` için freezed kullan.
- Platform kanalları `lib/core/platform/` altında tek bir sarmalayıcı sınıfta toplanır.
- Asenkron işlemlerde `FutureBuilder` yerine `AsyncValue` ve Riverpod kullan.
- Yeni bir repository eklerken arayüzünü `domain`'de, somut sınıfını `data`'da yaz.

Bu dosya sayesinde ajan yeni bir görev aldığında hangi komutları çalıştıracağını, nereye dosya koyacağını ve hangi paketten kaçınacağını bilir. Kuralları kısa ve net tutun; özellikle state management ve platform kanalı kararları projenin genelini etkilediği için yazılı olması önemlidir. Terminalde cursor-agent komutunun kurulumu hakkında Cursor CLI nasıl kullanılır? Adım adım rehber sayfasını inceleyebilirsiniz. Cursor Agent hakkında daha fazla bilgi için Cursor Agent sayfasına da bakabilirsiniz.

Çalışma döngüsü ve Flutter için örnek komutlar

Ajanla çalışırken büyük bir özelliği tek seferde istemek yerine planı parçalayın. Önce ajanın mevcut kodu okumasını sağlayın; ardından küçük bir değişiklik isteyin, flutter analyze ve flutter test çalıştırmasını isteyin, son olarak git diff ile değişiklikleri inceleyin. Bu döngü, widget ağacındaki beklenmeyen kırılmaları erken yakalar. İyi bir döngü şöyle işler: önce ajanın dosya listesini ve mevcut testleri görmesini isteyin, sonra tek bir modülü değiştirin, ajan testleri çalıştırıp başarısızlıkları raporlasın, siz diff’i onaylayın, ardından bir sonraki adıma geçin. Bu yaklaşım, özellikle widget ağacının büyük olduğu projelerde geri dönüşü zor hataları önler.

Flutter projelerinde sık kullanılan görevler için örnek promptlar:

• lib/features/auth/presentation/login_screen.dart dosyasındaki formu Riverpod StateNotifier kullanacak şekilde yeniden düzenle; form doğrulamasını ayrı bir provider’a taşı.
• firebase_auth paketini pubspec.yaml’a ekle, AuthRepository arayüzünü domain katmanına yaz, implementasyonu data katmanına ekle ve mock testini güncelle.
• Mevcut widget testlerini çalıştır, başarısız olanları düzelt, sonra yeni eklediğin bileşen için bir widget testi yaz.
• MethodChannel ile batarya seviyesi okuma özelliğini ekle; Android ve iOS tarafı için platform sınıflarını güncelle, ardından flutter analyze çalıştır.
• Küçük bir refactor yap: tüm if (mounted) kontrollerini context.mounted ile değiştir, flutter analyze ve flutter test’ten geçtiğinden emin ol.

Her prompttan sonra ajanın çıktısını beklemeden diff’i gözden geçirin; Flutter’da tek bir satırlık bir widget değişikliği bile birçok testi etkileyebilir.

Cursor Agent’ın iyi yaptığı Flutter işleri ve dikkat edilecekler

Ajan en çok şu alanlarda verimli çalışır: mevcut widget’ların refactor edilmesi, state management geçişleri (örneğin setState’ten Riverpod’a), repository ve model katmanlarının şablonunu üretme, platform kanalı sarmalayıcıları yazma ve test dosyalarını güncelleme. Ancak dikkat edilmesi gereken noktalar da vardır:

Pitfall’lar: build_runner ile üretilen dosyalar ajan tarafından elle düzenlenirse tutarsızlık oluşur; bu yüzden generated dosyalara dokunmamasını kurala yazın. Asenkron kodda BuildContext kullanımı mounted kontrolü gerektirir; ajan bazen bunu atlar. Platform kanalı eklerken yalnızca Dart tarafını değil, android/app/src/main/... ve ios/Runner/... altındaki dosyaları da güncellemesi gerekir; ajan bunları gözden kaçırabilir. Golden testler piksel farklarına duyarlıdır; ajan yeni bir golden eklediğinde görüntüyü manuel inceleyin. Ayrıca ajan flutter pub add ile bağımlılık eklerken sürüm kısıtlamalarını yanlış yazabilir; pubspec.yaml’daki caret (^) kurallarını kontrol edin. Build_runner kullanıyorsanız ajan build_runner watch komutunu sonsuz döngüde çalıştırabilir; bunun yerine tek seferlik build komutunu isteyin.

Flutter’da ajanla test ve doğrulama

Ajan her değişiklikten sonra flutter analyze çalıştırmalıdır; siz de flutter test sonuçlarını inceleyin. Widget testleri için flutter test test/widget komutunu, birim testleri için flutter test test/unit komutunu kullanabilirsiniz. Entegrasyon testleri veya platform kanalı testleri gerekiyorsa ajanı bir emülatör veya cihaz bağlamında çalıştırmasını isteyin; ancak ajanın kendisi cihaz yönetimi yapmaz, siz flutter devices ile uygun cihazı seçmelisiniz. Değişiklikleri gözden geçirirken git diff çıktısını inceleyin; özellikle pubspec.yaml dosyasındaki sürüm değişikliklerini onaylayın. Ajan testleri güncellerken mevcut testleri bozabilir; bu yüzden her turda testlerin tamamını çalıştırmak yerine önce etkilenen dosyalarla ilgili testleri koşmak pratiktir. Ajan testleri çalıştırırken --coverage gibi ek parametreleri destekler; ancak coverage raporunu siz yorumlayın. Ajanın ürettiği testlerin assert’lerinin anlamlı olduğundan emin olun; bazen yalnızca widget’ın varlığını kontrol eden zayıf testler üretebilir.

Flutter projesinde birden fazla ajanı AgentVera ile yürütmek

AgentVera, Flutter projesinde aynı anda birden fazla Cursor Agent’ı ayrı gerçek terminal panellerinde çalıştırmanıza olanak tanır. Her ajan kendi git worktree’sinde çalışabildiği için biri state management refactor’u yaparken diğeri platform kanalı ekleyebilir ve dosyalar çakışmaz. Otomatik kod incelemesi, ajanın ürettiği widget veya provider değişikliklerini dosya:satır bağlantılarıyla gösterir; checkpoint özelliği ise hatalı bir refactor’u tek tıkla geri alıp oturumu adım adım yeniden oynatmanızı sağlar. Böylece Flutter’ın katmanlı yapısında paralel çalışmanın riskleri azalır. Cursor Agent ile paralel ajan kullanımı hakkında Paralel kodlama ajanları için en iyi araçlar (2026) sayfasına göz atabilirsiniz.

Sonuç

Cursor Agent, Flutter projelerinde terminalden çalışan, proje kurallarına saygı duyan ve test komutlarını kendisi koşabilen güçlü bir yardımcıdır. Başarılı kullanım, AGENTS.md dosyasının net olmasına, görevleri küçük parçalara bölmeye ve her turda analizör ile testleri çalıştırmaya bağlıdır. Bu pratikleri uyguladığınızda widget geliştirme, state management geçişleri ve platform kanalı işlerini güvenle ajan’a devredebilirsiniz.