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? 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:
# 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? rehberindeki kalıplar da işe yarar. FastAPI projelerinde sık kullanılan örnek promptlar:
app/routers/items.pyiçindekiPOST /itemsendpoint’ineItemCreatemodeline göre 201 yanıtı ve 422 doğrulama hatası testlerini yaz, ardından testleri çalıştır.GET /usersendpoint’inelimitveoffsetsorgu parametreleri ekle; response modeliniUserListolarak güncelle, TestClient testini ekle.- Bağımlılık enjeksiyonundaki
get_dbfonksiyonunu async hale getir; etkilenen tüm endpoint’leri ve testleri güncelle. - Pydantic
UserUpdatemodelindekiemailalanınaEmailStrdoğrulaması ekle; mevcut testler kırılırsa düzelt. app/main.pyiç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.