# opencode ile Python projelerinde pratik ajan kullanımı

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

Python projelerinde opencode coding agent ile nasıl çalışılır? AGENTS.md, venv, pytest, ruff, mypy ve çoklu ajan kullanımı için pratik rehber.

**Kısaca:**

- opencode’u Python projenizde opencode komutuyla başlatın; AGENTS.md dosyası build, test ve lint komutlarını bağlama alır.
- Küçük adımlarla plan yapıp her değişiklik sonrası pytest, ruff ve mypy çalıştırmak ajanın Python hatalarını erken yakalamasını sağlar.
- Paralel görevlerde AgentVera’nın git worktree ve checkpoint özellikleri aynı Python kod tabanında çakışmayı önler.

`opencode`, Python projenizin kökünde `opencode` komutuyla başlattığınız terminal tabanlı bir kodlama ajanıdır. Projenizdeki AGENTS.md dosyasını bağlam olarak okur ve sizin verdiğiniz build, test, lint ve tip kontrolü komutlarını çalıştırabilir. Aşağıdaki pratik düzen, Python bilen bir geliştiricinin opencode ile güvenli ve hızlı çalışmasını sağlar. Daha genel kullanım için [opencode](/ajanlar/opencode/) sayfasına bakabilirsiniz.

## Neden opencode Python işlerine uygun?

Python işleri komut satırına yakın olduğu için opencode’un terminalde çalışması doğrudan değer üretir: `pytest -q`, `ruff check .` ve `mypy src` çıktılarını okuyup aynı oturumda düzeltme önerebilir. Ayrıca pyproject.toml, conftest.py ve modül içi import yapısı gibi metin tabanlı bileşenleri kolayca günceller. Modelden bağımsız çalışabildiği için Python projenizde en uygun modeli seçme esnekliği kalır. Bu karar için [opencode mu Claude Code mu?](/blog/opencode-mu-claude-code-mu/) yazısındaki kıyaslamaya göz atabilirsiniz.

opencode, sanal ortamı etkinleştirilmiş bir shell’de çalıştığında Python paketlerini doğru yerde arar; bu nedenle venv oluşturmak ve ajanı o ortamda çalıştırmak önemlidir. Ayrıca proje kökündeki pyproject.toml içindeki `[project]` ve `[tool.pytest.ini_options]` bölümlerini okuyarak test ve paket kurallarını anlayabilir. Bu, ajanın her seferinde hangi test komutunun geçerli olduğunu sormasını engeller ve doğrudan işe odaklanmasını sağlar. Python’un dinamik yapısı nedeniyle statik analiz tek başına yetmez; opencode test çıktılarını da yorumlayarak hataları giderebilir. Bu yönüyle terminal tabanlı bir ajan, masaüstü IDE eklentilerinden daha tutarlı bir Python deneyimi sunar.

## Projeyi ajan için hazırlama: Python projesinde AGENTS.md

opencode, proje kökündeki AGENTS.md dosyasını talimat olarak okur; bu nedenle komutları net ve kısa tutun. Dosya, sanal ortamı nasıl kurduğunuzu, hangi test komutunu kullandığınızı ve dizin kurallarınızı içermelidir. Bu dosyanın nasıl kullanılacağına dair adım adım anlatım için [opencode nasıl kullanılır?](/blog/opencode-nasil-kullanilir/) rehberine bakabilirsiniz.

```text
# AGENTS.md

## Build ve test komutları
- Ortam: python -m venv .venv && source .venv/bin/activate
- Kurulum: pip install -e ".[dev]"
- Test: pytest -q
- Lint: ruff check .
- Format: ruff format --check .
- Tip kontrolü: mypy src

## Dizin düzeni
- src/<paket>/ altında uygulama kodu; tests/ aynı yapıyı yansıtır.
- Kökte yalnızca pyproject.toml, AGENTS.md, README.md ve .gitignore bulunur.
- Geçici scriptler scripts/ altında olur.

## Python kuralları
- Bütün public fonksiyonlarda tip annotation zorunludur.
- pytest fixture'ları conftest.py içinde; test dosyaları test_*.py adını kullanır.
- Kütüphane kodunda print yok; logging kullan.
- Bağımlılık eklerken pyproject.toml içine neden eklendiğini kısa yorum olarak yaz.
```

AGENTS.md’yi bu seviyede tutmak, opencode’un her seferinde `pytest` mi `pytest -q` mi gibi sorular sormasını engeller ve agent’ı Python projesinin gerçek sözleşmelerine bağlar. `pip install -e ".[dev]"` komutu, paketi geliştirme modunda kurduğu için `src` altındaki modüllerin import edilebilir olmasını sağlar; bu, ajanın test çalıştırırken `ModuleNotFoundError` ile karşılaşmasını büyük ölçüde önler. Sanal ortam oluşturma komutunu ayrıca belirttiğinizde, ajan yeni bir ortam oluşturmayı veya mevcut ortamı etkinleştirmeyi bilir; böylece sistem Python’una paket bulaşmaz. Dizin düzeni kuralları, ajanın yeni dosya oluştururken nereye koyacağını şaşırmasını engeller. Python kuralları bölümü ise tip disiplininden logging kullanımına kadar projenizin kalite çıtasını korur. AGENTS.md’yi proje büyüdükçe güncelleyin; örneğin yeni bir test marker’ı eklediğinizde bunu dosyaya işleyin ki ajan da kullanabilsin.

