Cursor Agent ile FastAPI Geliştirme Rehberi

Cursor Agent, FastAPI projelerinde terminalden çalışan ve 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.

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

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.