opencode ile Django projelerinde verimli çalışma rehberi

opencode ile Django projesinde çalışmak, terminalde opencode komutunu çalıştırıp ajanın proje kökündeki AGENTS.md dosyasını okumasıyla başlar. Ajan, Django’nun model, migration, view, template, DRF ve test akışlarını dosya düzenleyerek ve python manage.py komutlarını çalıştırarak yürütür. Bu rehber, mevcut bir Django projesinde opencode’u güvenli ve verimli kullanmak için somut bir düzen sunar.

opencode Django işleri için neden uygun?

Django projeleri çok sayıda küçük ve birbiriyle ilişkili dosyadan oluşur: models.py, admin.py, serializers.py, views.py, urls.py, template’ler ve testler. opencode terminal içinde çalıştığı için python manage.py makemigrations, migrate, check, pytest gibi komutları doğrudan çalıştırabilir ve çıktıya göre sonraki adımı belirleyebilir. AGENTS.md sayesinde her oturumda komutları ve dizin kurallarını yeniden anlatmak gerekmez. Django işleri çoğu zaman zincirleme değişiklik ister: modele alan eklemek; migration, serializer, admin ve test güncellemesini gerektirir. opencode bu zinciri tek istekte yürütebilir, siz de git diff ile her aşamayı denetleyebilirsiniz.

Ajan ayrıca admin arayüzü geliştirmede, veri fixture’ları (loaddata) oluşturmada, özel yönetim komutları (management commands) yazmada ve custom template tag’leri eklemede oldukça pratiktir. Örneğin bir modelin list_display, search_fields ve list_filter ayarlarını yaparken admin.py dosyasını hızlıca güncelleyebilir, python manage.py check ile hataları anında görebilir. Django’nun ORM, migration graph ve test runner ile katı kuralları, ajanın işini daha öngörülebilir kılar; çünkü doğrulama komutları net ve tekrarlanabilirdir. Ayrıca collectstatic veya makemessages gibi rutin komutları da güvenle çalıştırabilirsiniz.

Projeyi ajan için hazırlamak: AGENTS.md

AGENTS.md dosyasını proje köküne ekleyin; opencode her çalıştırmada bu dosyayı okur. Kısa, kesin ve projeye özel ifadeler kullanın. Komutlar, gerçekte projede çalıştırdığınız haliyle yazılmalıdır. Django’ya özgü kuralları netleştirin; ajanın yanlış varsayım yapmasını önler. Örneğin:

# AGENTS.md

## Komutlar
- Kurulum: `pip install -r requirements/dev.txt`
- Test: `pytest --reuse-db -q`
- Lint: `ruff check . && ruff format --check .`
- Tip kontrolü: `mypy .`
- Migration üret: `python manage.py makemigrations`
- Migration uygula: `python manage.py migrate`
- Doğrulama: `python manage.py check && python manage.py makemigrations --check --dry-run`

## Dizin düzeni
- Uygulamalar `apps/<app_name>/` altında.
- Her app içinde `models.py`, `views.py`, `serializers.py`, `admin.py`, `urls.py`.
- Testler `<app>/tests/` paketinde, `test_*.py` dosyalarında.
- Şablonlar `<app>/templates/<app>/` altında; statikler `<app>/static/<app>/`.

## Django kuralları
- Migration dosyalarını elle değiştirme; yalnızca veri migration'ı için yeni dosya oluştur.
- ORM kullan; N+1 riskini önlemek için `select_related` / `prefetch_related` ekle.
- DRF'de `permission_classes` ve serializer doğrulamasını eksik bırakma.
- Kullanıcıya görünen metinleri `gettext_lazy` ile işaretle.
- Settings değerlerini ortam değişkenlerinden oku; sırları commit etme.

Bu dosyayı oluştururken model, migration ve test komutlarınızı tarif etmeniz yeterli; ajan geri kalanını proje kodundan öğrenir. Ayrıca env.example dosyanız varsa, ortam değişkenlerinin adlarını buraya ekleyin ki ajan yeni bir .env oluşturması gerektiğinde hangi anahtarların beklendiğini bilsin. Migration komutlarının yanına --noinput gibi bayrakları yazabilirsiniz; ancak dikkatli olun, çünkü bazı veri kaybı sorularında ajanın sormadan devam etmesini istemeyebilirsiniz. Lint ve tip kontrolü komutlarını ayrı satırlarda verin; birleştirilmiş komutlarda hata çıktıları karışabilir. Daha genel bir başlangıç için opencode nasıl kullanılır? Adım adım rehber içeriğine göz atabilirsiniz.

Çalışma döngüsü: plan, küçük adım, test, diff

Verimli bir döngü şöyle işler: önce ajanın ne yapacağını tek cümleyle netleştirin. Karmaşık bir iş ise önce plan istemek yararlıdır; ajan dosyaları listelesin ve değişiklik sırasını söylesin. Sonra tek bir küçük adımı uygulamasını isteyin. Ajan komutları çalıştırdıktan sonra siz git diff ile değişiklikleri inceleyin; özellikle migration dosyaları, settings.py ve URL yönlendirmeleri üzerinde durun. Son adımda test ve doğrulama komutlarını çalıştırın. Aşağıdaki örnek istekler bu döngüyü destekler:

• “apps/products/models.py içindeki Product modeline slug alanı ekle; migration üret ve testleri çalıştır.”
• “DRF’de ProductViewSet için list ve retrieve endpointlerini yaz; serializer’da category ilişkisini CategorySerializer ile göster.”
• “Order modeli için created_at üzerinde tarihe göre filtreleme ekle; sorgu parametresi date_from ve date_to olsun.”
• “apps/blog/templates/blog/post_detail.html şablonunda ilgili yazılar listesini ekle; view’de select_related ve prefetch_related kullan.”
• “pytest-django ile Product modeli için CRUD testleri yaz; pytest.mark.django_db kullan.”

