Gemini CLI’yi Flask projenizde terminalden gemini komutuyla başlatıp GEMINI.md ile blueprint, application factory, Jinja, SQLAlchemy ve pytest kurallarını verirseniz, ajan bağlamı bilerek çalışır. Bu rehberde kurulum, çalışma döngüsü, tipik görevler ve test doğrulama adımlarını Flask’a özel olarak anlatıyorum.
Gemini CLI neden Flask işine uyar
Flask, katı bir yapı dayatmadığı için ajanın doğru desenleri kavraması projeden projeye değişir. GEMINI.md ile blueprint ve application factory kurallarını açıkça verdiğinizde Gemini CLI, route eklerken mevcut url_for isimlerini korur, yeni blueprint’leri create_app içine doğru sırayla kaydeder ve Jinja şablonlarında yalnızca route bağlamındaki değişkenleri kullanır. SQLAlchemy tarafında oturum yönetimini ve ilişki yüklemelerini bilir; pytest tarafında ise app.test_client() fixture’larıyla test yazabilir. Bu da Flask projelerinde tekrarlayan işlerin çoğunu güvenle devredebileceğiniz anlamına gelir.
Örneğin bir e-ticaret projesinde sipariş listesi endpoint’i eklemek istediğinizde ajan, mevcut blueprint yapısına uygun bir orders.py oluşturabilir, url_prefix değerini projedeki diğer blueprint’lerden öğrenir, SQLAlchemy sorgusunu route içinde yazar ve şablona yalnızca gereken verileri geçirir. Aynı işi elle yaptığınızda birkaç dosyayı elle açmanız gerekir; Gemini CLI bunu tek istekte toplar. Ancak bunun çalışması için proje kurallarının ajan tarafından net görülmesi şarttır. İşte bu yüzden GEMINI.md hazırlığı kritiktir.
Flask projesini ajan için hazırlama
Reponun köküne GEMINI.md ekleyin. gemini komutu bu dosyayı otomatik okur; ekstra bayrak vermeniz gerekmez. Genel kurulum için Gemini CLI nasıl kullanılır? Adım adım rehber sayfasına bakabilirsiniz; burada doğrudan Flask projesine odaklanıyorum. Dosyanın kısa ve net olması önemli; ajan uzun anlatımlarda önemli kuralı atlayabilir.
# GEMINI.md
## Proje komutları
- Kurulum: python -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt
- Çalıştırma: export FLASK_APP=run.py && flask run --debug
- Test: pytest -q
- Lint: ruff check .
- Format kontrolü: ruff format --check .
## Klasör düzeni
- app/__init__.py: create_app application factory
- app/extensions.py: db, migrate gibi eklentiler
- app/blueprints/: her blueprint ayrı klasörde
- app/templates/ ve app/static/
- tests/: pytest testleri, conftest.py fixture'ları burada
## Flask kuralları
- Modül seviyesinde `from app import create_app` yapma; döngüsel import çıkar.
- Route içinde `current_app`, `db` gibi nesneleri import etmeden kullan.
- Blueprint route'larında `url_for('blueprint.endpoint')` isimlerini koru.
- SQLAlchemy sorgularını şablonda değil route içinde çöz.
- Testler application factory üzerinden `app.test_client()` kullansın.Bu örnek, ajanın doğru test ve lint komutlarını kullanmasını, klasör beklentilerini bilmesini ve Flask’a özgü tuzaklardan kaçınmasını sağlar. GEMINI.md’yi model değişikliklerinde veya yeni blueprint eklendiğinde güncel tutun. Ayrıca GEMINI.md içine Python sürümü ve bağımlılık yönetimi ile ilgili notlar da ekleyebilirsiniz; örneğin pip freeze yerine requirements.txt kullanıldığını belirtmek ajanın yanlış paket yüklemesini engeller. Dosyayı çok uzatmaktan kaçının; 30–50 satır ideal ölçüdür. Ajan her istekte bu dosyayı bağlam olarak işler, bu yüzden güncel olmayan bilgiler hatalı kod üretimine yol açar.
Çalışma döngüsü ve örnek komutlar
Çalışma şu döngüde ilerler: önce ajanın neyi değiştireceğini küçük bir adım olarak planlayın, sonra gemini içinde o adımı isteyin, değişiklikten sonra pytest -q ve ruff check . çalıştırın, en son git diff ile üretilen kodu satır satır inceleyin. Flask projelerinde tek seferde çok fazla blueprint veya model değişikliği istemek yerine her seferinde bir katmanı hedefleyin. Daha etkili istekler için kodlama ajanları için prompt nasıl yazılır rehberine göz atabilirsiniz.
app/auth/routes.pyiçindeki giriş endpoint’ini blueprint’e uygun şekilde düzenle;url_for('auth.login')kullanan tüm dosyaları kontrol et ve gerekirse güncelle.- Yeni
app/ordersblueprint’ini application factory’ye kaydet;/orderslistesi için SQLAlchemy sorgusunu route içinde yap, Jinja şablonunu oluştur ve pytest ile iki test ekle. app/extensions.pyüzerindekidbnesnesini kullanarak kullanıcı-rol ilişkisini modelleyen SQLAlchemy değişikliğini yap; mevcut testleri bozma.tests/conftest.pyiçinde uygulama fabrikası kullanan birclientfixture’ı yaz ve tüm testlerin bu fixture’ı kullanmasını sağla.- Jinja şablonlarındaki form alanlarını CSRF ve otomatik kaçış açısından incele; güvenli olmayan
|safekullanımlarını raporla.
Bu istekleri verirken her zaman beklenen dosya ve davranışı açıkça yazın. Örneğin “application factory’ye kaydet” demek yerine “app/init.py içindeki create_app fonksiyonunda app.register_blueprint çağrısını ekle” demek daha kesin sonuç verir. Ajanın bir seferde yaptığı işi küçük tutmak, diff incelemesini kolaylaştırır ve geri almayı ucuzlaştırır. Çalışma döngüsünde git commit’lerini her adımdan sonra atmayı alışkanlık haline getirin; böylece ajanın yanlış bir değişikliğini izole edebilirsiniz.
İyi gittiği işler ve dikkat edilecek yerler
Gemini CLI, tekrar eden Flask işlerinde iyidir: blueprint ayırma, test üretme, SQLAlchemy ilişkilerini düzeltme, Jinja şablonlarını yeniden düzenleme. Ancak aşağıdaki tabloda sık görülen hataları diff aşamasında yakalamanız gerekir.
| Bileşen | Dikkat edilecek tipik hata |
|---|---|
app/__init__.py | Ajan bazen create_app içine modül seviyesinde import yazar; döngüsel import oluşur |
| Blueprint route’ları | Uç nokta adını değiştirip şablonlardaki url_for bağlantılarını bozar |
| Jinja şablonları | İş mantığını veya sorguyu şablona taşır; gereksiz ` |
| SQLAlchemy modelleri | Lazy load ilişkilerini şablonda tetikler; N+1 sorgu üretir |
| pytest fixture’ları | Global app nesnesi kullanır; app.test_client() yerine yanlış bağlam kurar |
Bunların dışında Flask’a özgü üç noktaya özellikle dikkat edin: döngüsel import, uygulama bağlamı ve request sonrası SQLAlchemy oturumunun kapanması. Ajan bazen db.session.remove() çağrısını unutabilir; bu da testlerde kirliliğe yol açar. Blueprint kayıt sırasını değiştirirse url_for hataları çıkabilir; her değişiklikten sonra Flask uygulamasını gerçekten başlatıp kritik route’ları elle test edin.
Özellikle şablonlarda {{ user.orders }} gibi lazy load ifadeleri ajan tarafından sıkça üretilir. Bu, template render sırasında DB sorgusuna neden olur ve performans düşer; ayrıca request bitince oturum kapandığı için hata da verebilir. Bu yüzden GEMINI.md’ye “ilişkileri route içinde joinedload veya selectinload ile yükle” kuralını eklemek faydalıdır. Ajan bu tür ince ayrıntıları kendiliğinden bilemeyebilir; diff incelemesi sırasında lazy='joined' gibi model değişikliklerini aramalısınız. Bir diğer yaygın hata, create_app içinde app.config['SECRET_KEY'] atamasını unutup session kullanımında hata alınmasıdır; bu da testlerde ortaya çıkar.
Flask’ta test ve doğrulama
Ajanın ürettiği her değişiklikten sonra testleri siz çalıştırın; ajanın söylediği başarılı sonuç yeterli değildir. pytest -q komutu hızlı geri bildirim verir; ruff check . stil hatalarını yakalar. Flask testlerinde conftest.py içinde application factory kullanan bir client fixture’ı tanımlayın ve her testin bu fixture’ı kullanmasını isteyin. SQLAlchemy ile çalışırken test başına geçici bir veritabanı kullanmak en temiz yoldur; ajanın db.create_all() ve db.drop_all() çağrılarını fixture içine yerleştirdiğinden emin olun. Son olarak git diff üzerinde yalnızca beklenen dosyaların değiştiğini doğrulayın; beklenmedik bir app/__init__.py değişikliği neredeyse her zaman döngüsel import habercisidir.
Testlerin kapsamını yalnızca route düzeyinde tutmayın; ajanın ürettiği SQLAlchemy sorguları için basit bir model testi de eklemesini isteyin. Örneğin User.query.filter_by(email=...).first() çağrısının doğru sonuç döndürdüğünü doğrulayan bir pytest testi, ilişki hatalarını erken ortaya çıkarır. Test veritabanı olarak SQLite in-memory kullanılabilir; ancak production PostgreSQL davranışlarını taklit etmese de döngüsel import ve bağlam hatalarını yakalamak için yeterlidir. Ajanın testlerini çalıştırmadan önce conftest.py dosyasının sys.path eklemeleri yapmadığından emin olun; bu tür hack’ler ajan tarafından önerilebilir. Bunun yerine paket yapınızı doğru kurun ve pip install -e . kullanın. Ajanın test için monkeypatch kullanması normaldir; ancak app nesnesini global değiştirmesine izin vermeyin. Her testin kendi uygulama örneğini yaratması en güvenlisidir.
Aynı Flask projesinde birden çok ajan: AgentVera
Birden çok Gemini CLI ajanını aynı Flask projesinde paralel çalıştırmak istediğinizde AgentVera’nın gerçek terminal panelleri işe yarar; her ajan kendi git worktree’sinde çalıştığı için biri app/auth üzerinde değişiklik yaparken diğeri app/orders blueprint’ini güvenle geliştirebilir. Ajan turu bittiğinde ikinci bir model kod incelemesi yapar ve Flask’ta sık görülen döngüsel import veya yanlış current_app kullanımını dosya:satır olarak işaretler. Checkpoint sayesinde hatalı bir create_app değişikliği tek tıkla geri alınır; token bütçesi ise ajanın kontrolden çıkmasını önler. Windows’ta bu akışla ilgili paralel ajanlar rehberine bakabilirsiniz.
Bu yaklaşım özellikle birden fazla blueprint üzerinde aynı anda çalışırken faydalıdır; ancak her ajanın GEMINI.md dosyasını aynı sürümde gördüğünden emin olun. Git worktree kullanmak, ana dalın stabil kalmasını sağlar; ajanlar kendi dalında çalışır ve merge sırasında çakışmalar daha kolay çözülür. Kod incelemesi modeli, Flask’a özgü kuralları bilerek url_for endpoint isimlerinin tutarlılığını ve db.session kullanımını kontrol edebilir. Token bütçesi ajanın uzun süre takılmasını engeller, böylece tek bir blueprint’te sonsuz döngüye girmez.
Sonuç
Gemini CLI, doğru GEMINI.md ve test disipliniyle Flask projelerinde blueprint, Jinja, SQLAlchemy ve pytest işlerinin çoğunu güvenilir şekilde yürütür. Yine de ajanın ürettiği her diff’i Flask’a özgü riskler açısından incelemek ve birden çok ajanı kontrollü bir ortamda çalıştırmak gerekir. Küçük adımlarla ilerleyip testleri hep siz çalıştırırsanız, Gemini CLI Flask geliştirme hızınızı ciddi şekilde artırır.