# Gemini CLI ile Flask Projesi Geliştirme Rehberi

Adres: https://agentvera.dev/blog/gemini-cli-ile-flask/ · Yayın: 2026-11-01

Gemini CLI’yı Flask projelerinde GEMINI.md, blueprint, application factory, Jinja, SQLAlchemy ve pytest ile pratik olarak adım adım öğrenin.

**Kısaca:**

- Gemini CLI, GEMINI.md ile blueprint ve application factory kurallarını okuyunca Flask projelerinde tutarlı kod üretir; her adımda pytest çalıştırmak hataları erken yakalar.
- Ajanın Flask’ta en sık hata yaptığı yerler döngüsel import, uygulama bağlamı ve SQLAlchemy lazy load’tır; diff’i ve testleri mutlaka inceleyin.
- Birden çok Gemini CLI ajanını git worktree ve checkpoint destekli bir ortamda paralel çalıştırmak, Flask geliştirmeyi hızlandırır ama kod incelemesi şarttır.

[Gemini CLI](/ajanlar/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](/blog/gemini-cli-nasil-kullanilir/) 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](/blog/kodlama-ajanlari-icin-prompt-yazmak/) rehberine göz atabilirsiniz.

- `app/auth/routes.py` iç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/orders` blueprint’ini application factory’ye kaydet; `/orders` listesi için SQLAlchemy sorgusunu route içinde yap, Jinja şablonunu oluştur ve pytest ile iki test ekle.
- `app/extensions.py` üzerindeki `db` nesnesini kullanarak kullanıcı-rol ilişkisini modelleyen SQLAlchemy değişikliğini yap; mevcut testleri bozma.
- `tests/conftest.py` içinde uygulama fabrikası kullanan bir `client` fixture’ı 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 `|safe` kullanı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 `|safe` ekler |
| 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](/blog/windowsta-kodlama-ajanlari/) 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.

## Sık sorulanlar

**Gemini CLI Flask projesinde nasıl başlatılır?** Terminalde proje klasörüne gidip gemini yazmanız yeterlidir. GEMINI.md dosyası varsa ajan otomatik okur; proje komutlarını orada tutmak doğru test ve lint komutlarını kullanmasını sağlar.

**Gemini CLI Flask için GEMINI.md dosyasına ne yazılmalı?** Blueprint yapısı, application factory (create_app), test ve lint komutları, klasör düzeni, current_app kullanımı ve SQLAlchemy kuralları gibi projeye özel talimatlar yazılmalıdır. Dosyanın kısa ve net olması ajanın kural atlamasını azaltır.

**Gemini CLI Flask’ta döngüsel import hatalarını çözebilir mi?** Evet, çoğu zaman çözebilir ama diff’i incelemek gerekir. GEMINI.md’ye modül seviyesinde app import etmeme kuralı koymak ve ajanın extensions.py ile current_app kullanmasını istemek hataları azaltır.

**Gemini CLI ile Flask pytest testleri yazdırabilir miyim?** Evet, application factory ve app.test_client() fixture’ları kullanarak test üretir. Ancak testlerin gerçekten geçtiğini kendiniz pytest -q ile doğrulamalı ve SQLAlchemy temizliğini kontrol etmelisiniz.

---

**AgentVera hakkında.** AgentVera, Solviera Teknoloji tarafından geliştirilen macOS, Windows ve Linux masaüstü uygulamasıdır. 18 yapay zeka kodlama ajanını (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) proje bazında, gerçek terminallerde ve kullanıcının kendi CLI kurulum ve girişleriyle yan yana çalıştırır. Ücretsiz planda sınırsız ajan vardır. İndir: https://agentvera.dev/indir/ · Fiyatlar: https://agentvera.dev/fiyatlar/