Python projenizde terminalde gemini komutuyla 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:
# 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.pyiçindekiOrdersınıfınastatusalanı ekle;Enumkullan, tip ipuçlarını ve docstring’leri tamamla.tests/test_orders.pyiçinde eksik kapsamı belirle;Order.totalhesaplaması için sınır değer testleri yaz.src/siparis_api/utils.pyiçindekiformat_pricefonksiyonunuDecimaldöndürecek şekilde değiştir; çağrıldığı tüm yerleri güncelle.ruff checkvemypyhatalarını sırayla düzelt; her düzeltmeden sonra testleri yeniden çalıştır.pyproject.tomliçindekipytestayarları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 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.