# Cursor Agent Django: Projede Nasıl Kullanılır?

Adres: https://agentvera.dev/blog/cursor-agent-ile-django/ · Yayın: 2026-11-01

Django projelerinde Cursor Agent ile model, migration, DRF ve test işlerini güvenle yürütün. Kurulum, AGENTS.md, prompt örnekleri ve sık hatalar.

**Kısaca:**

- Cursor Agent, Django projelerinde model-migration-test döngüsünü hızlandırır; AGENTS.md ile komut ve kuralları netleştirin.
- Ajanın önerdiği değişiklikleri her zaman pytest ve diff ile doğrulayın; migration ve ORM tuzaklarına dikkat edin.
- Paralel ajan kullanımında AgentVera worktree, otomatik review ve checkpoint ile Django değişikliklerini güvene alır.

`cursor-agent` ile bir Django projesi açtığınızda, kod tabanını okuyup model, migration, view ve test katmanlarında değişiklik önerebilen terminal tabanlı bir [Cursor Agent](/ajanlar/cursor-agent/) çalıştırmış olursunuz. Bu rehberde, Django’ya özel AGENTS.md kurallarını, güvenli çalışma döngüsünü ve sık düşülen tuzakları pratik örneklerle ele alıyorum. Django projelerinde ajanın en büyük avantajı, ORM, migration ve DRF gibi katmanları birlikte yorumlayabilmesidir; ancak doğru kurulum ve doğrulama yapılmazsa hatalı kod üretebilir.

## Django işleri için neden Cursor Agent?

Django projeleri genellikle birden çok app, migration zinciri, ORM sorguları ve DRF endpoint’lerinden oluşur. Cursor Agent bu yapıyı dosya düzeyinde değil proje bağlamında okur; örneğin bir model değişikliğinin hangi serializer, admin, form ve migration dosyalarına dokunacağını çıkarabilir. Terminalde proje kökünde `cursor-agent` başlattığınızda, `manage.py` komutlarını ve pytest çıktılarını kendi bağlamında kullanabilir; böylece sadece kod üretmekle kalmaz, hatayı test çıktısına göre düzeltebilir.

Ajan özellikle şu işlerde kullanışlıdır:

- mevcut modellere alan ekleyip migration üretmek,
- DRF serializer ve viewset’leri mevcut kod stilinden çıkararak yazmak,
- N+1 sorguları bulup `select_related`/`prefetch_related` eklemek,
- pytest-django ile test senaryolarını genişletmek.

Ajan ayrıca `settings.py`, `INSTALLED_APPS` ve `urls.py` dosyalarını incelediği için yeni bir app eklerken gerekli ayarları otomatik tamamlar; örneğin yeni bir `payments` app’i oluşturduğunda `settings.py` içine eklemeyi ve ana `urls.py` içine include etmeyi önerebilir. Karmaşık bir refactor sırasında tüm etkilenen dosyaları listeleyip adım adım değişiklik yapabilir. Bir migration üretmeden önce ajan, modelin `Meta` sınıfındaki `ordering`, `verbose_name` gibi ayarları kontrol eder; alan tipleri, `default`, `null`, `blank` gibi parametreleri mevcut kod stiline göre önerir. Ancak her zaman `makemigrations --dry-run` ile üretilecek migration’ı önizleyin.

Daha genel kurulum ve temel kullanım için [Cursor CLI nasıl kullanılır? Adım adım rehber](/blog/cursor-cli-nasil-kullanilir/) sayfasına bakabilirsiniz.

## Projeyi ajan için hazırlama

Ajanın doğru kararlar vermesi için proje köküne `AGENTS.md` veya `.cursor/rules` dosyası koyun. Bu dosya, komutlar, klasör kuralları ve Django’ya özgü kısıtları içermelidir. Ajan her çalıştığında bu talimatları okur; böylece her seferinde proje yapısını yeniden keşfetmek yerine doğrudan doğru varsayımlarla başlar. `AGENTS.md` proje genelinde tek dosya iken, `.cursor/rules` içinde birden fazla kural dosyası tutabilirsiniz; örneğin `django-rules.mdc` gibi. Her iki yöntem de ajanın davranışını netleştirmek için iyidir.

