Codex, Django proje klasöründe codex ile başlatıldığında AGENTS.md dosyanızı okur; bu dosyaya test, lint, migration ve klasör kurallarını yazarsanız ajan projeye hızla adapte olur. Bu rehber, Django bilen geliştiriciler için Codex ile kontrolsüz kod üretmek yerine güvenli ve doğrulanabilir bir çalışma döngüsü kurmayı anlatıyor. Genel kullanım için Codex sayfasındaki bilgileri Django özelinde somutlaştırıyoruz.
Codex’in Django İşlerine Uygunluğu
Django’nun uygulama yapısı, modelleri, migration sistemi ve açık ORM arayüzü ajan için belirli sınırlar sağlar. Codex, modeller arası ilişkileri okumada, QuerySet üretmede ve DRF view/serializer çiftlerini tamamlamada iyi sonuç verir; çünkü bunlar genellikle dosyalar arası net bağımlılıkları olan, kalıpları tahmin edilebilir işlerdir. Örneğin, bir DRF endpoint’inde queryset’in nasıl optimize edileceğini, hangi serializer alanlarının eksik olduğunu veya bir formdaki validasyon mantığını hızlıca önerebilir. Ayrıca mevcut testlerdeki başarısızlıkları ayıklamada, import sorunları ve settings bağımlılıklarını çözmede yardımcı olur. Öte yandan Django’nun runtime state’i, ayar mirası ve migration zinciri hatalı varsayımlara açıktır; bu yüzden ajanın her çıktısı test ve diff ile denetlenmelidir.
Projeyi Ajan İçin Hazırlama ve AGENTS.md
Codex’i proje kökünde codex komutuyla başlatmadan önce AGENTS.md dosyasını hazırlamak en yüksek getirili adımdır. Bu dosya, ajanın her oturumda göreceği kalıcı bağlamdır; Bağlam mühendisliği: yapay zeka kodlama ajanları rehberi rehberinde anlatıldığı gibi net komutlar ve sınırlar koymadığınızda ajan genel geçer çözümler üretir. Codex CLI nasıl kullanılır? Adım adım rehber yazısındaki genel akışı da bilmek işe yarar.
Aşağıdaki örnek, tipik bir Django projesinin AGENTS.md dosyasını gösteriyor:
# AGENTS.md
## Proje
Django 5.1, Python 3.12, PostgreSQL 16. Bağımlılıklar pyproject.toml içinde.
## Sık kullanılan komutlar
- Kurulum: `python -m pip install -e '.[dev]'`
- Test: `pytest -q`
- Tek dosya testi: `pytest apps/users/tests/test_views.py -q`
- Lint/format: `ruff check . && ruff format --check .`
- Migration üret: `python manage.py makemigrations`
- Migration uygula: `python manage.py migrate`
- Migration durum kontrolü: `python manage.py makemigrations --check`
- Statik toplama (build kontrolü): `python manage.py collectstatic --noinput`
## Klasör ve mimari
- `apps/<app>/models.py`: modeller; iş mantığı burada büyümesin.
- `apps/<app>/services.py`: iş mantığı ve sorgu seçimleri.
- `apps/<app>/api/views.py`, `serializers.py`: DRF uçları.
- `apps/<app>/tests/`: pytest-django testleri; her uygulama kendi testini taşır.
- `config/settings/`: ortam bazlı ayarlar.
## Django kuralları
- Model alanı değiştirince `makemigrations` çalıştır ve migration dosyasını diff'te göster.
- Sorgularda N+1 riski varsa `select_related` veya `prefetch_related` ekle.
- QuerySet döngü içinde `get()` çağırma; toplu işleri tek sorguda yap.
- Migration'ları elle düzenleme; gerekirse önce `makemigrations --check` ile durumu kontrol et.
- Testlerde veritabanı erişimi için `@pytest.mark.django_db` kullan.
- API değişikliklerinde serializer testi ekle.
## Kod stili
- Import sırası: stdlib, üçüncü parti, Django, yerel.
- Fonksiyonlar kısa, tip ipuçları zorunlu.Bu dosyayı proje köküne koyduktan sonra codex komutunu çalıştırın. Ajan, istekleri bu kurallara göre yorumlar; örneğin bir model değişikliği istediğinizde diff içinde migration dosyasını da göstermesini beklersiniz. İlk halini yazdıktan sonra, ajanın yanlış yaptığı bir davranış gördüğünüzde dosyayı güncelleyin; örneğin migration üretmeden doğrudan model değiştirdiğini fark ederseniz, ‘model değişikliklerinde daima makemigrations çalıştır’ kuralını ekleyin. AGENTS.md dosyasını gereğinden uzun tutmayın; 50-100 satır arası hem bağlamı şişirmez hem de kritik kuralları barındırır.
Çalışma Döngüsü ve Örnek Komutlar
Codex ile Django çalışırken en sağlıklı döngü şudur: önce mevcut kodu okutup plan isteyin, sonra tek bir değişikliği uygulatın, ilgili testleri çalıştırın ve git diff ile çıktıyı inceleyin. Plan isteği genellikle ‘önce öneri listesi ver’ şeklinde başlar; böylece ajan doğrudan kod yazmadan mevcut yapıyı analiz eder. Ardından her değişiklik için tek bir görev verin ve test komutunu siz çalıştırın ya da ajanın çalıştırmasını isteyin. Ajan pytest çıktısını okuyup başarısız testleri düzeltebilir. Küçük adımlar, hem migration hatalarını erken yakalar hem de ajanın bağlamını gereksiz yere şişirmez.
Örnek istekler:
apps/orders/models.pyiçindeki Order modelini incele. Eksik index’leri ve unique constraint’leri tespit et; önce öneri listesi ver, kod yazma.apps/orders/views.pyiçindeki sipariş listesi endpoint’ini N+1 açısından tara. Gerekliselect_related/prefetch_relatedeklemelerini yap vepytest apps/orders/tests/test_api_orders.py -qile doğrula.apps/inventoryuygulamasında StockTransaction modelinereasonalanı ekle. Migration üret, admin kaydını güncelle ve yalnızca ilgili testleri çalıştır.- Şu hata için
pytest apps/billing/tests/ -qçıktısını yorumla; önce başarısız testi bul, sonra minimal düzeltmeyi uygula. - Mevcut DRF serializer’larını incele. Eksik validasyonları ve
select_relatedihtiyaçlarını raporla; sadece kritik olanları uygula.
Değişiklik sonrası git diff --stat ve git diff ile neyin değiştiğini görün. Ajan bazen gereksiz dosyaları (örn. pycache, .env) değiştirebilir. Özellikle settings.py veya urls.py gibi merkezi dosyalarda değişiklik yaparken diff’i satır satır kontrol edin. Her adımdan sonra git diff --stat ve git diff ile neyin değiştiğini görün. Özellikle apps/ altındaki model ve migration değişikliklerinde makemigrations --check çıktısını da isteyin.
Codex’in İyi Yaptığı Django Görevleri ve Riskler
Aşağıdaki tablo, Codex’in Django’da en çok kullanıldığı görevleri ve dikkat edilmesi gereken noktaları özetler:
| Görev | Codex için iyi bir istek | Dikkat edilecek nokta |
|---|---|---|
| Model + migration | Order modeline shipped_at alanı ekle, migration üret ve ilgili testleri çalıştır. | Otomatik migration’lar doğru olabilir; ancak data migration veya RunPython gerekiyorsa ajanın hazır şablonu körlemesine kullanmasını engelleyin. |
| ORM iyileştirme | Sorguyu N+1 açısından incele, select_related/prefetch_related öner ve uygula. | Gereksiz prefetch_related eklemek belleği şişirir; mutlaka pytest ve gerekirse EXPLAIN ile doğrulayın. |
| DRF view/serializer | OrderListAPIView için eksik queryset optimizasyonunu ve serializer validasyonunu tamamla. | Codex bazen iş mantığını serializer’a taşıyabilir; bu, model katmanını zayıflatır. Kurallarınızda iş mantığının yeri net olmalı. |
| pytest-django testleri | apps/orders/tests/ altında başarısız testleri düzelt ve yeni test ekle. | Veritabanı durumu testler arasında sızabilir; @pytest.mark.django_db kullanımını ve factory/fixture yapısını ajanın doğru anladığından emin olun. |
Tablonun ötesinde, Codex’in Django’da sıkça tökezlediği noktalar şunlardır: migration bağımlılıkları ve --fake gibi komutlar, lazy evaluation nedeniyle çalışmayan QuerySet’lerin debug edilmesi, settings’lerin ortam değişkenleriyle karışması, signal’lerin beklenmedik yan etkileri ve cache invalidation. Ajan bu konularda genellikle yüzeysel öneriler verir; bu yüzden üretim etkisi yüksek değişikliklerde deneyimli bir gözle doğrulama şarttır. Bunların dışında Codex; admin kayıtları, form validasyonları ve basit template düzeltmeleri gibi küçük işlerde de etkilidir. Ancak settings dosyalarında ortamdan ortama değişen değerleri, özel migration’ları ve sinyal kaynaklı yan etkileri değiştirirken dikkatli olun.
Test ve Doğrulama
Codex ile yapılan her değişiklikten sonra test komutunu çalıştırmak pazarlık konusu olmamalıdır. Django projelerinde pytest -q veya sadece ilgili uygulama için pytest apps/<app>/tests/ -q çalıştırın. Başarısız test varsa ajanın test çıktısını okumasını isteyin; düzeltme sonrası yalnızca başarısız testleri hızlıca tekrar koşmak için pytest --lf kullanılabilir. pytest-django kullanıyorsanız, test veritabanı yeniden kullanımı için --reuse-db seçeneği hızlı döngüler sağlar; ancak model değişikliklerinden sonra --create-db gerekebilir. Ajanın eklediği testlerde django_db marker’ının doğru kullanıldığından emin olun; aksi halde ‘Database access not allowed’ hataları görürsünüz. Ayrıca ruff check . ve ruff format --check . komutlarını da çalıştırarak stil hatalarını erken yakalayın.
Testlerin yanında git diff incelenmeden iş bitmiş sayılmaz. Özellikle modellerde alan eklemeleri, index değişiklikleri veya DRF serializer alanlarında diff’i satır satır inceleyin. Ayrıca migration güvenliği için python manage.py makemigrations --check --dry-run gibi bir kontrol eklemek faydalıdır; böylece model ve migration dosyaları arasındaki uyumsuzluk erken görülür. Doğrulama akışını her değişiklik için tekrarlayın: test + lint + migration check + diff.
Aynı Django Projesinde Birden Fazla Ajan: AgentVera
Django projesinde model ve migration değişiklikleri paylaşılan dosyalarda çakışma riski doğurur; AgentVera bu riski azaltır. Her ajanı kendi git worktree’sinde çalıştırabilir, böylece biri apps/orders/models.py ile uğraşırken diğeri apps/payments üzerinde aynı anda değişiklik yapabilir. Ajan turu bittiğinde otomatik kod incelemesi model ile migration uyumsuzluklarını dosya:satır göstererek yakalar. Checkpoint’ler sayesinde hatalı bir migration veya settings değişikliği tek tıkla geri alınabilir. Token bütçeleri ise uzun süren migration zinciri işlerinde ajanın kontrolsüz harcama yapmasını önler. Ayrıntılar için AgentVera nasıl kullanılır: ilk proje, ajanlar ve ızgara rehberine bakılabilir.
Sonuç
Codex’i Django’da verimli kullanmanın yolu, ajanı serbest bırakmak değil; AGENTS.md, küçük adımlar, test ve diff ile sınırlandırmaktır. Migration ve ORM odaklı değişikliklerde doğrulamayı artırın, aynı projede paralel çalışıyorsanız worktree ve inceleme mekanizmalarını kullanın. Zamanla, ajanın sık yaptığı hataları AGENTS.md’ye ekleyerek projeye özgü bir içgörü oluşturursunuz. Böylece Codex, Django projelerinde güvenilir bir çift pilot olur.