# Gemini CLI ile Python projelerinde kodlama rehberi

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

Python projelerinde Gemini CLI kurulumu, GEMINI.md yapılandırması, sanal ortam, pytest, ruff ve mypy ile güvenli çalışma döngüsü. Test ve tip kontrolü ipuçları.

**Kısaca:**

- Gemini CLI, Python projelerinde GEMINI.md’deki komutlarla sanal ortamı, pytest, ruff ve mypy’yi çalıştırarak kod geliştirmeyi hızlandırır.
- Küçük adımlarla çalışıp her değişiklikten sonra test, tip ve lint kontrollerini yapmak Python hatalarını erken yakalar.
- AgentVera ile ayrı git worktree’lerde paralel ajanlar çalıştırıp otomatik kod incelemesiyle Python projesini güvenle yönetebilirsiniz.

Python projenizde terminalde `gemini` komutuyla [Gemini CLI](/ajanlar/gemini-cli/)'yi başlatabilirsiniz. Ajan, proje klasöründeki GEMINI.md dosyasını okur; orada tanımlı sanal ortam, test, lint ve tip kontrolü komutlarını kullanarak doğrudan kodunuz üzerinde çalışır. Bu rehber, GEMINI.md yapılandırmasından güvenli çalışma döngüsüne ve paralel ajan kullanımına kadar Python projesi için pratik bilgileri içerir.

## Gemini CLI Python işleri için neden uygundur

Gemini CLI, proje dizininde çalışan bir terminal ajanı olduğu için Python’un dosya yapısını, import mekanizmasını ve araç zincirini doğrudan kullanır. `pyproject.toml` içindeki bağımlılıkları, `pytest` konfigürasyonunu, `ruff` ve `mypy` ayarlarını tek komutla değerlendirip eksik tip, bozuk import veya lint hatasını anında raporlar. Sanal ortamda çalıştığında Python sürüm uyuşmazlıklarını önler; bu da özellikle birden çok projede geçiş yapan geliştiriciler için kritik bir avantajdır. Ajanın GEMINI.md üzerinden komutları bilmesi, her seferinde `activate` veya `pip install` adımlarını elle anlatma yükünü ortadan kaldırır. Sonuç olarak kod üretimi, test döngüsü ve kalite kontrolleri tek bir terminal bağlamında birleşir.

## Python projesini ajan için hazırlama ve GEMINI.md

Kök dizinde GEMINI.md oluşturup projeye özel komutları ve kuralları yazın. Dosya kısa ve kesin olmalı; ajan her turda okuyacaktır. Aşağıdaki örnek, sanal ortamı, kurulumu, test, lint ve tip kontrolünü tek blokta tanımlar:

```markdown
# Proje: siparis-api

## Ortam
- Python 3.12, sanal ortam: `.venv`
- Kurulum: `python -m venv .venv && .venv/bin/pip install -e '.[dev]'`
- Aktifleştirme: `.venv/bin/activate` (Linux/macOS), `.venv\\Scripts\\activate` (Windows)

## Komutlar
- Test: `.venv/bin/pytest -q`
- Lint: `.venv/bin/ruff check src tests`
- Tip kontrolü: `.venv/bin/mypy src`
- Biçim kontrolü: `.venv/bin/ruff format --check src tests`

## Klasör düzeni
- `src/siparis_api/` paket kodu
- `tests/` pytest testleri
- `pyproject.toml` tüm yapılandırma

## Kurallar
- Her fonksiyon ve metod için tip ipucu zorunlu; `typing.Any` kullanma.
- Import sırası: standart kütüphane, üçüncü parti, yerel (`ruff` I001 kuralı).
- Bağımlılık eklerken `pyproject.toml` güncelle, asla `pip install` ile ortamı kirletme.
- Önce test yaz, sonra kodu değiştir.
- Taahhüt mesajı kısa ve emir kipinde olsun.
```

Bu dosya sayesinde ajan `pytest`, `ruff` ve `mypy` komutlarını doğru sanal ortamdan çağırır. `pyproject.toml` içinde test ve lint yapılandırması zaten varsa, GEMINI.md’de yalnızca komut satırı ve proje kuralları yeterlidir. Klasör düzenini açıkça yazmak, ajanın yeni modülü nereye koyacağını bilmesini sağlar.

