# Cursor Agent ile FastAPI Geliştirme Rehberi

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

Cursor Agent ile FastAPI projelerinde test odaklı geliştirme yapın. Ajana kuralları verin, küçük adımlarla çalışın, TestClient ile doğrulayın.

**Kısaca:**

- Cursor Agent, FastAPI projelerinde route, Pydantic modeli ve DI eklerken net kurallarla verimli çalışır.
- AGENTS.md içinde test, lint ve klasör kuralları belirtmek ajanın projeye uyumunu artırır.
- Her değişiklikten sonra pytest ve TestClient ile doğrulayıp diff’i gözden geçirmek gerekir.

Cursor Agent, FastAPI projelerinde terminalden çalışan ve [Cursor Agent](/ajanlar/cursor-agent/) sayfasında anlatılan ajanı `cursor-agent` komutuyla başlatır. FastAPI’nin açık route, Pydantic ve DI yapısı, ajanın küçük değişiklikleri hızlı üretmesine uygundur. Bu rehberde ajanı FastAPI projesine nasıl bağlayacağınızı, hangi kurallarla yönlendireceğinizi ve nasıl güvenle test edeceğinizi göreceksiniz.

## Cursor Agent FastAPI işleri için neden uygun?

FastAPI projeleri, endpoint tanımları, Pydantic şemaları ve bağımlılık enjeksiyonu gibi tekrarlayan ama kurallara bağlı parçalardan oluşur. Cursor Agent bu parçaları proje bağlamında üretmekte iyidir; `APIRouter` yapısını, `Depends` zincirlerini ve `response_model` kullanımını mevcut koddan öğrenir. Async endpoint’lerde `async def` ve `await` düzenini tutarlı biçimde uygular. Örneğin, `items` router’ında `GET /items/{item_id}` endpoint’i varsa, `POST /items` eklerken aynı hata yaklaşımını, yanıt modelini ve bağımlılıkları taklit eder. Bu, projede tutarlılığı korur. En büyük fayda, sıfırdan büyük dosya yazmasını istemek yerine küçük, doğrulanabilir parçalar istemektir. Ayrıca Pydantic v2 geçişi gibi tekrarlayan refactor işlerinde ajan, `orm_mode` yerine `from_attributes=True` dönüşümünü hızlıca yapar ve OpenAPI şemasını bozmadan ilerler. Bu tür mekanik ama dikkat gerektiren işler, ajanın güçlü olduğu alanlardır.

## Projeyi ajan için hazırlama: AGENTS.md ve .cursor/rules

FastAPI projelerinde ajanın doğru çalışması, proje kurallarının net olmasına bağlıdır. Kök dizinde `AGENTS.md` veya `.cursor/rules` altında bir dosya oluşturup şunları yazın: paket yöneticisi ve test/lint komutları, klasör düzeni, Pydantic model adlandırma kuralları, DI kullanımı, async zorunluluğu ve test beklentileri. Aşağıdaki örnek gerçek bir FastAPI projesi için yeterli başlangıç talimatıdır.

```markdown
# FastAPI projesi için ajan talimatları

## Komutlar
- Bağımlılık kurulumu: `uv sync`
- Test: `pytest -q`
- Lint: `ruff check .`
- Format: `ruff format .`

## Klasör düzeni
- `app/main.py`: FastAPI uygulaması
- `app/routers/`: path operations
- `app/schemas.py`: Pydantic modeller
- `app/services/`: iş mantığı
- `app/db.py`: veritabanı bağlantısı ve DI
- `tests/`: pytest dosyaları

## FastAPI kuralları
- Tüm endpoint’ler async ve `APIRouter` kullan.
- Pydantic modellerde `from_attributes=True` gerekiyorsa kullan.
- DI bağımlılıklarını `Depends` ile enjekte et; global çağırma.
- İstek ve yanıt şemaları ayrı olsun: `*Create`, `*Read`, `*Update`.
- Her endpoint için en az bir başarı ve bir hata testi yaz.
```

Bu dosya sayesinde ajan, `uv sync` ile kurulum yapmayı, testleri `pytest -q` ile çalıştırmayı ve `ruff` ile denetlemeyi bilir. Klasör düzeni netleşince, yeni bir endpoint isteğinde dosyayı nereye koyacağını tahmin etmez; `app/routers/` altına ekler. FastAPI’ye özel kurallar ise Pydantic v2 uyumu ve DI düzenini korur. `AGENTS.md` yerine `.cursor/rules` altında birden fazla kural dosyası tutmak büyük projelerde daha iyidir; örneğin `fastapi.md` adında endpoint ve şema kuralları, `testing.md` adında test beklentileri ayrı dosyalarda olabilir. Ajan, değişiklik yapmadan önce bu dosyaları okuduğu için tutarlılık artar. Kurallar eksikse ajan, kendi varsayımlarıyla çalışır ve projede uyumsuz desenler üretebilir; örneğin sync endpoint yazabilir veya Pydantic v1 stilini tercih edebilir. Temel Cursor CLI kullanımı için [Cursor CLI nasıl kullanılır? Adım adım rehber](/blog/cursor-cli-nasil-kullanilir/) sayfasına bakabilirsiniz; burada proje talimatlarına odaklanıyoruz.

