# Cursor Agent Python Projelerinde Nasıl Kullanılır? Rehber

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

Cursor Agent ile Python projelerinde sanal ortam, pyproject.toml, pytest, mypy ve ruff kullanarak güvenli kod üretme rehberi. Kurulum, çalışma döngüsü ve tuzaklar.

**Kısaca:**

- Cursor Agent, Python projelerinde test, lint ve tip kontrolü ile küçük adımlarla güvenli kod üretir.
- AGENTS.md dosyasına sanal ortam, pyproject.toml ve komutları yazmak ajanın doğru çalışmasını sağlar.
- AgentVera ile birden çok Cursor Agent’ı git worktree’lerde paralel çalıştırıp otomatik kod incelemesi yapabilirsiniz.

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](/ajanlar/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:

```markdown
# 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](/blog/cursor-cli-nasil-kullanilir/) 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.py` içindeki `toplam` fonksiyonuna tip notasyonu ekle; ardından `mypy src` çalıştır ve hataları göster.'
- '`tests/test_hesap.py` içine `test_toplam_sifir` testini ekle; sadece sıfır ve negatif sayı durumlarını kapsa, sonra `pytest -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.toml` içine `pytest` bağımlılığını ekle ve `pip 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)](/blog/paralel-yapay-zeka-kodlama-ajani-araclari/) 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.

## Sık sorulanlar

**Cursor Agent Python projelerinde sanal ortamı nasıl kullanır?** Projenin sanal ortamını aktifleştirip cursor-agent komutunu çalıştırın. AGENTS.md dosyasına sanal ortam etkinleştirme ve çalıştırma komutlarını yazın; ajan komutları o ortamda çalıştırır.

**Cursor Agent Python testlerini kendisi çalıştırır mı?** Evet, planlı çalışma akışında ajan pytest komutunu kendisi çalıştırabilir. Siz de her değişiklikten sonra testleri çalıştırmasını isteyin.

**Cursor Agent Python’da tip hatalarını düzeltir mi?** mypy ile tip kontrolü yapılandırılmışsa ajan çıktıyı okur ve tip hatalarını düzeltebilir. Ancak büyük değişikliklerde diff’i incelemeniz gerekir.

**Cursor Agent Python kodu için hangi dosyaları okur?** AGENTS.md veya .cursor/rules dosyalarındaki proje kurallarını okur. Ayrıca pyproject.toml, kaynak kodu ve testleri inceler.

---

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