## Çalışma döngüsü: plan, küçük adımlar, testler, diff

Ajanı doğrudan büyük bir refactor’a sokmak yerine her görevi küçük, doğrulanabilir adımlara bölün. Önce opencode’dan etkilenecek dosyaları ve test planını listeleyen kısa bir plan isteyin; sonra uygulatın. Her adım sonrası ajanın çalıştırdığı pytest, ruff ve mypy çıktısını isteyin. Değişiklikleri commit’lemeden önce mutlaka `git diff` ile inceleyin; özellikle test dosyalarındaki assert’lerin zayıflatılmadığından emin olun. Tipik Python görevleri için kullanabileceğiniz örnek prompt’lar:

- "`src/acme/payments.py` içindeki `calculate_tax` fonksiyonuna eksiksiz tip annotation ekle, ardından `mypy src` ve `pytest -q` çalıştır; kırılan test varsa düzelt."
- "Mevcut FastAPI endpoint’lerindeki pydantic modellerini pydantic v2 stiline taşı; her modül sonrası `ruff check .` ve `pytest tests/test_api.py` çalıştır."
- "`tests/test_cache.py` dosyasına geçersiz TTL ve boş anahtar için parametrize testler ekle; testleri çalıştır ve kırılanları raporla."
- "`pyproject.toml` içindeki bağımlılıkları grupla, `pip install -e ".[dev]"` sonrası oluşan import hatalarını çöz."
- "`src/acme/worker.py` içindeki print ifadelerini logging kullanacak şekilde değiştir; sonra ruff ve mypy çalıştır."

Bu prompt’lar, ajanın yalnızca kodu değil doğrulamayı da çalıştırmasını zorunlu kılar. Ek olarak, opencode’dan değişiklik öncesi mevcut testlerin hangilerinin etkileneceğini tahmin etmesini isteyebilirsiniz; bu, gözden kaçan yan etkileri azaltır. Ajan bir hata ile karşılaştığında traceback’in tamamını ona verin; çoğu zaman doğru düzeltmeyi önerecektir. Diff incelemesi sırasında yalnızca üretim koduna değil, `pyproject.toml`, `conftest.py` ve test dosyalarındaki değişikliklere de bakın. Özellikle `pytest.raises` bekleyen bir testin `assert` kısmının silinip silinmediğini kontrol edin. Küçük adımlar, hem ajanın hata yapma olasılığını düşürür hem de hangi değişikliğin testi bozduğunu kolayca bulmanızı sağlar.

## Tipik Python işleri ve dikkat edilmesi gereken yerler

opencode tip tamamlama, pytest yazımı, modül içi refactor, lint hatalarını giderme ve bağımlılık güncelleme gibi görevlerde iyi çalışır. Ancak Python’un dinamik doğası bazı tuzaklar yaratır. Ajan, `Any` tipini yaygınlaştırabilir, testleri geçirmek için assert’leri gevşetebilir veya çalışan bir import’u kırıp fark etmeden bırakabilir. Aşağıdaki tablo sık kullanılan görevler için iyi prompt ve dikkat noktalarını özetler:

| Görev | İyi prompt | Dikkat edilecek yer |
|---|---|---|
| Tip tamamlama | "Kod tabanındaki public fonksiyonlara tip ekle, mypy çalıştır." | `Any` kullanımı artabilir; `--strict` hedefliyorsan açıkça belirt. |
| Bağımlılık güncelleme | "pyproject.toml’daki üst limitleri testler yeşil kalacak şekilde gevşet." | Gereksiz alt limit ekleyebilir; `pip freeze` ile karşılaştır. |
| Test yazma | "Şu modül için boş ve sınır durumlarını kapsayan pytest ekle." | Sadece geçsin diye assert zayıflatabilir; diff’i incele. |
| Refactor | "Bu fonksiyonu ikiye böl, dış davranışı aynı kalsın; pytest -q ile doğrula." | Büyük refactor’da döngüsel import oluşabilir; mypy ve import sırasına bak. |

Bunların ötesinde, sanal ortam etkin değilken `pip install` çalıştırılması sistem Python’una paket bulaştırabilir. opencode’a her zaman aktive edilmiş `.venv` içinde komut çalıştırmasını açıkça söyleyin. Ayrıca paket adının `src` altında olması ve `pip install -e ".[dev]"` ile kurulması, ajanın modül import hatalarını daha az yaşamasını sağlar. Python’un döngüsel import sorunları, ajan büyük bir modülü bölerken ortaya çıkabilir; bu yüzden ilgili modülleri import eden testlerin varlığı kritik önem taşır. Ajanın `# type: ignore` yorumlarını otomatik eklemesine izin vermeyin; bunlar tip güvenliğini sessizce azaltır. `mock` veya `monkeypatch` kullanan testlerde ajanın teardown’ı unuttuğu durumlara dikkat edin. Ayrıca `__init__.py` dosyalarında gereksiz import bırakılmaması, paketin başlangıç süresini korur; ajanın bu dosyaları düzenlerken farkında olmadan yan etki eklemesi olasıdır.

