Cursor Agent, bir Python projesinde terminalden cursor-agent komutuyla başlatılır ve kod yazma, test çalıştırma, lint ile tip kontrolü gibi işleri sizinle birlikte yürütür. Bu rehber, Python ekosistemiyle (venv, pyproject.toml, pytest, mypy, ruff) nasıl sağlam bir akış kurulacağını gösterir. Ayrıntılı ajan kullanımı için Cursor Agent sayfasına bakabilirsiniz.
Cursor Agent Python işlerinde neden iyi çalışır?
Python projeleri güçlü ve standart araçlara sahiptir; Cursor Agent bu araçların çıktısını okuyup bir sonraki adımı planlayabilir. Sanal ortam ve pyproject.toml sayesinde bağımlılıklar belirlidir, böylece ajan hangi komutu çalıştıracağını bilir. pytest hatalarını, ruff ihlallerini ve mypy tip sorunlarını aynı terminalde görebilir; siz de diff’i inceleyerek ilerlersiniz. Python’un dinamik yapısı nedeniyle testler ve tip kontrolü kritik olduğundan, Cursor Agent’ın bu komutları kendisinin çalıştırması geri bildirim döngüsünü kısaltır.
Ajan ayrıca modül importlarını, paket yapısını ve test kapsamını anlamak için proje dosyalarını tarar. Örneğin, bir fonksiyonun tip notasyonu eksikse mypy çıktısını okur ve ilgili satırı düzeltir; bir test başarısız olursa traceback’i analiz edip kök nedeni bulmaya çalışır. Bu onu sadece kod üreten bir araç değil, Python iş akışının aktif bir parçası yapar. Ancak ajanın çıktısına körü körüne güvenmeyin; her adımda sizin onayınız ve diff incelemeniz gerekir.
Python projesini Cursor Agent için hazırlama
Cursor Agent proje kökündeki AGENTS.md veya .cursor/rules dosyalarını okur. Python projenizde bu dosyaya sanal ortam, kurulum, test, lint ve tip kontrolü komutlarını yazın; ajan her adımda bu komutları kullanır. Klasör düzenini ve Python’a özgü kuralları da ekleyin. Örnek bir AGENTS.md:
# AGENTS.md - Python projesi kuralları
## Komutlar
- Sanal ortam: `python -m venv .venv && source .venv/bin/activate`
- Kurulum: `pip install -e '.[dev]'`
- Test: `pytest -q`
- Lint: `ruff check .`
- Format: `ruff format .`
- Tip kontrolü: `mypy src`
## Klasör düzeni
- Kaynak kod: `src/`
- Testler: `tests/`
- Paket verileri: `src/<paket>/py.typed`
## Python kuralları
- Tüm genel fonksiyonlara tip notasyonu ekle; `Any` kullanma.
- Testler pytest ile yazılır; her yeni davranış için test ekle.
- `ruff` çıktısını temizlemeden işi bitirme.
- `pyproject.toml` içindeki bağımlılıkları elle düzenle, `pip freeze` kullanma.Bu dosyayı projenin köküne koyun. Sanal ortamın zaten var olduğunu varsayın; ajanın kendi başına yeni bir ortam yaratmasını istemiyorsanız ‘venv oluşturma’ komutunu yazmayın. Ajan, AGENTS.md’yi her görev başında okur ve komutları yürütürken bu kurallara uyar. Alternatif olarak .cursor/rules dosyasına aynı bilgileri ekleyebilirsiniz; ikisi de ajan tarafından tanınır. Cursor CLI’nin temel kullanımı için Cursor CLI nasıl kullanılır? Adım adım rehber rehberi işinize yarar.
Güvenli çalışma döngüsü ve örnek komutlar
Döngü dört adımdan oluşur: plan iste, küçük bir değişiklik yapmasını söyle, testleri/lint/type check çalıştır, diff’i incele. Agent’a asla ‘tüm projeyi düzelt’ demeyin; tek bir fonksiyon veya modülle sınırlayın. Aşağıdaki örnek komutlar işinize yarar:
- ‘Sanal ortamı etkinleştir ve
pytest -qçalıştırarak mevcut durumu kontrol et.’ - ‘
src/hesap.pyiçindekitoplamfonksiyonuna tip notasyonu ekle; ardındanmypy srcçalıştır ve hataları göster.’ - ‘
tests/test_hesap.pyiçinetest_toplam_sifirtestini ekle; sadece sıfır ve negatif sayı durumlarını kapsa, sonrapytest -qçalıştır.’ - ‘Ruff hatalarını düzelt;
ruff check .çıktısını temizle, diff’i göster.’ - ‘Son iki commit’in diff’ini incele; davranış değişikliklerini ve test eksiklerini listele.’
- ‘
pyproject.tomliçinepytestbağımlılığını ekle vepip install -e .[dev]ile kur; ardından testleri çalıştır.’
Her adımdan sonra ajanın çıktısını okuyun; testler yeşil değilse bir sonraki adıma geçmeyin. Küçük adımlar sayesinde hata ayıklamak kolaylaşır. Değişikliği beğenmezseniz git checkout -- <dosya> ile geri alabilirsiniz; ajan da bunu yapabilir ama komutu siz verin.
Cursor Agent’ın iyi yaptığı Python işleri ve dikkat edilecekler
Cursor Agent refactor, test yazma, lint düzeltme ve bağımlılık güncelleme gibi tekrarlı işlerde hızlıdır. Ancak Python’un dinamik yapısı nedeniyle bazı tuzaklara dikkat edin:
| Görev | Agent iyi çalışır | Python’a özgü tuzak |
|---|---|---|
| Bağımlılık ekleme | pyproject.toml’u günceller, sanal ortama kurar | Gereksiz paket ekleyebilir; her diff’i kontrol edin |
| Refactor | Tip notasyonlarını ve importları korur | Geniş kapsamlı değişikliklerde testleri atlayabilir |
| Test yazma | pytest dekoratörlerini ve fixture’ları bilir | Zayıf assertion veya sahte testler ekleyebilir |
| Lint ve tip düzeltme | ruff/mypy çıktısını anlar | Bazı hataları # noqa veya # type: ignore ile bastırabilir |
| Docstring üretme | Google/NumPy stilini takip eder | Yanlış örnekler veya eksik parametreler yazabilir |
| Performans iyileştirme | Basit optimizasyonlar yapabilir | Algoritmik karmaşıklığı göz ardı edip mikro optimizasyon yapabilir |
Özellikle import yan etkileri olan modüllerde, ajan yanlış sırada import düzeltebilir. Sanal ortam dışına yazma veya global pip kurulumu yapmasına izin vermeyin. Ajanın pyproject.toml içindeki bağımlılık sınırlarını değiştirmesini istemiyorsanız bunu kurallara ekleyin. Ayrıca Python’un mutable default argument, global interpreter lock, async/await gibi konularında ajan bazen hatalı öneriler verebilir; bu tür değişiklikleri özellikle inceleyin.
Test ve doğrulama stratejisi
Python projelerinde ajanın işini bitmiş sayması için üç komutun da temiz dönmesi gerekir: pytest -q, mypy src ve ruff check .. Bunları bir zincir halinde çalıştırmasını isteyin. Örneğin: ‘Değişikliği yap, ardından pytest -q && mypy src && ruff check . çalıştır; hata varsa düzelt.’ Test kapsamını artırmak için regresyon testleri eklemesini isteyin; böylece ajanın değiştirdiği davranışı doğrulamış olursunuz. Ajan testleri kendisi çalıştırdığı için bazen kendi çıktısını yanlış yorumlayabilir; siz de komutları manuel olarak çalıştırıp doğrulayın.
git diff çıktısını incelemek, özellikle tip notasyonları ve import değişikliklerinde zorunludur. Testlerin kalitesini de kontrol edin: iddialar gerçek davranışı doğruluyor mu, fixture’lar izole mi, parametrize testler doğru mu? Gerekirse ajanı hypothesis gibi property-based test kütüphaneleriyle ek testler yazmaya yönlendirin. Coverage raporu isterseniz pytest --cov komutunu ekleyebilirsiniz, ancak asıl güven testlerin anlamlılığından gelir. Ajanın çalıştırdığı komutların çıktısını okuyun; ajan bazen hatayı yutup devam edebilir.
Birden çok ajanı tek Python projesinde çalıştırma (AgentVera)
AgentVera, Cursor Agent dahil birden çok CLI kod ajanını kendi terminal panellerinde yan yana çalıştıran bir masaüstü uygulamasıdır. Python projeleri için en değerli özellikleri şunlardır: her ajan kendi git worktree’sinde çalıştığı için aynı dosyaları ezmez; bir ajanın turu bittiğinde ikinci bir model otomatik kod incelemesi yapar ve bulgular dosya:satır olarak bağlanır; token bütçeleri ajanın sonsuz döngüye girmesini engeller; kontrol noktaları sayesinde bozulan bir ortam tek tıkla geri alınabilir. Böylece bağımlılık veya test değişikliklerini paralel dallarda deneyebilir, en sağlam olanı birleştirirsiniz. Bu paralel ajan araçları hakkında daha fazla bilgi için Paralel kodlama ajanları için en iyi araçlar (2026) sayfasına göz atabilirsiniz.
Sonuç
Cursor Agent, Python projelerinde disiplinli bir test-lint-tip kontrolü döngüsüyle çalıştığında büyük zaman kazandırır. Kuralları AGENTS.md’ye yazın, komutları küçük parçalara bölün ve her adımda diff’i inceleyin. Paralel işler için AgentVera gibi araçlarla birden çok ajanı güvenle yönetebilirsiniz. Python’un dinamik doğasına uygun bu akış, ajanın hatalarını erken yakalamanızı sağlar.