# opencode ve FastAPI ile Pratik Geliştirme Rehberi

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

opencode ile FastAPI projelerinde pratik çalışma rehberi: AGENTS.md kurulumu, pytest ve TestClient döngüsü, endpoint ve Pydantic model görevleri, sık tuzaklar.

**Kısaca:**

- opencode, FastAPI projelerinde AGENTS.md ile konvansiyonları öğrenir; görevleri küçük adımlara bölüp pytest ile doğrulamak en verimli yöntemdir.
- Endpoint değişikliklerinde response_model ve TestClient testleri birlikte çalıştırılarak Pydantic ve DI hataları erken yakalanır.
- Paralel çalışmalarda git worktree, otomatik kod incelemesi ve token bütçeleri FastAPI refactor riskini düşürür.

[opencode](/ajanlar/opencode/)'i FastAPI proje klasöründe `opencode` komutuyla başlatın; ajan proje talimatlarını AGENTS.md’den okur ve endpoint, Pydantic model ile dependency injection değişikliklerini küçük adımlarla yapar. Her adımdan sonra `pytest` ile TestClient testlerini çalıştırıp diff’i incelemek en güvenli çalışma biçimidir. Ayrıca ayrıntılı genel kullanım için [opencode nasıl kullanılır? Adım adım rehber](/blog/opencode-nasil-kullanilir/) sayfasına bakabilirsiniz.

## Neden opencode FastAPI işlerine uygun?

FastAPI projeleri katmanlıdır: route tanımları, Pydantic şemaları, servis fonksiyonları ve bağımlılıklar farklı dosyalarda tutulur. opencode terminal üzerinden çalıştığı için `app/api/` altındaki route dosyasını, `app/schemas/` altındaki modeli ve `app/deps.py` bağımlılığını aynı anda okuyup değişiklikleri tutarlı biçimde yapabilir. AGENTS.md’deki klasör düzeni ve kurallar, ajanın hangi dosyaya ne koyacağını netleştirir; böylece endpoint eklerken `response_model` ve `Depends` çağrıları doğal olarak yerine oturur.

FastAPI’nin kod kalıpları kısa ve deyimsel olduğu için opencode’un ürettiği yamalar da gözden geçirmesi kolaydır. Örneğin bir `POST` endpoint’inde `request` modelini Pydantic v2’ye göre yazmak, `yield` ile veritabanı session’ı açmak veya `status_code` belirlemek birkaç satırlık değişikliklerdir. Ayrıca TestClient tabanlı testler hızlı çalıştığı için ajan `pytest -q` komutunu kendisi çalıştırıp hata ayıklayabilir; bu da insan müdahalesini azaltır.

## Projeyi ajana hazırlama

opencode’un proje konvansiyonlarını öğrenmesi için kök dizine kısa ama kapsamlı bir AGENTS.md dosyası koyun. Bu dosya ajanın her çalıştırmada okuduğu tek talimat kaynağıdır; komutlar, klasör düzeni ve FastAPI’ye özgü kuralları içermelidir. Aşağıdaki örnek gerçekçi bir FastAPI projesi için uygundur:

```markdown
# AGENTS.md

## Komutlar
- Kurulum: `uv sync`
- Test: `pytest -q`
- Lint: `ruff check app tests`
- Format: `ruff format app tests`

## Klasör düzeni
- `app/main.py`: FastAPI uygulaması
- `app/api/`: rota tanımları
- `app/schemas/`: Pydantic modeller
- `app/services/`: iş mantığı
- `app/deps.py`: bağımlılıklar
- `tests/`: TestClient testleri

## Kurallar
- Yeni endpoint'lerde mutlaka `response_model` tanımla.
- Pydantic v2 API'sini kullan; `orm_mode` yerine `from_attributes=True` yaz.
- Route içinde doğrudan DB erişimi yapma; `Depends` ile servis fonksiyonunu çağır.
- Async endpoint'lerde blocking I/O kullanma; gerekirse `run_in_threadpool` sarmala.
- Her değişiklikten sonra `pytest -q` çalıştır.
- Testlerde yalnızca HTTP davranışını TestClient ile doğrula.
```

Komutlar bölümü ajana hangi paket yöneticisini ve test komutunu kullanacağını söyler; `uv sync` yerine `pip install -e .` de olabilir. Klasör düzeni bölümü, `app/api/` altındaki dosyaların yalnızca route tanımlarını içermesini, iş mantığının `app/services/` altında olmasını garantiler. Kurallar bölümü ise FastAPI’ye özgü tuzakları baştan önler: `response_model` zorunluluğu, Pydantic v2 geçişi, async/blocking ayrımı ve testlerin yalnızca HTTP üzerinden yapılması gibi. Bu dosyayı güncelledikçe ajan sonraki görevlerde yeni kurallara uyar; örneğin bir gün `pytest -x` eklemek isterseniz, AGENTS.md’ye yazmanız yeterlidir.

