# Gemini CLI ile FastAPI projelerinde hızlı kodlama

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

Gemini CLI ile FastAPI projelerinde GEMINI.md kurulumu, test döngüsü, tipik görevler ve yaygın tuzaklar. Pytest ve TestClient odaklı pratik rehber.

**Kısaca:**

- Gemini CLI, GEMINI.md talimatlarıyla FastAPI endpoint, Pydantic modeli ve bağımlılık değişikliklerini test odaklı yapar.
- TestClient ve pytest döngüsünü kurup diff incelemeden ajan çıktısını kabul etmeyin.
- Pydantic v2, dependency_overrides ve OpenAPI şeması en sık gözden kaçan noktalardır.

[Gemini CLI](/ajanlar/gemini-cli/) terminalde `gemini` komutuyla başlatılır ve proje kökündeki GEMINI.md talimatlarını okuyarak kod üretir. FastAPI projelerinde path operasyonları, Pydantic modelleri, bağımlılık enjeksiyonu ve async endpoint’ler üzerinde değişiklik yaparken testleri çalıştırıp hataları düzeltmesi için net bir çalışma döngüsü kurulabilir. Bu rehber, ajanı FastAPI’ye özgü kurallar ve doğrulama adımlarıyla verimli kullanmayı gösterir.

## Neden Gemini CLI FastAPI işine uygun

FastAPI projeleri çoğunlukla birbiriyle bağlantılı dosyalardan oluşur: router modülleri, Pydantic şemaları, bağımlılıklar ve testler. Gemini CLI, tek bir endpoint değişikliğinde bu dosyaları birlikte düzenleyebilir. Örneğin `GET /users` için sayfalama eklerken router, response modeli ve test dosyasını aynı oturumda güncelleyip tutarlı bir diff üretebilir.

Ajan ayrıca async/await yapılarını ve dependency injection akışını anlar. `Depends` ile bağlanan bir servisi yeniden adlandırırken veya bir endpoint’i sync’ten async’e çevirirken etkilenen tüm çağrıları gözden geçirebilir. Testleri kendi başına çalıştırıp kırmızı testleri düzeltmesi, FastAPI’nin hızlı deneme-yanılma döngüsüyle uyumludur. Bu sayede geliştirici daha çok iş mantığına ve API tasarımına odaklanabilir.

Gemini CLI, OpenAPI şemasındaki değişiklikleri de fark edebilir. Pydantic modeline eklenen bir alan response modeli olarak kullanıldığında şemanın güncellenmesi gerekir; ajan buna uygun test yazabilir veya mevcut testleri düzeltebilir. FastAPI’nin otomatik dokümantasyonu üzerindeki etkileri de kontrol edilir. Ancak bu tür değişikliklerde ajanın yalnızca istenen dosyaları değiştirdiğini doğrulamak gerekir.

## Proje kurulumu ve GEMINI.md

Proje kökünde `gemini` komutunu çalıştırmadan önce ([Gemini CLI nasıl kullanılır?](/blog/gemini-cli-nasil-kullanilir/) temel adımları anlatır) GEMINI.md dosyasını FastAPI’ye göre hazırlamak, ajanın doğru komutları ve klasör düzenini bilmesini sağlar. GEMINI.md kısa ve emir kipinde olmalı; proje dışı genel bilgiler yerine bu depoya özel kurallar içermelidir.

Aşağıdaki örnek, tipik bir FastAPI projesi için yeterli bir başlangıçtır:

```markdown
# FastAPI projesi talimatları

## Komutlar
- Test: `python -m pytest -q`
- Lint: `ruff check .`
- Format: `ruff format .`
- Geliştirme sunucusu: `uvicorn app.main:app --reload`

## Klasör düzeni
- `app/routers/`: path operasyonları
- `app/schemas/`: Pydantic modelleri
- `app/dependencies.py`: `Depends` ile kullanılan bağımlılıklar
- `tests/`: pytest dosyaları

## Kurallar
- Yeni endpoint eklerken TestClient ile en az başarılı ve hata durumu testi yaz.
- Pydantic v2 stillerini kullan; `orm_mode` yerine `from_attributes`.
- Endpoint'ler I/O içeriyorsa async tanımla ve blocking çağrıları `run_in_threadpool` ile sar.
- Yanıt modeli değiştiyse ilgili OpenAPI beklentilerini ve testleri güncelle.
```