Dosya kısa ve komut odaklı olmalı; uzun açıklamalar ajanın dikkatini dağıtabilir. Özellikle migration üretme, test çalıştırma ve lint komutlarını net belirtin. Ayrıca Python ve Django sürümünü, ayar modülünü (örneğin `DJANGO_SETTINGS_MODULE=config.settings.local`) ve veritabanı ayarlarını belirtin; böylece ajan doğru ortamı varsayar. Gizli anahtarları (SECRET_KEY, API anahtarları) dosyaya yazmayın.

Örnek dosya:

```markdown
# AGENTS.md

## Proje
Django 5.x + DRF + pytest-django. Uygulamalar `apps/` altında.

## Komutlar
- Test: `pytest`
- Tek dosya: `pytest apps/checkout/tests/test_orders.py -x`
- Lint: `ruff check .`
- Format: `ruff format .`
- Migration üret: `python manage.py makemigrations`
- Migration uygula: `python manage.py migrate`

## Klasör kuralları
- Model adları tekil, tablo adı app_label ile otomatik.
- Migration dosyalarını elle düzenleme; her değişiklik için ayrı üret.
- View'lar ince tutulur; iş mantığı `services.py` veya `selectors.py` içinde.
- DRF serializer'ları `api/serializers.py` altında, viewset'ler `api/views.py`.

## Django'ya özel kurallar
- QuerySet'leri view içinde değil model manager/metodunda tanımla.
- `select_related` ve `prefetch_related` sadece N+1 riski olduğunda ekle.
- Migration'ları çalıştırmadan önce mevcut migration graph'ını kontrol et.
- Testlerde veritabanı erişimi gerektiren testler `@pytest.mark.django_db` ile işaretlenir.
```

Bu talimatları ajanın proje anlayışının temeli olarak düşünün; her seferinde prompt içinde tekrar etmek yerine buraya yazmak daha verimlidir. Bu dosyayı sürüm kontrolüne ekleyin; böylece ekip arkadaşlarınız da aynı kuralları kullansın. Ajan, dosyayı okuduktan sonra kullanıcıdan gelen prompt’lara göre hareket eder; ancak bazen dosyadaki kuralları göz ardı edebilir, o yüzden önemli noktalarda prompt içinde hatırlatın.

## Güvenli çalışma döngüsü

Ajanla çalışırken şu sırayı izleyin: önce küçük bir plan isteyin, sonra tek bir değişikliği uygulatın, testleri çalıştırın ve diff’i inceleyin. Her prompt’tan sonra ajanın önerdiği diff’i `git diff` ile inceleyin; migration dosyalarını ayrıca `showmigrations` ile kontrol edin. Tek seferde büyük refactor istemek yerine model -> migration -> test olarak bölün. Ajan kendi kendine hata yaptığında düzeltme döngüsüne girebilir; ancak siz her aşamada onay verin.

Örnek promptlar:

- "Mevcut `Order` modeline `status` alanı ekle, migration’ı üret, admin ve DRF serializer’a yansıt. Testleri yaz ve çalıştır."
- "`ProductListView`'de N+1 sorguyu tespit et ve `select_related`/`prefetch_related` ile düzelt; açıklama ekle."
- "DRF’de `OrderCreateSerializer`'a stok kontrolü ekle; `ValidationError` fırlat, pytest ile iki senaryoyu test et."
- "Kullanıcı kayıt endpoint’ine throttle ekle; mevcut testleri bozma, yeni test ekle."
- "`apps/payments` için boş bir Django app oluştur; model, migration ve temel DRF viewset iskeletini kur."
- "`Book` ve `Author` modelleri arasındaki many-to-many ilişkiyi doğru yöneten bir DRF serializer yaz; nested create ve update desteklesin."
- "`Order` modelindeki `total_price` alanını computed property’ye çevir; migration’ı üretmeden admin ve API’yi güncelle."

