Codex, FastAPI proje klasöründe codex komutuyla başlattığınız bir kodlama ajanıdır. FastAPI bilen geliştiriciler için path operations, Pydantic modelleri, dependency injection, async endpoint’ler ve pytest ile TestClient kullanımı üzerinden pratik bir çalışma düzeni kurar. Bu rehber, ajanı AGENTS.md üzerinden yönlendirmeyi, küçük adımlarla test etmeyi ve sık yapılan hataları önlemeyi gösterir; Codex hakkında temel bilgi için ilgili sayfaya göz atabilirsiniz.
Neden Codex FastAPI işlerine uygun?
FastAPI projeleri güçlü bir dosya ve dekoratör düzenine sahiptir. @app.get path operation’ları, BaseModel şemaları ve Depends parametreleri ajanın kodda gezinmesini kolaylaştırır. Codex dosyaları okuyup mevcut kalıpları taklit edebildiği için yeni bir endpoint eklerken diğer router dosyalarındaki yapıyı kullanır. Ayrıca proje komutlarını çalıştırabildiği için pytest çıktısını görür ve hatayı kendi düzeltir. FastAPI’nin tip ipuçlarına dayalı yapısı da ajanın Pydantic şema değişikliklerini endpoint imzalarıyla birlikte güncellemesine yardımcı olur. Otomatik OpenAPI ve JSON Schema üretimi sayesinde ajan, yaptığı değişikliğin dokümantasyona yansımasını testten önce görebilir.
FastAPI projesi için AGENTS.md kurulumu
Codex proje klasörüne girdiğinde önce AGENTS.md dosyasını okur. FastAPI projesi için bu dosyaya çalıştırma komutlarını, klasör düzenini ve ajanın uyması gereken FastAPI kurallarını yazın. Böylece ajan her değişiklik sonrası doğru test ve lint komutlarını kullanır; ayrıca hangi dosyanın ne işe yaradığını bilir. Bu dosya yoksa Codex genel varsayımlarla hareket eder ve yanlış test komutu çalıştırabilir; FastAPI projesinde pytest ile TestClient kullanımı kritik olduğu için AGENTS.md ilk adım olmalıdır. Bağlam mühendisliği açısından bu dosya, ajanın tüm repo yerine ilgili katmanlara odaklanmasını sağlar. Daha geniş bir kurulum anlatımı için Codex CLI nasıl kullanılır? sayfasına bakabilirsiniz.
# AGENTS.md
## Proje komutları
- Bağımlılık kurulumu: `poetry install`
- Geliştirme sunucusu: `poetry run uvicorn app.main:app --reload`
- Test: `poetry run pytest -q`
- Lint: `poetry run ruff check app tests`
- Format: `poetry run ruff format app tests`
- Tip kontrolü: `poetry run mypy app`
## Klasör düzeni
- `app/main.py`: FastAPI uygulaması
- `app/routers/`: path operations
- `app/schemas/`: Pydantic modelleri
- `app/services/`: iş mantığı
- `app/dependencies.py`: ortak dependency'ler
- `tests/`: pytest testleri
## FastAPI kuralları
- Tüm endpoint yanıtları Pydantic response_model ile tanımlanmalı.
- Dependency'ler `Depends(...)` ile enjekte edilmeli, global import edilmemeli.
- Async endpoint'lerde yalnızca async kütüphaneler kullanılmalı.
- Testler `TestClient` ile yazılmalı, gerçek sunucu başlatılmamalı.
- Veritabanı session'ı dependency olarak sağlanmalı.Codex ile çalışma döngüsü ve örnek promptlar
Codex’e tek seferde büyük bir refactor vermek yerine plan yapın, küçük adımlar isteyin, her adımdan sonra testleri çalıştırın ve git diff ile değişiklikleri gözden geçirin. Plan yaparken ajanın hangi router ve şema dosyalarını değiştireceğini söyleyin; bu, ajanın ilgisiz dosyalara dokunmasını önler. Ajan bir endpoint ekledikten sonra testi birlikte yazmasını isteyin; test geçtikten sonra bir sonraki göreve geçin. Aşağıdaki tabloda tipik FastAPI görevleri için doğrudan kullanabileceğiniz promptlar var.
| Görev | Codex promptu |
|---|---|
| Yeni endpoint | app/routers/users.py içine GET /users/{user_id} ekle. UserRead response_model kullan, 404 döndür, testini tests/test_users.py içinde TestClient ile yaz ve pytest -q çalıştır. |
| Şema güncelleme | UserCreate şemasına age: Optional[int] = None alanını ekle, validator yaz, mevcut testleri güncelle ve çalıştır. |
| Dependency refactor | get_db oturumunu kullanan korumalı endpoint’leri require_user dependency’sine taşı; yetkisiz erişimde 401 döndür. |
| Async düzeltme | GET /items endpoint’ini async yap; DB çağrılarını AsyncSession ile uyumlu hale getir ve testleri geçir. |
| Test ekleme | POST /auth/login için başarılı ve başarısız giriş testlerini TestClient ile yaz; başarısızda 401, başarılıda token döndüğünü doğrula. |
Her prompt sonrası poetry run pytest -q çalıştırın ve git diff ile eklenen değişiklikleri inceleyin. Ajan testi geçemezse hatayı gösterin ve düzeltmesini isteyin.
Codex’in iyi yaptığı FastAPI işleri ve dikkat edilecek noktalar
Codex CRUD endpoint’leri, Pydantic şema ekleme/güncelleme, dependency injection’a taşıma, test yazma ve OpenAPI tutarlılığını düzeltme işlerinde oldukça iyidir. Mevcut router dosyalarındaki düzeni taklit ettiği için endpoint eklerken yanıt modeli ve durum kodu seçimini tutarlı yapar. Ancak şu noktalarda sıkı denetim gerekir:
- Async endpoint içinde sync ORM/DB çağrısı:
async defaltında blockingSessionveyarequestskullanabilir; bunuAsyncSessionveyarun_in_threadpoolile değiştirin. - Pydantic v1/v2 farkı:
orm_modeyerinefrom_attributes,schema()yerinemodel_dump()gibi sürüm karışıklığı olabilir. - Dependency injection sırası:
Dependsparametre sırası veya yield dependency’lerde kaynak kapatma hataları. - Response model atlamak: Ajan endpoint döndürürken
response_modeleklemeyi unutabilir; bu OpenAPI şemasını bozar. - TestClient ve lifespan:
TestClient(app)kullanırken lifespan handler’ları çalıştırmak içinwith TestClient(app) as client:gerekir; ajan bazen bunu atlayabilir. - Döngüsel import: Router’ları
main.pyiçinde import ederkenappnesnesini başka modülden almak döngüsel bağımlılık oluşturabilir.
Test ve doğrulama
Codex ile çalışırken her değişiklikten sonra ajanın şu komutları çalıştırmasını isteyin:
| Komut | Ne doğrular? |
|---|---|
poetry run pytest -q | TestClient ile path operation’ların yanıtlarını ve durum kodlarını doğrular. |
poetry run ruff check app tests | İmport düzeni, kullanılmayan değişkenler ve stil hatalarını yakalar. |
poetry run mypy app | Pydantic modelleri ile endpoint tipleri arasındaki uyumsuzlukları bulur. |
poetry run uvicorn app.main:app --reload | Manuel smoke test; OpenAPI dokümanını /docs üzerinden kontrol edin. |
Testleri yalnızca ajanın çalıştırmasına güvenmeyin; kendiniz de pytest -q çalıştırın ve git diff çıktısını inceleyin. Özellikle endpoint dönüş tipi, durum kodu ve hata mesajı gibi kontrat değişikliklerinde TestClient ile yazılmış testler en güvenilir doğrulamadır. Ajan bir test eklediğinde testin başarısız olup olmadığını ve gerçekten davranışı kapsadığını kontrol edin; bazen ajan kendini doğrulamak için zayıf bir test yazabilir.
AgentVera ile birden fazla ajan kullanımı
AgentVera, Codex dahil birden çok kodlama ajanını aynı pencerede gerçek terminal panellerinde yan yana çalıştıran bir masaüstü uygulamasıdır; FastAPI projelerinde her ajanı kendi git worktree’sinde çalıştırarak dosya çakışmalarını önleyebilirsiniz. Bir ajan endpoint eklerken diğeri Pydantic şemasını güncelleyebilir; otomatik kod incelemesi, değişiklikleri file:line bağlantılarıyla gösterir ve checkpoints sayesinde yanlış bir adımı geri alabilirsiniz. Token bütçeleri ajan başına, tur başına ve günlük olarak sınırlandırılabilir; %80 dolulukta uyarı alırsınız ve kap aşıldığında ajan sohbetini koruyarak durur. FastAPI işlerinde paralel worktree kullanımı ve otomatik review özellikle test geçmeyen değişiklikleri hızlıca yakalamanızı sağlar. Daha fazlası için AgentVera nasıl kullanılır sayfasına bakın.
Sonuç
Codex, FastAPI projelerinde AGENTS.md ile doğru yönlendirildiğinde endpoint geliştirme, şema güncelleme ve test yazma işlerini hızlandırır. Küçük prompt döngüleri, sürekli test ve dikkatli diff incelemesi ajanın ürettiği kodu güvenilir kılar. Async ve dependency injection konularında elle kontrol şarttır; ancak doğru kurulumla Codex FastAPI işlerinin önemli bir kısmını sizin için güvenle yapabilir.