opencode ve FastAPI ile Pratik Geliştirme Rehberi

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 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:

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