# Claude Code ile FastAPI Geliştirme Rehberi

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

Claude Code ile FastAPI projelerinde pratik çalışma rehberi: CLAUDE.md kurulumu, ajanla çalışma döngüsü, pytest ile testler ve sık düşülen tuzaklar.

**Kısaca:**

- CLAUDE.md içinde çalıştırma, test ve FastAPI kurallarını netleştirince ajan tutarlı kod üretiyor.
- Küçük adımlarla plan yapıp pytest ve TestClient ile doğrulamak FastAPI projelerinde en güvenli döngü.
- Bağımlılık enjeksiyonu, async endpoint ve Pydantic model değişikliklerinde diff ve testleri birlikte inceleyin.

[Claude Code](/ajanlar/claude-code/) ile FastAPI projelerinde terminalden `claude` komutuyla çalışan bir kodlama ajanıdır. Proje kökünde başlattığınızda dosyaları okur, değişiklik önerir, test ve lint komutlarını çalıştırır. Bu rehberde CLAUDE.md kurulumundan testli çalışma döngüsüne kadar pratik kullanımı anlatıyorum.

## Claude Code neden FastAPI işine uygun
FastAPI projeleri genellikle katmanlıdır: path operation’lar, Pydantic şemalar, servis fonksiyonları ve bağımlılık enjeksiyonu. Claude Code hem bu dosya ağacını gezebilir hem de tip ipuçları sayesinde bir endpoint’in girdisini, çıktısını ve bağımlılıklarını çıkarabilir. Örneğin `app/routers/users.py` içindeki bir endpoint’in `response_model=UserOut` kullandığını görür; `schemas.UserOut` modelini inceleyip günceller. TestClient tabanlı testleri çalıştırarak senkron test döngüsünü hızlandırır. Ayrıca FastAPI’nin açık tip sistemi sayesinde ajan, `Depends`, `Query`, `Body` ve `Path` parametrelerini doğru kullanma eğilimindedir. Büyük refactor’lerde ise önce etki analizi yaptırmak isabetli olur; ajan hangi dosyaların değişeceğini, hangi testlerin etkileneceğini listeleyebilir. Async/sync dönüşümlerinde dikkatli olmak gerekir, ancak doğru yönlendirmeyle ajan tipik CRUD akışlarını hızla tamamlar.

## Projeyi ajana hazırlama: CLAUDE.md
Claude Code proje kökündeki CLAUDE.md dosyasını okur. Bu dosya ne kadar net olursa ajan o kadar az yanlış komut üretir. FastAPI projesi için komutlar, dizin yapısı ve çerçeveye özel kurallar yazın. Sanal ortam adı, bağımlılık kurulumu, test ve lint komutları mutlaka yer almalı; aksi halde ajan yanlış Python ortamına kurulum yapabilir veya yanlış test komutu çalıştırabilir. Dizin yapısını açıkça belirtmek, ajanın yeni dosyaları doğru yerlere koymasını sağlar. FastAPI’ye özel kurallar kısmında `response_model` zorunluluğu, async/blocking I/O ayrımı, DI kullanımı ve test zorunluluğu gibi maddeler ekleyin. Temel başlangıç adımları için [Claude Code nasıl kullanılır](/blog/claude-code-nasil-kullanilir/) yazısına bakabilirsiniz; aşağıdaki örnek doğrudan bir FastAPI deposuna göre hazırlanmıştır.

```markdown
# CLAUDE.md

## Komutlar
- Sanal ortam: `source .venv/bin/activate`
- Kurulum: `pip install -e ".[dev]"`
- Test: `pytest -q`
- Lint: `ruff check app tests`
- Format: `ruff format app tests`

## Dizin yapısı
- `app/main.py`: FastAPI uygulaması ve router kayıtları
- `app/routers/`: path operation'lar
- `app/schemas/`: Pydantic modelleri
- `app/services/`: iş mantığı
- `app/dependencies.py`: bağımlılık enjeksiyonu

## FastAPI kuralları
- Her endpoint'te `response_model` belirt; Pydantic şemalarını `app/schemas/` altında tut.
- Async endpoint'lerde blocking I/O yapma; DB çağrıları için async sürücü kullan.
- Bağımlılıkları `Depends` ile yönet; global state'ten kaçın.
- Yeni endpoint eklerken TestClient ile test yaz; mevcut testleri bozma.
- Pydantic model değişikliği yaparken etkilenen endpoint ve testleri birlikte güncelle.
```

Bu dosyayı sürüm kontrolüne ekleyin. Ajan her oturumda aynı kuralları göreceği için tutarlı davranır. Ayrıca `.gitignore` içinde `.venv`, `__pycache__`, `.pytest_cache` gibi dizinlerin olduğundan emin olun; ajan bazen bu klasörleri tarayıp gereksiz dosyalar okuyabilir. `pyproject.toml` veya `requirements.txt` güncel olmalı; ajan bağımlılık ekleyecekse önce mevcut çevreyi kontrol etsin.