Her prompt sonunda testleri çalıştırmasını isteyin; ajan test başarısızlıklarını kendisi analiz edip düzeltebilir, ancak son kararı siz verin. Migration üreten işlemlerde `makemigrations --check --dry-run` ile beklemediğiniz migration olmadığını doğrulayın. Bu prompt’ları kullanırken ajanın ilk önerdiği diff’i inceleyin; çoğu zaman küçük bir düzeltme gerekir. Ajan, `git status` ve `git diff` komutlarını da çalıştırabilir, bu sayede değişiklikleri özetlemesini isteyebilirsiniz.

## Hangi Django işlerinde iyi, nerelerde dikkatli olmalı?

Ajan birçok standart Django işini hızlı yapar; ancak bazı alanlarda genel Python bilgisi ile Django’nun özel davranışını karıştırabilir. Aşağıdaki tablo sık karşılaşılan görevleri ve dikkat edilecek noktaları özetler:

| Görev | Dikkat edilecek nokta |
|---|---|
| Model değişikliği ve migration | Ajan mevcut migration dosyasını düzenlemeye çalışabilir; her değişiklik için yeni migration üretmesini isteyin. |
| ORM sorgusu yazma | QuerySet’ler tembeldir; ajan sorguyu yanlış yerde tetikleyebilir. `django-debug-toolbar` veya `assertNumQueries` ile doğrulayın. |
| DRF serializer/viewset | İzinler, throttle ve filtreleme katmanlarını atlayabilir. Endpoint’i tarayıcıda veya testle yetki kontrolü yapın. |
| Template ve form | Ajan bazen iş mantığını template’e taşıyabilir; Django template dilinin kısıtlarını bilmeli, custom tag/filter tercih edilmeli. |
| pytest-django testleri | Fixture ve transaction yönetimi karışabilir; `@pytest.mark.django_db` kullanımını ve DB kurulumunu netleştirin. |

Bu tuzakların çoğu, ajanın migration üretimini atlaması veya mevcut migration’a elle alan eklemesinden kaynaklanır. Migration üretimini her zaman açıkça isteyin ve oluşan dosyayı inceleyin. Ayrıca, `select_related` kullanırken many-to-many veya reverse relation için `prefetch_related` gerektiğini ajan unutabilir; bu yüzden sorgu sayısını test edin. DRF’de `permission_classes`, `authentication_classes`, `throttle_classes` gibi ayarların unutulduğunu sık görürüz; endpoint’lerin yetki kontrolünü ayrıca test edin. Django admin tarafında ise model kaydı ve `list_display` gibi ayarlar eksik kalabilir; ajanın admin dosyasını güncellemesini isteyin. Özellikle `default` değeri değiştirirken mevcut veri için migration’da `RunPython` kullanılması gerekebilir; ajan bunu atlayabilir. Ayrıca `ManyToManyField` eklerken otomatik ara tablo oluşturulur ancak özel ara model gerekiyorsa `through` parametresi unutulabilir.

## Test ve doğrulama

Django’da ajan çıktısını kabul etmeden önce her zaman `pytest` çalıştırın. `pytest-django` kuruluysa, her testin veritabanı erişimi olup olmadığını belirtin; ajan bazen marker eklemeyi unutabilir. `pytest.ini` veya `pyproject.toml` içindeki `DJANGO_SETTINGS_MODULE` doğru tanımlanmış olmalı. Ajanın eklediği `select_related` veya `prefetch_related` sorgularının gerçekten N+1 çözüp çözmediğini `assertNumQueries` ile test edin. Migration’ların `makemigrations --check --dry-run` ile temiz olduğunu doğrulayın. DRF endpoint’lerinde yanıt şemasını ve yetki kontrollerini ayrı testlerle sabitleyin; otomatik üretilen testler çoğu zaman sadece 200 döndüğünü kontrol eder, yetkiyi atlar.