## Çalışma döngüsü: planla, küçük adım at, test et, diff’i oku

Cursor Agent ile verimli çalışma döngüsü şöyle kurulur: önce ajanı plan moduna alıp hangi dosyaları değiştireceğini, hangi Pydantic şemalarını etkileyeceğini yazdırın. Plan modunda ajan, değişiklik yapmadan önce dosya listesi ve test planı sunar; bu özellikle `Depends` zincirinin değişeceği işlerde faydalıdır. Plan onaylandıktan sonra tek bir küçük iş isteyin; örneğin sadece yeni bir router dosyası ekleyin. Değişiklikten sonra `pytest -q` çalıştırın, ardından `git diff` ile ajanın eklediği kodun tamamını gözden geçirin. Diff incelemesinde `app/routers/` dışındaki değişikliklere özellikle bakın; yanlışlıkla `main.py` veya `db.py` üzerinde beklenmedik düzenleme yapmış olabilir. FastAPI’ye özgü olarak `response_model` uyumu, DI sıralaması ve async/sync tutarlılığını kontrol edin. Bir sonraki adıma geçmeden önce testlerin yeşil olduğundan emin olun. Ajanın ürettiği kodu küçük commit’ler halinde kaydedin; böylece hata durumunda geri almak kolaylaşır. Özellikle birden fazla endpoint içeren bir istek, ajanın dikkatini dağıtabilir; tek endpoint + test ikilisi üzerinde çalışmak en verimlisidir.

Tipik FastAPI görevleri için kullanabileceğiniz Türkçe prompt örnekleri:

- Yeni bir `orders` router’ı ekle: `GET /orders` ve `POST /orders` endpoint’leri olsun. Pydantic `OrderCreate` ve `OrderRead` şemalarını tanımla; `OrderRead` içindeki `id` ve `created_at` alanlarını response_model olarak kullan. Testleri `tests/test_orders.py` içine TestClient ile yaz.
- Mevcut `GET /items` endpoint’ine `skip` ve `limit` query parametreleri ekle; varsayılan 0 ve 20 olsun, üst sınır 100 olsun. Aynı dosyada sayfalama için iki test ekle.
- `get_current_user` bağımlılığını `Depends` ile kullanan bir endpoint yaz. Bu bağımlılık `Authorization` header’ından JWT çözsün. Testte `app.dependency_overrides` ile sahte kullanıcı döndür.
- Pydantic v1’den v2’ye geçişte `orm_mode` yerine `from_attributes=True` kullanacak şekilde `Item` modelini güncelle ve tüm testlerin geçtiğini doğrula.
- Uygulamaya CORS middleware’i ekle; sadece `settings.DEBUG` true iken `allow_origins=['*']` olsun, production’da belirli origin listesi kullan.
- `GET /users/me` endpoint’inin yanıtını `response_model=UserRead` ile döndür; `password_hash` alanı yanıtta görünmesin. Mevcut testi güncelle ve yeni bir hata testi ekle.
- `APIRouter` prefix’lerini `main.py` içinde `include_router` ile ayarla; her router kendi prefix’ini kendi dosyasında değil, include sırasında alsın. Bu kuralı testlerle doğrula.

## Cursor Agent hangi FastAPI işlerini iyi yapar, nerelerde dikkat ister?

Aşağıdaki tablo, ajanın güçlü olduğu ve riskli olduğu alanları özetler.

| Görev | Güçlü yönü |
| --- | --- |
| Yeni endpoint ve router | İyi; mevcut kalıpları kopyalar |
| Pydantic şemaları | İyi; alan tiplerini ve doğrulamayı üretir |
| DI ve `Depends` zincirleri | Orta; sıralamayı bazen karıştırır |
| TestClient ile test yazma | İyi; başarı ve hata durumlarını kapsar |
| Async dönüşümler | Riskli; `async`/`sync` karışabilir |

Ajanın iyi olduğu yerler: yeni `APIRouter` eklemek, Pydantic modellerini mevcut örneklerden türetmek, basit CRUD endpoint’lerini testleriyle birlikte yazmak, dependency override’ları test etmek. Dikkat edilmesi gerekenler: async endpoint’in içinde senkron veritabanı çağrısı yapmak, `Depends` sıralamasını bozmak, `response_model` ile dönen şemayı uyumsuz bırakmak, Pydantic v2’de `orm_mode` kalıntısı bırakmak, `TestClient` ile async bağımlılıkları test ederken event loop sorunları yaratmak. Özellikle middleware sıralaması ve lifespan olayları ajanın kafasını karıştırabilir; production kodunda bu kısımları elle kontrol edin. Ajan, `Query` veya `Path` parametrelerinin `description` ve `example` alanlarını bazen atlayabilir; OpenAPI dokümantasyonu için bunları kontrol edin. Ayrıca `Depends` ile cache kullanımı (`use_cache=False`) gibi ince ayarları kendiliğinden eklemez; talimat vermezseniz varsayılan davranışı kullanır. Bu hataları yakalamak için her değişiklikten sonra OpenAPI şemasını `app.openapi()` ile kontrol edin ve tüm testleri çalıştırın.

