Claude Code ile FastAPI Geliştirme Rehberi

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 yazısına bakabilirsiniz; aşağıdaki örnek doğrudan bir FastAPI deposuna göre hazırlanmıştır.

# 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 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.

Ö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 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.