Cursor Agent, bir Flask projesinde proje kökünde cursor-agent komutuyla başlatıldığında AGENTS.md ve .cursor/rules dosyalarındaki proje talimatlarını okuyarak çalışır. Bu rehber; blueprint, application factory, Jinja, SQLAlchemy ve pytest kullanan bir Flask projesinde ajanı test ve diff odaklı bir iş ortağı gibi kullanmayı anlatır. Amaç, ajanı kontrolsüz kod üreticisi olarak değil, küçük ve doğrulanabilir adımlarla yönetmektir. Cursor Agent sayfası temel kullanım için iyi bir başlangıçtır.
Cursor Agent Flask projelerinde neden iyi çalışır?
Flask’ın açık yapısı, route’ların görünürlüğü ve blueprint’lerin küçük dosyalara bölünmesi ajanın bağlamı kolay okumasını sağlar. Agent, create_app içindeki kayıt sırasını gördüğünde yeni blueprint’i nereye ekleyeceğini kolayca planlar. SQLAlchemy modelleri de genellikle tek dosyada veya model paketinde olduğu için agent küçük model değişikliklerini güvenle yapar. Jinja şablonlarında döngü, koşul ve include işlemleri basit olduğundan agent şablon görevlerinde hızlıdır. En önemlisi, Flask’ın test client’i ve pytest fixture’ları agent’ın yazdığı kodu anında doğrulamasına izin verir; böylece her adımda gerçek bir çalışan sonuç elde edilir.
Projeyi ajan için hazırlamak
Agent’ın proje kurallarını bilmesi için proje köküne AGENTS.md koymak en pratik yoldur; .cursor/rules klasörü de aynı işi görür. Dosya kısa olmalı; komutlar, klasör yapısı ve Flask’a özgü kurallar bulunmalı. Gereksiz açıklamalar bağlam penceresini doldurur. Komut satırı ajanının genel kullanımı için Cursor CLI nasıl kullanılır? Adım adım rehber yazısına bakabilirsiniz.
Örnek AGENTS.md:
# AGENTS.md
## Komutlar
- Çalıştır: `flask --app app:create_app run --debug`
- Test: `pytest -q`
- Lint: `ruff check .`
- Format: `black .`
## Klasör düzeni
- `app/` application factory ve blueprint'ler
- `app/blueprints/` her blueprint kendi klasöründe, `routes.py` şart
- `app/models.py` SQLAlchemy modelleri
- `app/templates/` Jinja şablonları
- `tests/` pytest testleri
## Flask kuralları
- Yeni blueprint eklerken `app/blueprints/<ad>/__init__.py` ve `routes.py` oluştur; `create_app` içinde `app.register_blueprint` ile kaydet.
- SQLAlchemy modellerini `app/models.py` içinde tanımla; dairesel import yaratma.
- Jinja şablonlarında iş mantığı yazma; özel filtreler `app/template_filters.py` içinde `app.jinja_env.filters` ile kaydedilsin.
- View fonksiyonları dışında `request`, `session` veya `g` kullanma; test client fixture'ları `tests/conftest.py` içinde olsun.
- Form doğrulama için Flask-WTF kullan; hata mesajları Türkçe olabilir.Bu dosyayı agent her görevde okuyacağı için ‘yeni blueprint ekle’ dediğinizde doğru klasörü ve kayıt adımını bilir.
Çalışma döngüsü: plan, küçük adımlar, test, diff
Agent ile verimli çalışmanın anahtarı tek seferde büyük bir refactor istemek değil, görevi sıralı parçalara bölmektir. Şu döngüyü izleyin:
- Görevi tek bir blueprint, tek model alanı veya tek şablon değişikliği olacak şekilde tarif edin.
- Agent’tan önce dosyayı okumasını değil, doğrudan ‘şu dosyayı aç, şu değişikliği yap, testleri çalıştır’ demesini isteyin; böylece bağlam gereksiz uzamaz.
- Agent işini bitirdiğinde
pytest -qçalıştırın veya agent’ın kendi çalıştırdığı test çıktısını inceleyin. git diffile değişiklikleri satır satır gözden geçirin; özellikle import sırası, blueprint kaydı ve context kullanımına bakın.- Hata varsa traceback’i olduğu gibi agent’a yapıştırın; ‘test düzelt’ gibi bulanık ifadeler yerine hatanın hangi testte ve hangi satırda olduğunu söyleyin.
Örnek promptlar:
app/blueprints/authaltına login ve logout view’larını ekle;Usermodelini SQLAlchemy ile kullan, form Flask-WTF olsun.tests/test_auth.pyiçinde başarılı giriş ve hatalı şifre testlerini yaz,pytest tests/test_auth.py -qçalıştır.app/models.pyiçindekiOrdermodelinestatusalanı ekle, Alembic migration oluştur. Migration dosyasınımigrations/versionsaltına yaz,flask db upgradesonrasıpytest -qçalıştır.app/templates/products/list.htmlşablonunuapp/blueprints/products/routes.pyiçindeki pagination nesnesine göre güncelle; boş durumda_empty.htmlpartial’ını include et.app/__init__.pyiçindekicreate_appfonksiyonuna test config desteği ekle;tests/conftest.pyiçindeclientfixture’ı yaz vepytest tests/test_app.py -qile doğrula.app/blueprints/apialtındaki JSON hata dönüşlerini tutarlı hale getir;errorhandlerkullan vetests/test_api.pyiçinde 404 ve 500 için test yaz.
Bu tür promptlar ajanı tek sorumluğa odaklar ve diff’i küçük tutar.
Hangi Flask görevleri ajanın elinde güvenli, nerelerde dikkat etmeli
Ajan en çok şu işlerde rahat çalışır: yeni blueprint şablonu oluşturma, basit CRUD view’ları, Jinja şablonlarında döngü ve include, pytest ile test client kurulumu, SQLAlchemy modeline alan ekleme. Buna karşılık, Flask’a özgü birkaç alan dikkat gerektirir.
| Konu | Ajanın genelde iyi yaptığı | Ajanın sık gözden kaçırdığı |
|---|---|---|
| Blueprint | Blueprint nesnesi ve route decorator’ları | url_prefix, create_app içinde register_blueprint çağrısı |
| Application factory | create_app fonksiyonuna config veya extension ekleme | Import sırası, dairesel import oluşması |
| SQLAlchemy | Modele kolon ekleme, basit query yazma | db.session.commit() ve rollback, lazy loading |
| Jinja | for, if, extends, include | Kullanıcı girdisinin autoescaping dışında kalması |
| pytest | client fixture’ı, basit assertion’lar | Uygulama context’i, test sonrası veritabanı temizliği |
Özellikle application factory kullanıyorsanız ajanın yeni bir blueprint eklerken app/__init__.py içindeki create_app fonksiyonuna kayıt satırını eklediğini doğrulayın. SQLAlchemy’de ise session’ın request sonunda kapatıldığından emin olun; ajan bazen db.session.remove() adımını atlar. Alembic migration’larda ajan dosya oluşturabilir ama down_revision zincirini bozmaması için diff’i inceleyin.
Flask ile test ve doğrulama
Flask’ın test client’i, ajanın yazdığı kodu hızlı doğrulamak için idealdir. tests/conftest.py içinde uygulama factory’den test client üreten bir fixture bulundurmak hem sizin hem ajanın işini kolaylaştırır. Agent’tan her değişiklikten sonra pytest -q çalıştırmasını ve çıktıyı raporlamasını isteyin. Test kırılırsa traceback’i aynen verin; ajan genellikle hatayı kendi başına bulur ama bulanık ‘düzelt’ komutuyla yanlış yere müdahale edebilir.
Doğrulama sırası şöyle olabilir: önce birim testleri (tests/test_models.py), sonra view testleri (tests/test_blueprints.py), en sonda entegrasyon senaryoları. Agent’tan yalnızca test yazmasını değil, testin geçtiğini terminal çıktısıyla göstermesini isteyin. Ayrıca git diff --check gibi basit kontrollerle boşluk hatalarını yakalayabilirsiniz; Flask’ta bir import hatası tüm uygulamayı çökertebilir, bu yüzden diff’te from app.models import ... satırlarına ayrıca bakın. Güvenli iş akışı için Vibe coding nasıl yapılır? Güvenli bir iş akışı yazısındaki kontrol listesine göz atabilirsiniz.
Flask projesinde birden fazla agent: AgentVera
Flask projesinde blueprint, model ve ön yüz değişikliklerini paralel yürütmek isterseniz AgentVera, Cursor Agent dahil komut satırı ajanlarını tek pencerede kendi gerçek terminallerinde yan yana çalıştırır. Her agent kendi git worktree’sinde çalışabildiği için dosyalar birbirini ezmez; biri auth blueprint’ini, diğeri Order modelini aynı anda güvenle değiştirebilir. Bir tur bittiğinde ikinci model kodu otomatik inceler ve bulguları dosya:satır olarak işaretler; import sırası veya blueprint kaydı hataları hızla görünür. Checkpoint’ler sayesinde hatalı bir migration veya refactor tek tıkla geri alınabilir. Token bütçeleri de uzun test döngülerinde ajanın kontrolden çıkmasını önler.
Kapanış
Cursor Agent, Flask projesinde doğru talimatlar ve küçük adımlarla yönetildiğinde blueprint, model, şablon ve test işlerini ciddi biçimde hızlandırır. Önemli olan AGENTS.md dosyasını güncel tutmak, her turu test ve diff ile kapatmak ve Flask’a özgü tehlikeli noktaları elden geçirmektir. Böylece ajan, sürekli kontrol edilen bir kod üreticisi değil, projeye hâkim bir iş ortağı gibi davranır.