Her istekten sonra ajanın yaptığı değişiklikleri git diff --stat ve git diff ile inceleyin. Karmaşık işleri tek seferde istemek yerine modele alan ekle, sonra serializer, sonra view gibi adımlara bölün. Bu, hataları erken yakalamanızı sağlar. Ajan testleri çalıştırırken --reuse-db kullanıyorsa, bazı durumlarda test veritabanı şeması güncellenmeyebilir; --create-db gerektiğinde isteği açıkça belirtin. Ayrıca ajanın migration üretmesini istediğinizde --dry-run çıktısını kontrol ederek gerçekten beklenen değişikliklerin yapıldığından emin olun.

Hangi Django görevlerinde iyi, nerelerde dikkatli olmalı?

Aşağıdaki tablo tipik görevler ile dikkat noktalarını özetler:

Yaygın tuzaklar şunlardır: ajan, settings.py içinde debug değerini değiştirmek gibi istenmeyen düzenlemeler yapabilir; bu yüzden settings.py değişikliklerini ayrıca gözden geçirin. Birden fazla app arasında model ilişkisi kurarken import sırasına dikkat etmez ve apps.get_model kullanılması gerekebilir; bu durumda hatayı siz fark edersiniz. Ayrıca veri migration’larında RunPython fonksiyonları için tersinir işlem (reverse) unutulabilir. Onun için migration dosyalarının reversible olmasına dikkat edin.

Ajan, karmaşık QuerySet’lerde len() ve count() arasındaki farkı karıştırabilir; büyük veri kümelerinde count() kullanması gerektiğini hatırlatın. Class-based view’lerde get_context_data override’ını bazen eksik yazar; template’te değişken hatası alırsanız bu noktayı kontrol edin. Django sinyalleri (post_save, pre_delete) eklerken transaction içinde mi çalıştığını düşünmeyebilir; sinyallerin yan etkilerini testlerle doğrulayın. Ayrıca ajan, UniqueConstraint veya CheckConstraint eklerken eski verilerin bu kısıtları sağlayıp sağlamadığını kontrol etmeden migration üretebilir; uygulamadan önce veri durumunu sorgulayın.

Test ve doğrulama

Her önemli değişiklikten sonra ajanın şu komutları çalıştırmasını isteyin: pytest --reuse-db -q, ruff check ., python manage.py check ve python manage.py makemigrations --check --dry-run. Son komut, modele ait migration dosyalarının eksik olup olmadığını gösterir. pytest --reuse-db veritabanını testler arasında yeniden kullanarak hız kazandırır; ancak bazen izolasyon sorunu oluşursa --create-db ekleyin. Ajan testleri yazarken pytest.mark.django_db işaretini eklemeyi unutabilir; test çıktısında hata görürseniz bu noktayı kontrol edin. DRF’de testler için APIClient ve force_authenticate kullandığınızdan emin olun.

Projenizde factory_boy veya model_bakery gibi araçlar varsa, AGENTS.md’ye bunları kullanmasını söyleyin; böylece test verisi üretimi hızlanır. Ajanın manage.py test yerine her zaman pytest kullanmasını açıkça belirtin; çünkü fixture’lar ve plugin’ler farklı çalışır. Testlerin isimlendirmesini de standartlaştırın: örneğin test_product_list_returns_200 gibi. Ayrıca coverage raporu almak isterseniz pytest --cov=apps --cov-report=term-missing komutunu ekleyebilirsiniz; ancak ajanın bu raporu otomatik yorumlamasını beklemeyin, kendiniz inceleyin.

Ajanın çalıştırdığı komutların çıktısını oturum içinde görürsünüz; hata durumunda ajan genellikle kendini düzeltmeye çalışır, ancak tekrar eden hatalarda adımı siz yönlendirin. Özellikle migration çakışmaları veya veritabanı bağlantı hataları gibi ortam sorunlarında ajanın önerdiği komutları dikkatle değerlendirin.

Birden fazla ajanla Django projesinde çalışma (AgentVera)

Django projesinde aynı anda birden fazla görevi izole etmek isterseniz AgentVera kullanışlıdır. Gerçek komut satırı araçlarını yan yana çalıştırdığı için opencode ile aynı terminal deneyimini korursunuz. Her ajan kendi git worktree’sinde çalışabildiği için model ve migration değişiklikleri birbirini ezmez; test çalıştırmak da temiz bir dalda güvenlidir. Otomatik kod incelemesi, DRF izinleri veya migration dosyalarındaki riskli satırları anında işaret eder. Token bütçeleri ile ajanın maliyeti kontrol altında kalır; böylece paralel çalışan ajanlar aynı veritabanı tanımı ve pytest --reuse-db komutlarıyla çakışmadan görev yürütür.

Sonuç

opencode, AGENTS.md ile yapılandırıldığında Django projelerinde günlük işleri hızlandıran pratik bir terminal ajanıdır. Özellikle model-migration-test zincirini küçük adımlar halinde yürütürken kontrolü sizde tuttuğunuzda faydası artar. Her değişiklikte git diff, pytest ve makemigrations --check --dry-run üçlüsünü uygulayın. Daha büyük veya paralel işler için AgentVera gibi araçlarla ajanları bölerek riski azaltabilirsiniz. Ajan seçimi konusunda opencode mu Claude Code mu? Dürüst bir karşılaştırma yazısına göz atabilirsiniz.