## Python projesinde güvenli çalışma döngüsü

Ajanla planla, küçük adımlar at, testleri çalıştır, diff’i incele. Her turda tek bir sorumluluğu bitirmesini isteyin; aksi halde hem test çıktısı hem kod incelemesi karmaşıklaşır. İyi bir döngü şöyledir: önce mevcut durumu özetlemesini isteyin, sonra değişikliği küçük bir adımda yaptırın, ardından test ve lint komutlarını çalıştırmasını söyleyin, en son `git diff` çıktısını okuyun. Aşağıdaki örnek promptlar tipik Python işlerini kapsar:

- `siparis_api/models.py` içindeki `Order` sınıfına `status` alanı ekle; `Enum` kullan, tip ipuçlarını ve docstring’leri tamamla.
- `tests/test_orders.py` içinde eksik kapsamı belirle; `Order.total` hesaplaması için sınır değer testleri yaz.
- `src/siparis_api/utils.py` içindeki `format_price` fonksiyonunu `Decimal` döndürecek şekilde değiştir; çağrıldığı tüm yerleri güncelle.
- `ruff check` ve `mypy` hatalarını sırayla düzelt; her düzeltmeden sonra testleri yeniden çalıştır.
- `pyproject.toml` içindeki `pytest` ayarlarını `asyncio_mode = "auto"` olacak şekilde güncelle; mevcut testleri gözden geçir.

Her prompttan sonra ajanın çalıştırdığı komutları ve ürettiği diff’i kontrol edin. Özellikle testleri zayıflatan bir değişiklik yapmadığından emin olun: ajan bazen başarısız testi kaldırmayı veya assert’i gevşetmeyi seçebilir. İsterseniz ajanı yalnızca `git diff` göstermeye zorlayın, commit ettirmeyin.

## Ajanın iyi yaptığı Python işleri ve dikkat edilecek noktalar

Gemini CLI, tip ipucu ekleme, docstring yazma, import düzenleme, basit refactor ve test taslağı oluşturmada başarılıdır. Ruff ve mypy çıktılarını okuyup hatayı kendisi düzeltmesi de güçlü yönüdür. Ancak dikkat edilmesi gereken durumlar vardır:

| İş | İyi prompt | Dikkat edilecek nokta |
|---|---|---|
| Tip ipucu ekleme | `src/siparis_api/views.py` içindeki tüm fonksiyonlara eksiksiz tip ipucu ekle ve `mypy src` çalıştır | `Any` kullanmaya eğilimli olabilir; kuralı GEMINI.md’de netleştirin |
| Pytest ile test yazma | `calculate_discount` için parametreli test yaz, boş sepet ve negatif miktar senaryolarını ekle | Sadece mutlu yolu test edebilir; sınır koşullarını siz belirtin |
| Ruff düzeltme | `ruff check src tests --fix` ile otomatik düzeltmeleri uygula, sonra diff göster | `--fix` bazen davranışı değiştirmez ama okunabilirliği bozabilir; diff’i inceleyin |
| Bağımlılık ekleme | `pyproject.toml` içindeki `[project.optional-dependencies]` bölümüne `httpx` ekle | Sürüm aralığını kendisi seçebilir; mevcut uyumluluğu siz doğrulayın |

Python’a özgü tuzaklar arasında `sys.path` varsayımları, modül seviyesindeki yan etkiler ve asenkron kodun test edilmesi yer alır. Ajan, `__init__.py` dosyasını unutup import hatasına yol açabilir veya `asyncio` testlerini senkron çalıştırmayı deneyebilir. Bu nedenle GEMINI.md içinde asenkron testler için `pytest-asyncio` kullanımını açıkça yazın. Ayrıca ortam değişkenlerine dayalı yapılandırmalarda `.env` dosyasına erişim sınırlı olabilir; testlerde `monkeypatch` ile değişkenleri ayarlamasını isteyin.

## Python kodunu test etme ve doğrulama

