# Claude Code ile Flask Projeleri: Pratik Rehber

Adres: https://agentvera.dev/blog/claude-code-ile-flask/ · Yayın: 2026-11-01

Claude Code ile Flask projelerinde planlama, test ve güvenli değişiklik döngüsünü CLAUDE.md, blueprint, SQLAlchemy ve pytest odaklı pratik bir rehberle öğrenin.

**Kısaca:**

- Claude Code, Flask projelerinde blueprint, Jinja ve SQLAlchemy değişikliklerini küçük, test edilebilir adımlarla güvenle yapabilir.
- Proje kökündeki CLAUDE.md dosyasına komutlar, klasör kuralları ve Flask’a özgü kısıtlar yazmak ajanın doğruluğunu artırır.
- Her değişiklikten sonra pytest ve diff incelemesi yapmak, Flask bağlam hatalarını ve yanlış migration düzenlemelerini erken yakalar.

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](/ajanlar/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:

```markdown
# 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 bir `dashboard` blueprint'i oluştur, `create_app` içine kaydet, basit bir index template ekle ve bir pytest testi yaz."`
- `"SQLAlchemy modelindeki `User` sınıfına `is_active` boolean alanı ekle; migration oluşturma, sadece modeli ve gerekli testleri güncelle."`
- `"Mevcut `list_products` view'ini incele ve N+1 sorgu varsa `selectinload` kullanarak 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](/blog/claude-code-plan-modu/) 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](/blog/claude-code-en-iyi-pratikler/) 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](/blog/birden-fazla-claude-code-ajani/) 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.

## Sık sorulanlar

**Claude Code Flask projesinde nasıl başlatılır?** Proje klasöründe terminalden claude komutunu çalıştırmanız yeterlidir. Ajan önce CLAUDE.md dosyasını okur; yoksa mevcut dosyaları inceleyerek bağlam oluşturur. İlk görevi vermeden önce proje komutlarını ve kurallarını CLAUDE.md içinde tanımlayın.

**CLAUDE.md dosyasına Flask için neler yazılmalı?** Test, lint ve çalıştırma komutlarını; blueprint ve model dosyalarının konumlarını; application factory ve SQLAlchemy oturum yönetimi gibi projeye özgü kuralları yazın. Ayrıca migration dosyalarının elle düzenlenmemesi ve testlerde fixture kullanımı gibi kısıtları belirtin.

**Claude Code Flask testlerini çalıştırabilir mi?** Evet, ajan terminalde pytest -q gibi komutları çalıştırabilir ve çıktıyı yorumlayarak hataları düzeltebilir. Siz de her değişiklikten sonra testleri kendiniz çalıştırıp git diff ile değişiklikleri gözden geçirmelisiniz.

**Claude Code ile birden fazla ajan aynı Flask projesinde güvenle çalışabilir mi?** Evet, ancak aynı çalışma dizininde aynı anda birden fazla ajan dosya çakışması yaratabilir. Her ajanı kendi git worktree’sinde çalıştırmak veya AgentVera gibi bir arayüz kullanmak güvenliği artırır; otomatik kod incelemesi Flask bağlam hatalarını yakalar.

---

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