Codex Python: Python projelerinde Codex kullanım rehberi

Codex’i Python projesinde kullanmak için terminalde proje köküne gidip codex komutunu çalıştırmanız yeterlidir; ajan proje dosyalarını ve AGENTS.md’yi okuyarak komutları sizin adınıza çalıştırır. Bu rehberde, Python’a özel sanal ortam, test, lint ve tip kontrolü döngüsünü güvenilir biçimde kurmayı anlatıyorum. Amaç, ajanın tahmin değil doğrulanmış kod üretmesini sağlamaktır. Codex hakkında genel bilgi için Codex sayfasına bakabilirsiniz.

Neden Codex Python işine uygun?

Python’un kaynak kodu ve hata çıktıları metin tabanlı olduğundan, Codex terminalde çalışan bir ajan olarak traceback’leri, pytest özetlerini, ruff ve mypy çıktılarını doğrudan okuyup tepki verebilir. Sanal ortam ile izole edilmiş bir proje, ajanın kurulum bağımlılığı tahmin etmesine gerek kalmadan python -m pytest, ruff check gibi komutları çalıştırmasına olanak tanır. Python’daki type hints, dataclass, Pydantic gibi yapılar statik analiz için yeterli sinyal üretir; Codex bu sinyalleri kullanarak daha küçük ve derlenebilir düzenlemeler yapabilir. Bunun yanında, pyproject.toml merkezli modern Python projeleri, ajan için tek bir yapılandırma noktası sunar; ajan bağımlılık, test ve lint ayarlarını aynı dosyadan okur. Python’un dinamik doğası gereği, çalışma zamanı hataları çoğu zaman testlerle yakalanır; Codex test sonuçlarını okuyup aynı oturumda düzeltme önerir. Bu geri bildirim döngüsü, özellikle mypy çıktısını kullandığında daha net hale gelir. Yine de bu faydalar ancak proje kuralları açıkça yazılırsa işe yarar; aksi halde ajan kendi alışkanlıklarına göre dosya düzeni veya test yaklaşımı uydurabilir.

Projeyi ajan için hazırlama

Codex proje kökündeki AGENTS.md dosyasını her oturumda bağlam olarak okur. Python projesi için bu dosya, ajanın her seferinde sormaması gereken komutları, dizin düzenini ve dile özgü kuralları içermelidir. Özellikle sanal ortamın nasıl aktif edileceği, testlerin hangi komutla çalıştırılacağı ve hangi dosyaların değiştirilmemesi gerektiği açıkça yazılmalıdır. Aşağıdaki örnek, tipik bir pyproject.toml tabanlı proje için yeterli bir başlangıçtır:

# AGENTS.md

## Komutlar
- Sanal ortam: python -m venv .venv && source .venv/bin/activate
- Kurulum: pip install -e '.[dev]'
- Test: python -m pytest -q
- Lint: ruff check .
- Tip kontrolü: mypy src

## Dizin düzeni
- src/ paket kodu
- tests/ pytest testleri, conftest.py ortak fixture'lar
- pyproject.toml tüm bağımlılık ve araç ayarları

## Python kuralları
- Python 3.12+ kullan
- Tüm public fonksiyonlara type hints ekle
- Testlerde yalnızca pytest ve mevcut fixture'ları kullan
- .venv, __pycache__, .ruff_cache ve uv.lock dosyalarını değiştirme
- Hata gidermek için # type: ignore veya Any ekleme; önce doğru tipi bul

Bu dosya kısa ama yeterlidir; Codex, talimatları karıştırmadan komutları çalıştırır. Komutların başına python -m eklemek, sanal ortam aktif değilse bile doğru Python yorumlayıcısını kullanma şansını artırır. Ayrıca [project.optional-dependencies] altında dev grubu tanımlayarak test ve lint araçlarını ayrı tutabilirsiniz. Codex CLI’nin adım adım kurulumu ve ilk çalıştırma akışı için Codex CLI nasıl kullanılır? Adım adım rehber yazısına bakılabilir.

Çalışma döngüsü: planla, küçük adımlarla ilerle, testleri çalıştır, diff’i incele

Codex’ten en iyi sonucu almak için her görevi planla, küçük adımlara böl, testleri çalıştır ve diff’i incele döngüsüyle yürütün. Ajanın tüm projeyi tek seferde düzenlemesine izin vermek yerine, tek dosya veya tek fonksiyon düzeyinde istek yapın; her isteğin sonunda test, lint ve tip kontrolü komutlarını ajanın kendisine çalıştırın. Sonra git diff ile değişiklikleri inceleyin; özellikle testlerde davranış değişikliği olup olmadığına bakın. İşte Python projelerinde sık kullanacağınız istemler:

