# Codex Python: Python projelerinde Codex kullanım rehberi

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

Python projelerinde Codex nasıl başlatılır, AGENTS.md nasıl yazılır, test ve tip kontrolü döngüsü nasıl kurulur? Pratik, adım adım rehber.

**Kısaca:**

- Codex, Python projesinde proje kökünde codex komutuyla başlar; AGENTS.md ile komutlar ve kurallar netleşir.
- Her görevde test, lint ve tip kontrolünü çalıştırıp diff’i inceleyin; Any veya # type: ignore gibi hilelere karşı uyanık olun.
- Paralel işler için git worktree ve otomatik kod incelemesi, Python refactor’larını daha güvenli hale getirir.

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

```text
# 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](/blog/codex-cli-nasil-kullanilir/) 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.

| Görev | Dikkat edilecek nokta |
|------|----------------------|
| Tip ekleme | Mypy geçsin diye `Any` veya `# type: ignore` eklemesi |
| Test yazma | Mevcut fixture’ları ve conftest.py’yi bozması |
| Bağımlılık güncelleme | Kilit dosyasını veya pyproject.toml’u izinsiz geniş değiştirmesi |
| Refactor | Tek seferde çok dosyayı değiştirip davranışı kaydırması |

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](/blog/ci-hatasini-yapay-zeka-duzeltsin/) 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](/blog/agentvera-nasil-kullanilir/) 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.

## Sık sorulanlar

**Codex Python projesinde nasıl başlatılır?** Terminalde proje köküne gidip codex komutunu çalıştırın. Ajan dosyaları ve AGENTS.md’yi okur; ardından Python görevlerinizi doğal dille verebilirsiniz.

**Codex sanal ortamı otomatik algılar mı?** Sanal ortamı kendiliğinden aktif etmez. AGENTS.md içinde source .venv/bin/activate veya python -m pytest gibi komutları belirtmeniz gerekir; ayrıca .venv dizinini değiştirmemesini söyleyin.

**Codex pytest hatalarını düzeltebilir mi?** Evet, python -m pytest -q çıktısını okuyup hataları düzeltebilir. Ancak mypy’yi susturmak için # type: ignore ekleyebilir; diff incelemesinde bu tür değişiklikleri kontrol edin.

**Birden çok Codex ajanı aynı Python projesinde nasıl çalışır?** Her ajanı ayrı git worktree veya ayrı görevle çalıştırarak çakışmaları önleyebilirsiniz. AgentVera gibi araçlar bu paralelliği yönetir, otomatik kod incelemesi ve kontrol noktaları sağlar.

---

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