Ajan her değişiklik sonrası `.venv/bin/pytest -q` komutunu çalıştırabilir. Test geçse bile `ruff` ve `mypy` sonuçlarını isteyin; bu üçlü, statik analiz ve davranış doğrulamasını birlikte kapsar. Örneğin `mypy src` temiz değilse tip hataları çalışma anında `AttributeError` veya `TypeError` olarak patlayabilir. Ruff’un `--fix` çıktısını her zaman diff ile karşılaştırın; otomatik formatlama beklenmedik satır değişiklikleri yaratabilir. Test kapsamı için şu döngüyü uygulayın: ajan yeni kod yazdığında, ilgili testi çalıştırıp başarısız olan durumu size rapor etmesini isteyin. Ardından eksik kapsamı siz belirleyip ajanın testi genişletmesini sağlayın. Son olarak `pytest --cov` gibi bir komutla kapsamı ölçün; ancak kapsam yüzdesinin tek başına kalite göstergesi olmadığını unutmayın. Ajanın önerdiği testleri gözden geçirip davranışı gerçekten doğruladığından emin olun; yalnızca satır sayacını artıran testler yazabilir.

## Bir Python projesinde birden çok ajanı yönetme: AgentVera

Aynı Python projesinde birden fazla kodlama ajanını paralel çalıştırmak için AgentVera’nın gerçek terminal panelleri ve git worktree desteği işe yarar. Her ajan kendi worktree’sinde kod değiştirir; böylece birbirinin dosyasını ezmez ve çakışma yaşamazsınız. Bir ajan bitirdiğinde ikinci model otomatik kod incelemesi yaparak Python’a özgü hataları `file:line` düzeyinde işaretler; bu, tip ve import hatalarını erken yakalamaya yardımcı olur. Ayrıca token bütçeleri, ajanların uzun test döngülerine takılmasını önlerken bütçe aşıldığında konuşmayı korur. Python’da sanal ortam ve GEMINI.md komutları her terminalde ayrı ayrı doğru ayarlanmalı; AgentVera bu komutları panellerde çalıştırmanıza olanak tanır. Böylece [kodlama ajanları için prompt yazma](/blog/kodlama-ajanlari-icin-prompt-yazmak/) rehberindeki yöntemleri farklı ajanlarla aynı anda deneyebilirsiniz.

## Sonuç

Gemini CLI, GEMINI.md ile doğru yapılandırıldığında Python projenizde sanal ortam, `pytest`, `ruff` ve `mypy` döngüsünü tek terminalden yürütür. Küçük adımlarla ilerleyip her turda diff ve test çıktısını incelemek, ajanı güvenilir bir eş programcıya dönüştürür. Python’a özgü tuzakları GEMINI.md içinde açıkça belirtin ve ajanın önerdiği test değişikliklerini asla otomatik kabul etmeyin. Paralel işler için AgentVera ile worktree ve otomatik inceleme kullanarak birden çok ajanı aynı projede güvenle yönetebilirsiniz.

## Sık sorulanlar

**Gemini CLI Python projesinde nasıl başlatılır?** Proje klasöründe terminal açıp gemini komutunu çalıştırın. Ajan, proje kökündeki GEMINI.md dosyasını okur. Python için sanal ortam ve test komutları bu dosyada tanımlıysa doğrudan onları kullanır.

**Gemini CLI Python projelerinde hangi komutları çalıştırabilir?** Sanal ortam etkinleştirildikten sonra pytest, ruff ve mypy gibi komutları çalıştırabilir. Bu komutların GEMINI.md içinde tanımlı olması, ajanın doğru araçları kullanmasını sağlar. Paket kurulumu için pip install -e '.[dev]' gibi bir komut yeterlidir.

**Gemini CLI ile Python kodu yazarken nelere dikkat etmeli?** Tip uyumu ve import düzenini GEMINI.md içinde açıkça belirtin. Her değişiklikten sonra diff’i inceleyin; özellikle testlerin gevşetilmediğinden emin olun. mypy ve ruff çıktıları, pytest geçse bile gizli sorunları yakalayabilir.

**Gemini CLI Python testlerini otomatik çalıştırabilir mi?** Evet, ajan test komutunu kendisi çalıştırabilir. Testler başarısız olursa hatayı okuyup düzeltme önerir. Ancak test kapsamını siz bilmelisiniz; ajan yalnızca mevcut testlere göre doğrulama yapar.

---

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