## Çalışma döngüsü: planla, küçük adım at, testi çalıştır, diff’i incele

opencode ile en verimli çalışma şekli, büyük bir görevi tek seferde vermek yerine her biri test edilebilir küçük adımlara bölmektir. Her adımda şu sırayı izleyin: önce ajan plan yapıp hangi dosyaları değiştireceğini söyler (ya da siz söylersiniz); sonra değişikliği yapar; ardından `pytest -q` ile testleri çalıştırır; son olarak `git diff` ile yalnızca o adıma ait değişiklikleri inceleyip onaylayın. Bu döngü, hataların erken yakalanmasını sağlar ve ajanın kendi içinde sapmasını önler.

İyi yazılmış istem, dosya yolunu, beklenen davranışı ve başarı kriterini içerir. Aşağıdaki örnekler FastAPI projelerinde sık karşılaşılan görevler için kullanılabilir:

- `app/api/users.py` içindeki `POST /users` endpoint’ine `response_model=UserOut` ekle ve `UserOut` modelini `app/schemas/user.py` dosyasına Pydantic v2 kurallarıyla yaz; test eklemeden önce mevcut `tests/test_users.py` testlerinin geçmesini sağla.
- `app/deps.py` içindeki `get_db` bağımlılığını async hale getir; `app/api/items.py` içindeki `GET /items` endpoint’ini buna göre güncelle ve `tests/test_items.py` içindeki ilgili testi çalıştır.
- `tests/test_items.py` içine `GET /items` için başarılı liste ve boş liste durumlarını TestClient ile ekle, ardından tüm testleri çalıştır.
- `app/api/auth.py` içindeki `POST /auth/login` endpoint’inde hata durumları için `HTTPException` mesajlarını sabit bir modüle taşı; `tests/test_auth.py` içindeki testleri güncelle.
- `get_current_user` bağımlılığındaki JWT doğrulamasını yeniden düzenle; mevcut testleri bozmadan `pyjwt` kullan. Dosya yollarını ve çalıştırılacak test komutunu istemde belirt.

İstemde test komutunu da yazarsanız ajan her değişiklikten sonra kendini doğrular. Ayrıca her adımı ayrı bir git commit haline getirin; böylece geri almak kolaylaşır ve `git show` ile tek bir değişikliği inceleyebilirsiniz.

## opencode’un iyi yaptığı işler ve dikkat edilmesi gerekenler

opencode, FastAPI projelerinde özellikle tekrarlayan ve kalıp gerektiren işlerde hızlıdır. Yeni bir Pydantic şeması oluşturmak, mevcut route’a `response_model` eklemek, dependency injection zincirini basitleştirmek, import düzenlemek ve TestClient ile test yazmak gibi görevleri doğru istemle kısa sürede tamamlar. Aşağıdaki tablo tipik görevler için güçlü istem örneklerini gösterir:

| Görev | Verilebilecek istem |
| `response_model` ekleme | `app/api/users.py` içindeki `POST /users` endpoint’ine `response_model=UserOut` ekle ve şemayı oluştur. |
| Bağımlılık refactor | `get_db` bağımlılığını `yield` ile yaz; session’ı her istekten sonra kapat, route’ları güncelle. |
| Test yazımı | `tests/test_items.py` içine `GET /items` için başarılı ve 404 durumlarını TestClient ile ekle. |
| Pydantic v2 geçişi | `app/schemas/` altındaki modellerde `orm_mode` yerine `from_attributes=True` kullanacak şekilde düzenle. |

Buna karşılık ajanın FastAPI’ye özgü konularda dikkatli yönlendirilmesi gerekir. En sık görülen hatalar şunlardır: `response_model` ile dönüş tipini uyuşturmamak; Pydantic v1 kalıntısı `orm_mode` veya `Config` sınıfı kullanmak; async endpoint içinde senkron DB çağrısı yaparak event loop’u bloke etmek; `yield`'li bağımlılıklarda kapanma sırasını yanlış kurmak (ör. DB session’ı kapatmadan önce commit etmemek); `Depends` parametrelerinin sırasını bozmak; middleware ve exception handler’ları `main.py` içinde yanlış konumlandırmak. Ayrıca ajan bazen yeni endpoint eklerken `status_code` belirtmeyi unutabilir veya hata yanıtlarında tutarlı bir format kullanmayabilir. Bu nedenle her değişiklikte `pytest` çalıştırıp `git diff` üzerinde özellikle `async def`, `yield` ve `response_model` bölümlerini gözden geçirin. AGENTS.md’ye bu kuralları eklemek hataları azaltır.

## Test ve doğrulama