## Test ve doğrulama: FastAPI’de ajanla güvenli çalışma

Agent test yazsa bile, testleri siz çalıştırmadan güvenmeyin. Standart akış şudur: değişiklik sonrası `pytest -q` çalıştırın; ilk hatada durdurmak için `pytest -q -x` kullanın. `TestClient` senkron bir sarmalayıcı olduğu için çoğu endpoint testi yeterlidir; ancak gerçek async davranışı görmek istediğinizde `httpx.AsyncClient` ve `ASGITransport` ile test yazabilirsiniz. Ajanın eklediği test dosyalarını inceleyin; `app.dependency_overrides` kullanıyorsa test sonunda `clear()` yapıldığından emin olun. Lint olarak `ruff check .` çalıştırın; ajan bazen kullanılmayan import bırakabilir. Eğer mypy kullanıyorsanız, `mypy app` ile tip hatalarını yakalayın. Son olarak `git diff` çıktısında sadece istediğiniz değişikliklerin olduğunu doğrulayın; özellikle `response_model` eksik veya yanlış Pydantic şemasıyla üretilmiş endpoint’leri arayın. Ajanın testleri doğru yazıp yazmadığını doğrulamak için test kapsamını `pytest --cov=app --cov-report=term-missing` ile kontrol edebilirsiniz. Yeni eklenen endpoint’in hem başarılı yanıtı hem de 4xx/5xx hatalarını test ettiğinden emin olun. Ajan, bazen sadece olumlu durum test eder; hata durumlarını siz ekleyin veya açıkça isteyin. Uygulama başlangıcında `lifespan` ile kaynak yönetimi varsa, `TestClient` ile lifespan’ın tetiklendiğini test edin; ajan bu kısmı atlayabilir. Her şey yeşilse, OpenAPI şemasını `/docs` üzerinden gözle inceleyip şemaların beklediğiniz gibi olduğunu doğrulayın.

## Birden fazla ajanı aynı FastAPI projesinde çalıştırma

FastAPI projesinde route’ları modüllere ayırdıysanız, birden fazla ajanı paralel çalıştırmak hız kazandırır. AgentVera, Cursor Agent dahil farklı CLI ajanlarını tek pencerede gerçek terminallerde yan yana çalıştırır. Her ajan kendi git worktree’sinde çalışabildiği için dosyalar çakışmaz; ayrı token bütçeleri, Pydantic şema refactorü gibi denemelerin maliyetini sınırlar. Tur sonunda otomatik kod incelemesi, `response_model` eksikleri veya DI override sızıntılarını bulur ve file:line ile gösterir. Bu, FastAPI projelerinde güvenli paralel geliştirme için önemlidir.

## Sonuç

Cursor Agent, FastAPI projelerinde net AGENTS.md kuralları ve küçük adımlı çalışma döngüsüyle güvenilir bir yardımcıdır. Testleri her değişiklikte çalıştırıp diff’i incelemek, FastAPI’ye özgü async, DI ve Pydantic hatalarını önler. Birden fazla ajanı paralel kullanmak istediğinizde AgentVera gibi araçlar worktree ve kod incelemesiyle süreci disipline eder.

## Sık sorulanlar

**Cursor Agent FastAPI projesinde nasıl başlatılır?** Proje klasöründe terminalden cursor-agent komutunu çalıştırın. İlk turda ajan, kök dizindeki AGENTS.md veya .cursor/rules dosyasını okuyup talimatlara göre hareket eder.

**Cursor Agent FastAPI endpoint’lerini otomatik oluşturabilir mi?** Evet, doğal dilde path operation, Pydantic şeması ve DI tanımı isteyebilirsiniz. Ancak üretilen kodu test etmeden ve diff’i incelemeden kabul etmeyin.

**Cursor Agent ile pytest testleri yazdırabilir miyim?** Evet, mevcut endpoint’ler için TestClient kullanan testler yazdırabilirsiniz. Özellikle başarı ve hata durumları için ayrı testler istemek faydalıdır.

**Cursor Agent FastAPI’de en çok nerede hata yapar?** Async/sync karışıklığı, Depends sıralaması, Pydantic v2 geçişi ve response_model uyumsuzluğu sık görülür. Bu yüzden her adımda test çalıştırıp git diff inceleyin.

---

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