Bu dosya sayesinde ajan, `pytest` çıktısını nasıl yorumlayacağını ve hangi klasörlerde değişiklik yapması gerektiğini bilir. GEMINI.md’yi güncel tutmak, özellikle bağımlılık yönetimi veya test komutu değiştiğinde kritik olur. Ajanın yanlış komut çalıştırmasını önlemek için test ve lint komutlarını her zaman aynı satırda tutun.

Ayrıca GEMINI.md’ye veritabanı bağlantısı veya ortam değişkenleriyle ilgili not ekleyin. Örneğin testlerin gerçek veritabanına değil, in-memory bir SQLite veya mock bağımlılıklara karşı çalışması gerektiğini belirtin. Böylece ajan yanlışlıkla canlı servise istek atan testler üretmez. Dosya kısa kaldığı sürece ajanın yönergeleri takip etme olasılığı artar.

## Çalışma döngüsü ve örnek promptlar

Ajanla çalışırken planla, küçük adımlar at, testleri çalıştır, diff’i incele döngüsünü tekrarlamak en sağlam yoldur. Önce istenen değişikliği tek bir cümleyle sınırlandırın; ajan büyük bir yeniden yapılandırmaya girişirse durdurun ve daha küçük bir görev verin. Her adımdan sonra `git diff` ile değişiklikleri inceleyin; testleri mutlaka çalıştırın.

[Kodlama ajanları için prompt nasıl yazılır?](/blog/kodlama-ajanlari-icin-prompt-yazmak/) rehberindeki kalıplar da işe yarar. FastAPI projelerinde sık kullanılan örnek promptlar:

- `app/routers/items.py` içindeki `POST /items` endpoint’ine `ItemCreate` modeline göre 201 yanıtı ve 422 doğrulama hatası testlerini yaz, ardından testleri çalıştır.
- `GET /users` endpoint’ine `limit` ve `offset` sorgu parametreleri ekle; response modelini `UserList` olarak güncelle, TestClient testini ekle.
- Bağımlılık enjeksiyonundaki `get_db` fonksiyonunu async hale getir; etkilenen tüm endpoint’leri ve testleri güncelle.
- Pydantic `UserUpdate` modelindeki `email` alanına `EmailStr` doğrulaması ekle; mevcut testler kırılırsa düzelt.
- `app/main.py` içindeki CORS ayarlarını env değişkeninden okuyacak şekilde düzenle; ilgili testi yaz.

Bu promptlarda istenen dosya ve beklenen davranış açıkça yazılır; ajanın kendi başına mimari karar vermesi gerekmez. Ajan bir adımı bitirdiğinde önce `python -m pytest -q` çalıştırın, sonra diff’i okuyun ve sadece istenen satırların değiştiğinden emin olun. Eğer diff beklenenden büyükse ajanı durdurup önceki adımı geri alın ve daha dar bir talimat verin.

Prompt yazarken önce bağlamı verin: hangi router, hangi model, hangi test dosyası. Sonra beklenen davranışı ve test kapsamını söyleyin. Son olarak ajanın çalıştırması gereken doğrulama komutunu ekleyin. Bu üçlü yapı çoğu FastAPI görevinde tutarlı sonuç verir.

## FastAPI’de iyi olduğu ve dikkat edilmesi gereken noktalar

Aşağıdaki tablo, ajanın güçlü olduğu alanları ve tipik tuzakları özetler.

| Alan | Güçlü olduğu iş | Dikkat edilecek nokta |
|------|------------------|------------------------|
| Path operasyonları | Yeni endpoint ekleme, parametre doğrulama, status code düzenleme | Yanlış HTTP fiili veya eksik `response_model` |
| Pydantic modelleri | Alan doğrulama, `EmailStr`, v2 geçişi | `orm_mode` yerine yanlışlıkla v1 stillerini kullanma |
| Bağımlılık enjeksiyonu | `Depends` zincirini yeniden adlandırma, async bağımlılık | Testlerde `dependency_overrides` kullanmayı unutma |
| Testler | TestClient ile parametreli test yazma | Sadece başarı durumunu test edip 422 veya 404’ü atlama |

Ajan özellikle Pydantic v2 ve v1 arasındaki farklarda karışabilir. Örneğin `ConfigDict(from_attributes=True)` yerine eski `orm_mode` kullanabilir; bu yüzden GEMINI.md’ye net kural eklemek faydalıdır. Ayrıca TestClient senkron bir arayüz sunduğu için async endpoint’leri sanki sync gibi test edebilir; ancak ajan bazen gerçek event loop davranışını gözden kaçırabilir. Bağımlılık geçersiz kılma (`app.dependency_overrides`) kullanılmadığında testler gerçek veritabanına bağlanmaya çalışabilir; bu, en sık görülen hatadır.