• src/services/order.py içindeki calculate_discount fonksiyonuna eksik type hints ekle, ilgili testleri tests/test_order.py altında güncelle ve python -m pytest -q çalıştır.
• python -m pytest -q çıktısındaki ilk üç hatayı sırayla düzelt; her düzeltmeden sonra yalnızca ilgili test dosyasını çalıştır.
• ruff check . çıktısındaki tüm hataları temizle, ancak # noqa eklemeden düzelt ve tekrar ruff check . ile doğrula.
• pyproject.toml içine pydantic bağımlılığını ekle, src/models.py içinde User modeli yaz ve tests/test_models.py ile doğrula.
• Bu değişiklikleri özetle, git diff --stat çıktısını göster ve tek cümlelik commit mesajı öner.

Codex’in iyi olduğu Python işleri ve dikkat edilecek yerler

Codex tip ekleme, basit refactor, test yazma, fixture düzenleme, bağımlılık güncelleme, hata ayıklama gibi işlerde hızlıdır. Özellikle dataclass, NamedTuple, Protocol gibi yapıları dönüştürürken veya pytest fixture’larını parametrize ederken iyi sonuç verir. Buna karşılık, Python’a özgü bazı riskler vardır: ajan, mypy’yi susturmak için Any veya # type: ignore ekleyebilir; var olmayan bir standart kütüphane fonksiyonunu veya paketin eski sürümündeki bir API’yi kullanabilir; sanal ortam aktif değilken global Python’a paket kurmaya çalışabilir; testlerde davranışı değiştirmeden yalnızca assertion’ları gevşetebilir. Ayrıca geniş çaplı bir refactor sırasında import düzenini bozup döngüsel bağımlılık yaratabilir.

Bu riskleri azaltmak için ajanın her turunu dar tutun ve yalnızca tek bir endişeyi çözmesini isteyin. Örneğin önce tip ekleme, sonra test yazma ayrı turlar olsun.

Python’da test ve doğrulama

Test ve doğrulama komutlarını ajanın her turunun sonunda zorunlu tutun. AGENTS.md’ye python -m pytest -q, ruff check . ve mypy src yazdığınızda, Codex bu komutları kendisi çalıştırıp çıktıyı yorumlar. Başarısız test veya tip hatası varsa, düzeltme isteğini çıktıdaki ilk hataya odaklayın; böylece ajan tüm projeyi değil sorunu düzeltir. Python’da doğrulama için tek başına pytest yeterli değildir; ruff hızlı lint ve format sağlar, mypy ise tip hatalarını yakalar. Codex’e bu üç komutu birlikte çalıştırma talimatı verin. Özellikle mypy --strict modunda başlangıçta çok hata üretebilir; ajanın hepsini bir kerede düzeltmesine izin vermek yerine önce src altındaki tek modüle odaklanın. CI’da yakalanan hatalar için de Codex’i çalıştırabilirsiniz; örneğin CI günlüğünü yapıştırıp ilgili hata bağlamında düzeltme isteyebilirsiniz. Bu akış için CI hatasını yapay zeka düzeltsin, PR yorumunu da yazısındaki yöntemi uygulayabilirsiniz.

Python projesinde birden çok ajan: AgentVera

Birden çok Codex ajanını aynı Python projesinde çalıştırırken dosya çakışmalarını önlemek ve kaliteyi korumak için AgentVera pratik bir çözüm sunar. Her ajan kendi git worktree’sinde çalıştığı için üst üste yazma riski ortadan kalkar; ajanlar paralel refactor veya test yazabilir. Ajanların her turunun sonunda ikinci bir model değişiklikleri otomatik inceler ve bulgularını dosya:satır düzeyinde bağlar. Ayrıca her turun anlık görüntüsü alındığından, yanlış bir refactor’u tek tıkla geri alabilir ve oturumu adım adım yeniden oynatabilirsiniz. Gerektiğinde token bütçeleriyle ajan başına ve tur başına sınır koyarak maliyet kontrolü sağlanır. AgentVera ile ajanları yapılandırma hakkında daha fazla bilgi için AgentVera nasıl kullanılır: ilk proje, ajanlar ve ızgara sayfasına bakabilirsiniz.

Özet

Codex Python projelerinde doğru konfigürasyon ve sıkı bir doğrulama döngüsüyle güçlü bir araçtır. Sanal ortamı, test, lint ve tip kontrolünü AGENTS.md ile tanımlayıp her turu küçük tutarak ajanın güvenilir değişiklikler yapmasını sağlarsınız. Paralel işler için AgentVera gibi araçlar işinizi kolaylaştırır. Deneyerek kendi akışınızı oluşturun.