Claude Code’u Flask projenizde kullanmak için proje klasöründe claude komutunu çalıştırın, CLAUDE.md dosyasına projeye özel kuralları yazın ve ajanı küçük, test edilebilir adımlarla yönlendirin. Bu rehber blueprint, application factory, Jinja, SQLAlchemy ve pytest kullanan projelerde pratik bir çalışma düzeni sunar; ajanın güçlü olduğu alanları ve dikkat edilmesi gereken Flask tuzaklarını ele alır.
Neden Claude Code Flask projelerine uygun
Flask’ın açık yapısı Claude Code için avantajdır. Route tanımları, blueprint kayıtları ve create_app fabrikası genellikle küçük ve okunaklı dosyalardadır; ajan bu dosyaları hızla tarayıp değişiklikleri hedefleyebilir. Jinja şablonları ile view fonksiyonları arasındaki veri akışı, SQLAlchemy modelleri ve config sınıfları da metin tabanlı olduğundan ajanın bağlam kurması kolaydır. Ayrıca pytest fixture’ları sayesinde ajan, yazdığı testleri aynı oturumda çalıştırıp sonucu görebilir. Uygulama bağlamı, request bağlamı ve g nesnesi gibi kavramlar kodda açıkça göründüğü için ajan bu yapıları öğrenip mevcut desenlere uygun kod üretebilir. Ajan, app/__init__.py dosyasındaki create_app yapısını okuyarak blueprint kayıtlarını ve uzantı başlatma sırasını anlayabilir; böylece yeni bir blueprint eklerken doğru yere kayıt ekleyebilir. SQLAlchemy oturum yönetimi ve model ilişkileri gibi konularda da mevcut desenleri taklit eder. Jinja şablonlarındaki blok yapısı, ajanın template inheritance kullanarak yeni sayfalar oluşturmasını kolaylaştırır. Ayrıca ajan, git diff çıktısını kendi ürettiği değişikliklerle karşılaştırabilir ve yanlışlıkla bozulan dosyaları hızla fark edebilir. Bu özellikler, Flask projelerinde sık tekrarlanan CRUD ekranları, form doğrulama ve basit API endpoint’leri için büyük zaman kazandırır. Temel kullanım için Claude Code sayfasına bakabilirsiniz.
Projeyi ajan için hazırlama ve CLAUDE.md
Claude Code proje kökündeki CLAUDE.md dosyasını otomatik okur. Bu dosyaya Flask’a özgü komutları, klasör düzenini ve davranış kurallarını yazmak ajanın tahmin yürütmesini azaltır. Projede .env ile yüklenen değişkenler, test veritabanı URI’si, flask CLI hedefi ve kullanılan pytest plugin’leri de burada belirtilebilir. Aşağıdaki örnek, application factory ve blueprint kullanan tipik bir yapıyı özetler:
# CLAUDE.md
## Proje komutları
- Kurulum: `pip install -e .`
- Test: `pytest -q`
- Lint: `ruff check .`
- Çalıştırma: `flask --app wsgi:app run --debug`
## Klasör yapısı
- `app/`: uygulama paketi
- `app/blueprints/`: her özellik için ayrı blueprint
- `app/templates/`: Jinja şablonları
- `app/static/`: statik dosyalar
- `tests/`: pytest testleri
## Flask kuralları
- Yeni özellikler `app/blueprints/` altına bir blueprint olarak eklenir ve `app/__init__.py` içindeki `create_app` fonksiyonuna kaydedilir.
- SQLAlchemy modelleri `app/models.py` içinde tutulur; migration dosyaları elle düzenlenmez.
- Testler `tests/conftest.py` içindeki `app` ve `client` fixture'larını kullanır; her test kendi verisini oluşturur.
- Jinja şablonlarında iş mantığı yazılmaz; gerekli veriler view fonksiyonunda hazırlanıp template context'ine eklenir.
- Değişiklik sonrası mutlaka `pytest -q` ve `ruff check .` çalıştırılır.Bu dosyadaki flask --app wsgi:app run --debug komutu, projenin nasıl ayağa kaldırılacağını gösterir. Eğer uygulama fabrikası farklı bir modülde ise yolu güncelleyin. Test komutunda -q bayrağı önemlidir; ajan kısa çıktıyı daha kolay yorumlar. Lint komutu olarak ruff check . yaygındır; projenizde black veya flake8 varsa onları yazın. Klasör yapısı kısmı, ajanın yeni dosyaları nereye koyacağını bilmesini sağlar. Flask kuralları bölümünde ise projeye özgü kısıtlar netleştirilir. Örneğin: ‘Model değişikliklerinde önce migration scripti oluşturmak için flask db migrate kullan, ama migration dosyasını elle düzenleme.’ gibi bir kural ekleyebilirsiniz. Ajan bu kurallara uyduğunda üretilen kod tutarlı olur.
Ayrıca .env dosyasındaki DATABASE_URL, FLASK_APP ve FLASK_ENV gibi değişkenleri açıklayan bir bölüm eklemek, testlerin neden farklı veritabanına bağlandığını anlamasına yardımcı olur. CLAUDE.md dosyası kısa ve kesin olmalı; uzun paragraflar yerine madde işaretleri tercih edin. Ajan ilk başlatıldığında bu dosyayı okur; siz de her yapısal değişiklikte güncellerseniz, ajanın bağlamı taze kalır. Yeni bir blueprint eklediğinizde klasör listesini ve kayıt kuralını güncellemeyi unutmayın.
Çalışma döngüsü ve örnek görev komutları
Güvenli bir Flask geliştirme döngüsü şöyle ilerler: önce ajanın ilgili dosyaları incelemesini ve kısa bir plan yazmasını isteyin; ardından tek bir sorumluluğu olan küçük bir değişiklik yaptırın; ajan testleri çalıştırsın; sonucu birlikte inceleyin; git diff ile değişiklikleri gözden geçirin. Bu döngü, Flask’ta sık görülen bağlam hatalarını ve import döngülerini erken yakalar. Aşağıdaki örnek komutlar Türkçe yazılmış tipik görevlerdir:
"app/blueprints/auth.py dosyasındaki login view'ini incele ve hata mesajlarını Türkçeleştir, testlerini de güncelle.""Yeni birdashboardblueprint'i oluştur,create_appiçine kaydet, basit bir index template ekle ve bir pytest testi yaz.""SQLAlchemy modelindekiUsersınıfınais_activeboolean alanı ekle; migration oluşturma, sadece modeli ve gerekli testleri güncelle.""Mevcutlist_productsview'ini incele ve N+1 sorgu varsaselectinloadkullanarak düzelt; testleri çalıştır.""Jinja şablonundaki formu Flask-WTF kullanacak şekilde yeniden yaz ve CSRF token'ını ekle, testleri güncelle."
Her görevden sonra ajanın ürettiği diff’i inceleyin; özellikle app/__init__.py, models.py ve wsgi.py gibi kritik dosyalarda beklenmedik değişiklik olup olmadığını kontrol edin. Ajan bazen sadece sizin istediğiniz değişikliği yapmak yerine formatlama veya import sıralaması gibi ek düzenlemeler yapabilir; bunları ayrı bir commit’te tutmak daha temiz olur. Plan aşamasını zorunlu kılmak için ‘önce plan yap ve onayımı bekle’ diyebilirsiniz; Claude Code plan modu: önce planla, sonra yaptır sayfasındaki örnekler bu konuda yardımcı olur.
Hangi Flask görevlerinde iyi, nerelerde dikkatli olmalı
Claude Code, aşağıdaki tabloda özetlenen tipik Flask işlerinde güvenilirdir; ancak her alanda insan gözetimi gerekir.
| Görev alanı | İyi olduğu durumlar | Dikkat edilecek noktalar |
|---|---|---|
| Blueprint ve route yapısı | Yeni blueprint ekleme, kayıt, url kuralları | Blueprint isim çakışmaları, import döngüleri |
| Jinja şablonları | Template inheritance, form rendering, filtreler | İş mantığını template’e taşıması, güvenli olmayan değişken çıktısı |
| SQLAlchemy | Model tanımları, basit sorgular, ilişki yapılandırma | Lazy loading, N+1, transaction yönetimi, migration dosyalarını elle değiştirme |
| pytest | Fixture kullanımı, test client ile istekler | Test veritabanını kirletme, app context doğru kurulmaması |
| Hata yakalama ve loglama | Genel hata yakalayıcılar, form doğrulama | Flask context dışında request veya g kullanımı, hata mesajlarının sızdırması |
Ajanın en sık yaptığı hatalardan biri, request veya g nesnesini request context dışında kullanmaktır. Örneğin bir helper fonksiyonuna request.args.get('q') eklemek, test dışında patlayabilir. Ajan bu tür bir kodu ürettiğinde testler geçse bile production’da RuntimeError verebilir; bu yüzden kritik yollar için request context içinde kalındığından emin olun. SQLAlchemy ile ilgili olarak, ajan db.session.commit() çağrısını döngü içinde tekrar tekrar yapabilir veya db.session.remove() eklemeyi unutabilir. Testlerde bu, oturumlar arası veri sızıntısına yol açar. Ayrıca ajan migration dosyalarını elle düzenlemeye çalışabilir; CLAUDE.md’ye ‘migration dosyalarını elle değiştirme, flask db migrate ve flask db upgrade kullan’ şeklinde açık bir kural koyun. Jinja tarafında ise ajan, kullanıcı girdisini | safe filtresiyle işaretlemek isteyebilir; bunu yalnızca gerçekten güvenli HTML için izin verin, aksi halde kaçışı koruyun. URL oluştururken url_for kullanımına dikkat edin; ajan bazen endpoint adını yanlış yazabilir. Bu yüzden route değişikliklerinde route listesini flask routes ile doğrulayın.
Flask’ta test ve doğrulama
Claude Code, test komutlarını çalıştırabilir; ancak son karar sizindir. Ajanın değişiklik yaptığı her oturumun sonunda pytest -q ve ruff check . komutlarını siz de çalıştırın. Testlerin tests/conftest.py içindeki fixture’lara dayandığından emin olun; ajan yeni bir test eklerken fixture’ı kullanmazsa veritabanı kirlenebilir. Ayrıca flask --app wsgi:app routes gibi komutlarla route listesini kontrol edebilirsiniz. Ajan, testlerin geçtiğini söylese bile git diff --stat ile hangi dosyaların değiştiğini görün ve kritik dosyaları (app/__init__.py, models.py, wsgi.py) ayrıca inceleyin. Claude Code en iyi pratikler: uygulamalı kontrol listesi sayfasındaki kontrol listesi bu süreci sistematikleştirir.
Test kapsamını artırmak için ajandan yeni eklenen bir endpoint için hem başarılı hem hata durumlarını kapsayan testler yazmasını isteyebilirsiniz. Örneğin: ‘Yeni kayıt endpoint’i için 201, 400 ve 401 durumlarını test eden pytest testleri ekle.’ gibi. Ajan testleri çalıştırdığında çıktıyı sizinle paylaşır; siz de pytest -q tests/test_auth.py -k login gibi daraltılmış komutlarla tekrar doğrulayın. Ayrıca pytest --cov=app --cov-report=term-missing komutuyla eksik kalan satırları görebilirsiniz; bu raporu ajana vererek eksik testleri yazdırabilirsiniz. Flask uygulamasının başlatılmasında sorun varsa flask --app wsgi:app shell ile interaktif kabukta importları test edebilirsiniz. Son olarak, her oturum sonunda git status ile beklenmeyen dosya eklenip eklenmediğini kontrol edin.
Birden fazla ajanı Flask projesinde çalıştırma
Aynı Flask projesinde birkaç ajanı paralel çalıştırmak istiyorsanız AgentVera iyi bir seçenektir; çünkü her ajan gerçek komut satırı araçlarını kendi terminal panelinde çalıştırır ve ajanlar kendi git worktree’lerinde izole çalışabilir. Böylece dosya çakışması yaşanmaz; ayrıca bir ajanın işi bittiğinde ikinci bir model kodunu otomatik inceleyip bulguları dosya ve satır bazında bildirir. Flask projelerinde context hataları ve bozuk blueprint kayıtları bu inceleme sayesinde hızla yakalanır. Bu çok ajanlı akışı Birden fazla Claude Code ajanını paralel çalıştırma yazısında daha detaylı görebilirsiniz.
Sonuç
Claude Code, Flask projelerinde disiplinli bir çalışma arkadaşıdır: CLAUDE.md ile projeyi tanıtın, küçük adımlarla ilerleyin, testleri sürekli çalıştırın ve her diff’i inceleyin. Bu rehberdeki döngüyü uyguladığınızda ajan, blueprint, Jinja ve SQLAlchemy işlerinde hız kazandırır; siz de mimari kararlara odaklanırsınız. Unutmayın, ajan bir araçtır; Flask’ın inceliklerini bilen bir geliştirici olarak son kontrolü siz yapmalısınız.