## Çalışma döngüsü ve örnek promptlar
Benim kullandığım döngü şöyle: önce ne yapılacağını küçük bir plan olarak isteyin, sonra tek bir dosya grubunu değiştirmesini söyleyin, ardından testleri çalıştırın ve diff’i inceleyin. Bu döngüyü [Claude Code en iyi pratikler](/blog/claude-code-en-iyi-pratikler/) yazısındaki kontrol listesiyle de birleştirebilirsiniz. Plan aşamasında ajanın hangi dosyaları değiştireceğini ve hangi komutları çalıştıracağını yazmasını isteyin; böylece sürpriz değişiklikleri önlersiniz. Küçük adımlar, özellikle Pydantic şemaları ve bağımlılık enjeksiyonu gibi birbiriyle bağlantılı parçalarda hata ayıklamayı kolaylaştırır. Her adımdan sonra `pytest -q` çalıştırın; ajan testlerin geçtiğini söylese bile çıktıyı kendiniz görün. Diff’i inceleyip yalnızca istenen değişikliklerin yapıldığını doğrulayın. Gerekirse ajanın önerdiği değişikliği geri alıp yeniden planlatın.

Örnek promptlar:

- `users` router’ına `GET /users/{user_id}` endpoint’i ekle. `response_model=UserOut` olsun, bulunamazsa `HTTPException(404)` döndür. `tests/test_users.py` içine iki TestClient testi yaz.
- `ItemCreate` Pydantic modeline `tax_rate: float = 0.0` alanını ekle. `POST /items` endpoint’ini ve ilgili testleri güncelle, sonra `pytest -q` çalıştır.
- `get_db` bağımlılığını async session kullanacak şekilde değiştir ve `items` router’ındaki DB çağrılarını async hale getir. Testleri çalıştırıp hataları düzelt.
- `ruff check` hatalarını düzelt, `ruff format` uygula ve değişen dosyaların kısa bir diff özetini çıkar.
- `GET /items?skip=0&limit=10` endpoint’ine pagination için `skip` ve `limit` parametrelerini `Query` ile ekle, varsayılan değerleri ve 100 üst sınırını koy. TestClient ile üç senaryo test et.

Bu promptlarda her zaman dosya yolunu ve beklenen davranışı açıkça belirtin. Ajan, belirsiz ifadelerde kendi yorumunu katabilir; özellikle Pydantic model adlarında ve endpoint yollarında net olun.

## Hangi işler iyi gider, nelere dikkat etmeli
İyi giden işler: yeni CRUD endpoint’leri, Pydantic şema güncellemeleri, DI refactor’leri, TestClient ile test yazımı ve OpenAPI dokümantasyonundaki eksikleri giderme. Ajan, tip ipuçları sayesinde `response_model`, `Depends` ve `Query`/`Body` parametrelerini genellikle doğru üretir. Örneğin `UserOut` modeli `id`, `email`, `is_active` içeriyorsa ajan bu alanları endpoint’te döndürmeyi unutmaz. Ayrıca hata durumları için `HTTPException` kullanımını ve durum kodlarını doğru seçer.

Dikkat edilmesi gereken yerler:

- Async/sync karışıklığı: Ajan `async def` endpoint içinde `SessionLocal()` gibi senkron DB oturumu açabilir. Bu, event loop’u bloklar; çözüm async sürücü veya `run_in_threadpool` kullanmaktır.
- `response_model` ile döndürülen nesne uyumsuzluğu: Ajan bazen ORM modelini doğrudan döndürür, ancak `response_model` Pydantic şeması bekler. FastAPI otomatik dönüştürür ama ilişkili alanlarda hata oluşabilir. `from_attributes = True` gerektiğini unutabilir.
- Bağımlılık enjeksiyonunda sıra hataları: Özellikle `Depends` içinde başka `Depends` kullanırken ajan parametre sırasını karıştırabilir; her bağımlılığın tekil ve test edilebilir olması gerekir.
- Test kapsamı düşük değişiklikler: Ajan sadece yeni endpoint ekleyip mevcut testleri çalıştırmadan bırakabilir. Her değişiklikte ilgili test dosyasını güncelleyip çalıştırdığını doğrulayın.
- Pydantic v2 davranış farkları: Ajan bazen v1 alışkanlıklarıyla `orm_mode` yazar; v2’de `from_attributes` kullanılır. CLAUDE.md içinde Pydantic sürümünü belirtin.

Ajan bazen yalnızca istediğiniz dosyayı değil, yanındaki yardımcıları da değiştirebilir; diff’i incelemeden kabul etmeyin. Ayrıca ajanın yeni bağımlılık eklemesi durumunda `pyproject.toml` veya `requirements.txt` dosyasını güncellediğinden emin olun.