## Test ve doğrulama

Python için olmazsa olmaz doğrulama üçlüsü `pytest`, `ruff` ve `mypy` olmalıdır. opencode’a her değişiklik sonrası bu üç komutu çalıştırmasını söyleyin; yalnızca "bitti" demesine güvenmeyin. Test çıktısında hata varsa ajanın traceback’i okuyup tamamlamasını isteyin. Hatalı bir commit oluşmadan önce `git diff -- tests/` ile test değişikliklerini ayrıca inceleyin. Determinizm için `pytest` ayarlarını pyproject.toml içinde sabitleyin; örneğin `addopts = "-q"` veya `filterwarnings` kuralları, ajanın her çalıştırmada aynı beklentiyi görmesini sağlar. Tip kontrolünde `mypy src` yeterli gelmiyorsa paket seviyesinde `# type: ignore` yorumlarının çoğalmasına izin vermeyin.

Ayrıca `ruff` için `extend-select` veya `ignore` listelerini pyproject.toml içinde tanımlayın; ajanın varsayılan kuralları bilmesi, tutarlı kod üretmesini sağlar. Testlerin paralel çalıştırılması gerekiyorsa bunu AGENTS.md’ye ekleyin, örneğin `pytest -n auto`. Ancak ajanın testleri paralel çalıştırması bazen veri yarışına yol açabilir; bu yüzden ilk etapta seri çalıştırmak daha güvenlidir. Flaky test fark ederseniz, opencode’a bu testi yeniden çalıştırmasını ve başarısızlık durumunda ilgili log’u raporlamasını söyleyin. Coverage hedefi koymak isterseniz, `pytest --cov` komutunu AGENTS.md’ye ekleyin, ancak ajanın coverage’ı yükseltmek için anlamsız testler yazmasına engel olmak için eşik değerini ve hangi dizinlerin ölçüleceğini net belirtin. Doğrulama komutlarının çıktısını ajanın yorumlaması, hata ayıklama süresini önemli ölçüde kısaltır, ama son kararı her zaman siz verin.

## Aynı Python projesinde birden fazla ajan: AgentVera

AgentVera, opencode ve diğer CLI ajanlarını tek pencerede gerçek terminal panellerinde çalıştıran bir masaüstü uygulamasıdır. Python projesi için en değerli tarafı, her ajanı kendi git worktree’sinde paralel başlatabilmesi; böylece biri `pytest` için fixture düzenlerken diğeri `ruff` hatalarını temizleyebilir ve aynı dosyayı ezmez. Ajan turu bitince ikinci model otomatik kod incelemesi yapar, bulgular file:line bağlantısıyla gelir. Ayrıca her turun checkpoint anlık görüntüsü, hatalı bir Python refactor’unu tek tıkla geri almayı sağlar.

## Sonuç

opencode’u Python projelerinde verimli kullanmanın özü, net bir AGENTS.md ve sürekli doğrulama döngüsüdür. Sanal ortamı aktif tutun, küçük adımlarla ilerleyin, her adımda test, lint ve mypy çıktısını isteyin, diff’i inceleyin. Böylece ajan size yardımcı olur; kontrol yine sizde kalır. Python’un dinamikliğine karşı statik analiz ve test disiplini, ajanın üretkenliğini güvenliğe dönüştürür. Zamanla kendi projenizin kalıplarına uyum sağlayan bir iş akışı geliştirebilirsiniz.

## Sık sorulanlar

**opencode Python projesinde nasıl başlatılır?** Proje kök dizininde terminal açıp opencode komutunu çalıştırın. Ajan, o klasördeki AGENTS.md dosyasını okur ve oradaki Python komutlarını kullanarak çalışmaya başlar.

**opencode sanal ortamı kendisi oluşturur mu?** Genellikle siz oluşturursunuz. İlk görevinizde opencode’a python -m venv .venv oluşturup etkinleştirmesini söyleyebilirsiniz; sonraki komutlar için o ortamı kullanması gerekir.

**opencode ile hangi Python işleri güvenle yaptırılır?** Tip annotation ekleme, pytest yazma, ruff hatalarını giderme, küçük refactor’lar ve bağımlılık güncelleme güvenle yaptırılabilir. Büyük mimari değişikliklerde plan ve diff incelemesi şarttır.

**opencode pytest ve ruff ile entegre çalışır mı?** Evet; ayrı bir entegrasyon gerekmez. AGENTS.md’ye pytest -q ve ruff check . komutlarını yazarsanız opencode değişiklik sonrası bunları çalıştırıp çıktıyı okuyabilir.

---

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