opencode ile Python projelerinde pratik ajan kullanımı

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 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? 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? rehberine bakabilirsiniz.

# 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:

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.