## FastAPI için test ve doğrulama
Claude Code’a testleri çalıştırmasını söylemek yetmez; çıktıyı birlikte yorumlamak gerekir. Her değişiklikten sonra şu üç adımı uygulayın: testleri çalıştır, lint’i çalıştır, diff’i oku. TestClient, senkron test yazımını kolaylaştırır; async endpoint’ler için anyio eklentisi gerekebilir, ancak TestClient yine de uygulamayı sorunsuz test eder. Birim testler için servis fonksiyonlarını izole edin; bağımlılıkları `dependency_overrides` ile değiştirerek veritabanı olmadan test yazdırın. Ajan test yazarken bazen yalnızca mutlu yolu test eder; hata durumları, doğrulama hataları ve yetkilendirme senaryolarını açıkça isteyin.

| Kontrol | Komut / yöntem | Neden önemli |
|---|---|---|
| Testler | `pytest -q` | Endpoint davranışını ve Pydantic doğrulamasını yakalar |
| Lint / format | `ruff check app tests && ruff format --check app tests` | Stil ve statik hataları önler |
| Diff | `git diff` veya ajanın özeti | Ajanın yalnızca istenen alanı değiştirdiğini doğrular |
| Manuel TestClient | `from fastapi.testclient import TestClient` ile hızlı senaryo | Karmaşık DI veya async akışlarda ek güvence verir |

Özellikle async endpoint’lerde TestClient senkron çalışsa da uygulama async çalışır. Ajanın değiştirdiği DI fonksiyonlarını test eden mevcut testler yoksa mutlaka yazdırın. Testler geçtikten sonra `uvicorn` ile elle bir istek atmak da hızlı bir doğrulama sağlar. Ajan test çıktısını özetlerken bazen hataları gizleyebilir; `pytest -q` çıktısının tamamını isteyin veya kendiniz çalıştırın. Ayrıca coverage raporu almak için `pytest --cov=app --cov-report=term-missing` komutunu CLAUDE.md’e ekleyebilirsiniz; ajan bu çıktıya göre eksik testleri tamamlayabilir.

## Aynı FastAPI projesinde birden fazla ajanı AgentVera ile çalıştırma
FastAPI projelerinde bir ajan endpoint eklerken başka bir ajan şema veya testleri düzenleyebilir. AgentVera, Claude Code gibi CLI ajanlarını ayrı gerçek terminal panellerinde yan yana çalıştırır; her ajanı kendi git worktree’sine koyarak dosya çakışmalarını önler. Tur sonunda ikinci bir model otomatik kod incelemesi yapar ve bulgular `file:line` ile bağlanır. Checkpoint’ler sayesinde hatalı bir tur tek tıkla geri alınır; token bütçeleri ise FastAPI servisindeki uzun refactor’lerde maliyeti sınırlar. Böylece aynı FastAPI deposunda güvenle paralel ilerlenir. Paralel çalıştırma hakkında [Birden fazla Claude Code ajanını paralel çalıştırma](/blog/birden-fazla-claude-code-ajani/) yazısına bakabilirsiniz.

## Sonuç
Claude Code, FastAPI projelerinde CLAUDE.md ile yönlendirildiğinde güçlü bir yardımcı olur. Küçük adımlar, sürekli test ve diff incelemesiyle güvenli bir döngü kurarsınız. Async/sync ayrımı, Pydantic sürümü ve bağımlılık enjeksiyonu gibi FastAPI’ye özgü noktalara dikkat ederek ajanın hatalarını erkenden yakalayabilirsiniz. Birden fazla ajan gerektiren işlerde ise izole worktree ve checkpoint gibi önlemler işleri ölçeklendirir. Sonuç olarak, doğru talimatlarla Claude Code FastAPI geliştirme hızınızı belirgin şekilde artırabilir.

## Sık sorulanlar

**Claude Code FastAPI projesinde nasıl başlatılır?** Proje kökünde terminal açıp claude komutunu çalıştırın. Ajan, CLAUDE.md dosyasını okuyarak proje kurallarınızı uygular; böylece FastAPI yapısına uygun öneriler verir.

**Claude Code FastAPI endpoint eklerken TestClient ile test yazabilir mi?** Evet. Ajan, pytest ve TestClient kullanarak senkron testler yazabilir; async endpoint’ler için anyio veya pytest-asyncio gerekebilir. Testleri çalıştırıp çıktıyı ajanla birlikte değerlendirmek en sağlıklısı.

**Claude Code’a FastAPI projesinde hangi komutları öğretmeliyim?** CLAUDE.md içine sanal ortamı etkinleştirme, bağımlılık kurulumu, test (pytest), lint ve format komutlarını yazın. Böylece ajan her adımda aynı komutları kullanır ve ortamdan kopmaz.

**Claude Code async endpoint ve dependency injection hatalarını bulabilir mi?** Genellikle bulur; özellikle DI bağımlılıklarının sırası, async/await eksikleri ve Pydantic şema uyumsuzluklarını tespit eder. Yine de kritik değişiklikleri testlerle ve diff incelemesiyle doğrulamak gerekir.

---

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