FastAPI projelerinde en güvenilir doğrulama TestClient ile yapılır. opencode’dan testleri `pytest -x -q` ile çalıştırmasını isteyin; `-x` bayrağı ilk hatada durur ve hatalı dosyayı hızlıca bulmanızı sağlar. Yalnızca `uvicorn` ile elle denemek yerine, her endpoint için başarılı ve hata durumlarını TestClient ile kapsayın. Örneğin `GET /items/{item_id}` için hem 200 dönen bir öğe hem de 404 dönen kayıp öğe testi yazın. Pydantic modellerde yapılan değişikliklerde mevcut şema testlerini de çalıştırın; `response_model` içindeki alanların doğru serileştirildiğini `response.json()` üzerinden kontrol edin.

Test veritabanı kullanıyorsanız, her testten önce veritabanını temizlemek için `pytest` fixture’ları tanımlayın. Ajan fixture yazarken `yield` kullanarak test sonrası temizlik yapabilir; bu, dependency injection’daki `yield` ile karıştırılmamalıdır. Ayrıca async endpoint’leri test ederken TestClient’ın senkron sarmalayıcı olduğunu unutmayın; ajan eğer `pytest-asyncio` ile gerçek async test yazmak isterse, `httpx.AsyncClient` ve `ASGITransport` kullanması gerekebilir. Ancak başlangıç için TestClient yeterlidir. Ajan test eklerken yalnızca HTTP statüsünü değil, dönen JSON gövdesindeki alanları da kontrol etsin; böylece `response_model` hataları erken yakalanır. Son olarak, `ruff check app tests` ve `ruff format app tests` komutlarını düzenli çalıştırarak kod kalitesini koruyun.

## Birden çok ajanla çalışmak: AgentVera

AgentVera, opencode dahil birden çok kodlama ajanını aynı pencerede gerçek terminal panellerinde yan yana çalıştıran bir masaüstü uygulamasıdır. FastAPI projelerinde en kritik üç özellik kendi dosyalarını korumak ve kaliteyi yükseltmek için yeterlidir: her ajan kendi git worktree’sinde çalıştığı için aynı anda farklı endpoint’ler üzerinde dosya çakışması yaşanmaz; ajanın turu bitince ikinci bir model kodu inceleyip bulguları file:line olarak işaretler; checkpoint’ler ve token bütçeleri ise uzun refactor’larda geri alma ve maliyet kontrolü sağlar. [Paralel kodlama ajanları için en iyi araçlar](/blog/paralel-yapay-zeka-kodlama-ajani-araclari/) sayfasında benzer araçların karşılaştırması bulunur.

## Sonuç

opencode’i FastAPI projesinde kullanmanın özü basittir: AGENTS.md ile kuralları netleştirin, görevleri küçük parçalara bölün, her adımda `pytest` ile TestClient testlerini çalıştırın ve `git diff` üzerinden yalnızca ilgili değişiklikleri onaylayın. Böylece route, Pydantic modeli ve dependency injection katmanlarındaki değişiklikler hızlı ama kontrollü kalır. Zamanla ajan proje konvansiyonlarını öğrenir ve daha az düzeltme gerektirir. Daha büyük paralel çalışmalar için AgentVera gibi araçlar worktree ve otomatik kod incelemesi ile riski azaltır. Unutmayın: opencode bir yardımcıdır; nihai kod incelemesi ve mimari kararlar sizde kalır.

## Sık sorulanlar

**opencode FastAPI projesinde nasıl kullanılır?** Proje klasöründe opencode komutunu çalıştırın ve görevleri küçük parçalara bölerek verin. Ajan AGENTS.md dosyasından komutları ve kuralları okur; her değişiklikten sonra pytest -q çalıştırıp git diff ile değişiklikleri inceleyin.

**opencode için AGENTS.md dosyasına ne yazmalıyım?** Kurulum, test, lint ve format komutlarını, klasör düzenini ve FastAPI kurallarını yazın. Örneğin yeni endpoint’lerde response_model eklenmesi, async endpoint’lerde blocking I/O kullanılmaması ve route içinde DB erişimi yapılmaması gibi kurallar yeterli.

**opencode FastAPI endpoint’lerini test edebilir mi?** Evet, terminal üzerinden pytest ve TestClient çalıştırabilir. Testleri pytest -x -q ile çalıştırıp ilk hatada durmasını sağlayabilir, dönen JSON gövdesini ve HTTP durumunu doğrulayabilir.

**opencode ile çalışırken FastAPI’de en sık hangi hatalar olur?** Pydantic v1 kalıntıları (orm_mode), async endpoint içinde senkron DB çağrısı, yield'li bağımlılıkların yanlış kapanma sırası ve response_model unutulması sık görülür. Bu yüzden her değişiklikte testleri çalıştırıp diff’i incelemek önemlidir.

---

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