Bir diğer sık hata, ajanın yanıt modeli olmadan bir sözlük dönen endpoint yazmasıdır. FastAPI bu durumda OpenAPI şemasında alanları gösteremez; testler geçse bile API dokümanı eksik kalır. Yeni endpoint eklerken her zaman `response_model` ve doğru status code kullanılmasını isteyin. Ayrıca path parametrelerinde tip dönüşümü ve validasyon kuralları ajan tarafından atlanabilir; `Path` sınıfı ile sınırlar eklemek gerektiğini belirtmek iyi olur.

## Test ve doğrulama

Ajanın ürettiği kodu kabul etmeden önce her zaman `python -m pytest -q` çalıştırın. Testler geçtikten sonra `TestClient` ile yazılan testlerin hem başarılı hem de hata durumlarını kapsadığını kontrol edin. Özellikle yeni bir endpoint eklendiğinde 201, 400/422 ve 404 senaryoları birlikte istenmelidir.

Ajanın kendi testlerini de gözden geçirin. Testler sadece mutlu yolu kontrol ediyorsa gerçek kullanımda sorun çıkar. Ayrıca OpenAPI şemasındaki beklenmedik değişiklikleri `git diff` ile inceleyin; `response_model` eklenmeden dönen fazladan alanlar veya eksik `status_code` fark edilmeyebilir. Testleri çalıştırmadan önce `app/main.py` içindeki lifespan veya middleware değişikliklerinin TestClient davranışını etkilemediğini doğrulayın.

Doğrulama adımlarını ajanın kendisine de yaptırabilirsiniz: "Testleri çalıştır, başarısız olanları listele ve düzelt" gibi bir prompt, ajanın kendi hatasını bulmasını sağlar. Ancak son onay her zaman geliştiricide olmalıdır. CI ortamında çalışacak ek kontroller (örneğin `ruff check` ve `mypy`) için ajanın ilgili komutları bilmesi gerekir; bu komutları GEMINI.md’de bulundurun.

## AgentVera ile birden çok ajan

FastAPI projelerinde birden çok Gemini CLI oturumunu tek pencerede yönetmek için AgentVera kullanılabilir. Her ajan kendi git worktree’sinde çalıştığı için ayrı router veya servis dosyaları üzerinde paralel değişiklik yaparken birbirlerinin dosyalarını ezmez. Otomatik kod incelemesi, endpoint veya Pydantic modeli hatalarını satır bazında gösterir. Checkpoint’ler endpoint davranışını bozan bir değişikliği tek tıkla geri almayı sağlar. Token bütçeleri ise ajanın tüm FastAPI projesini kontrolsüzce yeniden yapılandırmasını engeller.

## Kapanış

Gemini CLI, FastAPI projelerinde test odaklı ve küçük adımlı çalıştığınızda ciddi hız kazandırır. GEMINI.md dosyasını net tutmak, ajanın yanlış Pydantic veya test desenlerine kaymasını azaltır. Değişiklikleri her zaman pytest ve diff ile doğrulayın; birden çok ajan gerektiğinde worktree ve checkpoint imkânlarıyla çakışmayı ve geri dönüşü yönetin.

## Sık sorulanlar

**Gemini CLI FastAPI projesinde nasıl çalıştırılır?** Proje kökünde terminalden gemini komutunu çalıştırın. Ajan GEMINI.md dosyasındaki komutları ve kuralları okuyarak kod üretir; siz de pytest çıktısını ve diff’i inceleyerek yönlendirirsiniz.

**GEMINI.md dosyasına FastAPI için neler yazmalıyım?** Test, lint ve geliştirme sunucusu komutlarını, klasör düzenini ve Pydantic v2, async endpoint, dependency injection kurallarını yazın. Örnekler yukarıdaki rehberde mevcuttur.

**Gemini CLI FastAPI endpoint’lerini test edebilir mi?** Evet, TestClient ile test yazıp çalıştırabilir. Ancak testlerin başarılı ve hata durumlarını kapsadığını, dependency_overrides kullanıldığını doğrulamalısınız.

**Gemini CLI çok dosyalı FastAPI projelerinde güvenli mi?** Küçük adımlarla çalışırsanız güvenlidir. Her değişiklikten sonra git diff ve pytest ile doğrulayın; büyük yeniden yapılandırmalarda ajanı sınırlandırın.

---

**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/