Aşağıdaki komutları sık kullanın:

- `pytest -x` : ilk hatada durur,
- `pytest --lf` : son başarısız testleri yeniden çalıştırır,
- `pytest apps/checkout/tests/test_orders.py::test_create_order` : tek bir testi çalıştırır.

Ajanın test yazarken doğru fixture ve factory kullanmasını sağlayın; `factory_boy` gibi kütüphaneler genellikle daha okunaklı test verisi üretir. Veritabanı durumunu testler arasında izole etmek için `django_db` marker’ına ek olarak `transaction=True` veya `serialized_rollback` gibi seçenekleri gerektiğinde kullanın. DRF testlerinde `APIClient` yerine `APITestCase` veya `pytest-django`'nun `client` fixture’ını kullanın; ajan bazen `django.test.Client` ile karıştırır. Ayrıca JWT veya token auth varsa, testlerde token üretimini doğru yapması için ona mevcut auth yardımcılarını tanıtın.

## Aynı Django projesinde birden fazla ajan çalıştırma

AgentVera, birden fazla ajanı paralel çalıştırma imkânı sunar; Django’da her birini ayrı git worktree’de çalıştırarak migration çakışmalarını önlersiniz. Ajan turu bittiğinde ikinci bir model otomatik review yapar, `select_related` eksikliği veya permission hatası gibi Django’ya özgü sorunları `file:line` ile işaretler. Checkpoint’ler sayesinde hatalı bir migration veya refactor tek tıkla geri alınır. Daha geniş karşılaştırma için [paralel kodlama ajanları için en iyi araçlar (2026)](/blog/paralel-yapay-zeka-kodlama-ajani-araclari/) yazısına göz atın.

## Sonuç

Cursor Agent, Django projelerinde model-migration-test döngüsünü hızlandırmak için güçlü bir araçtır; ancak ORM ve migration gibi alanlarda körü körüne kabul etmek yerine her adımı test ve diff ile doğrulamak gerekir. İyi yazılmış AGENTS.md kuralları, küçük adımlı planlama ve pytest-django ile sağlam bir iş akışı kurarsanız, ajan günlük Django işlerinizin büyük kısmını güvenle üstlenir. Ek olarak, birden fazla ajan kullanırken AgentVera gibi araçlarla worktree ve otomatik review eklerseniz, paralel çalışmanın risklerini azaltırsınız.

## Sık sorulanlar

**Cursor Agent Django projesinde migration’ları kendisi oluşturabilir mi?** Evet, python manage.py makemigrations komutunu çalıştırabilir ancak doğru model değişikliğini uyguladıktan sonra sizden onay bekler. Yine de migration’ları gözden geçirmek ve makemigrations --check ile doğrulamak gerekir.

**Cursor Agent’ı Django REST framework projelerinde nasıl kullanırım?** Serializer, viewset ve permission sınıflarını mevcut kod stiline göre yazmasını isteyebilirsiniz. Endpoint davranışını test etmek için pytest-django ile senaryolar hazırlayın ve ajanın testleri çalıştırmasını sağlayın.

**Cursor Agent Django testlerini çalıştırabilir mi?** Evet, proje kökünde pytest veya python manage.py test komutlarını terminal üzerinden çalıştırabilir. Hataları test çıktısına göre düzeltebilir, ancak testleri yazmadan önce hangi komutun kullanılacağını AGENTS.md’ye yazmalısınız.

**Cursor Agent ile Django’da en sık hangi hatalar yapılır?** Mevcut migration dosyasını düzenlemek, ORM sorgularını yanlış yerde tetiklemek ve DRF yetki kontrollerini atlamak tipik hatalardır. Bunları önlemek için küçük adımlar isteyin ve her değişikliği test ile doğrulayın.

---

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