opencode ile .NET Projelerinde Pratik Çalışma Rehberi

opencode, proje klasöründe opencode komutuyla başlatılan bir terminal tabanlı kodlama ajanıdır. .NET çözümlerinde dotnet CLI, ASP.NET Core, Entity Framework Core ve test projeleriyle doğrudan çalışır. Bu rehber, .NET bilen bir geliştiricinin opencode’dan verim alması için gereken kurulum, çalışma döngüsü ve doğrulama pratiklerini anlatır.

Neden opencode .NET işlerine uygun?

.NET çözümleri genellikle birden çok proje, çözüm dosyası ve test projesi içerir; ajanın hangi komutu nerede çalıştıracağını bilmesi gerekir. opencode terminal tabanlı olduğu için dotnet build, dotnet test, dotnet format gibi komutları gerçek bir kabukta çalıştırır ve MSBuild çıktısını doğrudan yorumlayabilir. AGENTS.md dosyasını okuduğundan, çözüm yapısını, test komutlarını ve .NET’e özel kuralları önceden öğrenmiş olur.

opencode özellikle NuGet paket yönetimi, çoklu hedef çerçeve (multi-targeting) ve proje referansları gibi .NET altyapı detaylarında da başarılıdır. dotnet add package, dotnet remove package, dotnet list package --outdated gibi komutları çalıştırarak bağımlılık güncellemelerini yönetebilir. SDK sürümü veya global.json tutarsızlıklarında hatayı analiz edip çözüm önerebilir. Ayrıca model sağlayıcısından bağımsız olması, aynı kurulumla farklı modelleri denemeyi kolaylaştırır; Claude Code ile karşılaştırma için opencode mu Claude Code mu? Dürüst bir karşılaştırma yazısına bakılabilir. Windows ve WSL arasında seçim yapıyorsanız Kodlama ajanları için WSL mi, yerel Windows mu? yazısı da yol gösterir.

Projeyi ajana hazırlama ve AGENTS.md örneği

opencode proje kökündeki AGENTS.md dosyasını her oturumda okur. Dosya kısa ve gerçek komutlarla dolu olmalı; süslü ifadelerden kaçının. Aşağıdaki örnek, çok projeli bir ASP.NET Core çözümü için yeterli bir başlangıçtır:

# AGENTS.md

## Komutlar
- Build: `dotnet build src/MyApp.sln`
- Test: `dotnet test tests/MyApp.Tests/MyApp.Tests.csproj --no-restore`
- Lint/format: `dotnet format src/MyApp.sln --verify-no-changes`

## Klasör yapısı
- `src/` altında proje bazında klasörler
- `tests/` altında xUnit test projeleri
- EF Core migration'ları `src/MyApp.Infrastructure/Migrations`

## .NET kuralları
- Yeni davranış için xUnit testi ekle
- Model değişikliğinde `dotnet ef migrations add` ile migration oluştur
- Nullable reference types kapalıysa açma, açıksa koru
- Asenkron metod adlarını `Async` ile bitir
- ASP.NET Core'da controller yerine minimal API tercih et
- Kullanılmayan using'leri ve namespace importlarını temizle
- Ajan bir komutu çalıştırmadan önce onay iste

Çözüm ve test projesi adlarını kendi yapınıza göre güncelleyin. Ajan yanlış proje adıyla komut çalıştırırsa MSBuild hatası alırsınız; bu yüzden AGENTS.md’deki yolların gerçek olması önemlidir.

AGENTS.md’yi kısa tutmaya özen gösterin. Uzun ve genel talimatlar yerine, tam dosya yolları ve gerçek komut satırları verin. Örneğin “format kullan” yerine dotnet format src/MyApp.sln --verify-no-changes --exclude tests/ gibi bir komut yazın. Ayrıca dosyayı sürüm kontrolünde tutun; her ekip üyesi aynı talimatları kullanır. İhtiyaç duydukça güncelleyin, ama ajanın kafasını karıştıracak gereksiz ayrıntılardan kaçının.

Ek olarak şu .NET’e özgü kuralları da AGENTS.md’ye eklemeyi düşünün:

• appsettings.Development.json gibi ortama özel dosyaları değiştirme; user-secrets kullan.
• Directory.Build.props ve Directory.Packages.props varsa onlara müdahale etme.
• NuGet paket eklerken lisans ve güvenlik açığı kontrolü yap.
• dotnet ef komutları için gerekli tool manifest’i veya global tool kurulumu hakkında bilgi ver.
• Kod analizi uyarılarını kapatma; TreatWarningsAsErrors açıksa koru.

Çalışma döngüsü ve örnek .NET komutları

opencode ile verimli çalışmanın temeli; önce plan, sonra küçük değişiklik, ardından test ve diff incelemesidir. İlk oturum ve genel kullanım için opencode nasıl kullanılır? Adım adım rehber yazısına bakabilirsiniz.

Önerilen döngü şu şekildedir:

1. Ajanın mevcut kodu incelemesini ve önerdiği değişiklikleri önce plan olarak sunmasını iste.
2. Planı onaylayın veya küçültün.
3. Ajanın sadece ilgili dosyaları değiştirmesini sağlayın.
4. Değişiklik sonrası dotnet build ve dotnet test çalıştırın.
5. git diff ile farkı inceleyin; gerekiyorsa ajanın açıklamasını isteyin.

Aşağıdaki komutlar, ajanı doğal dille yönlendirmek için gerçekçi örneklerdir:

• “Solution’daki OrderService sınıfını incele; sipariş oluşturma metodundaki eksik doğrulama ve null kontrolünü eklemek için önce planını söyle.”
• “ProductController listeleme endpoint’ini sayfalama ve filtreleme destekleyecek şekilde güncelle; IQueryable üzerinde filtre uygula, ToListAsync kullan.”
• “Customer ve Address entity’leri arasında bire çok ilişki kur; migration’ı oluştur, dotnet ef database update çalıştırma, önce oluşan dosyaları göster.”
• “Bu xUnit test sınıfındaki başarısız testi bul ve yalnızca ilgili testi çalıştırarak düzelt; test adını ve hata mesajını raporla.”
• “dotnet build hatasını çöz, ancak değişikliği tek dosyayla sınırlı tut ve sonucu özetle.”
• “EF Core’da N+1 sorgu problemini AsNoTracking ve Include kullanarak gider; performansı ölçmeden önce mevcut sorguları göster.”
• “Bu minimal API endpoint’ine rate limiting eklemek için AddRateLimiter kullan; Program.cs’i güncelle ve gerekli NuGet paketini öner.”

Ajan büyük bir refactor önerirse, onu birden çok küçük göreve bölmesini isteyin. Her adımda testleri yeşil tutun; kırmızı testle ilerlemek düzeltmeyi zorlaştırır.

Tipik .NET görevleri ve dikkat edilmesi gerekenler

opencode özellikle CRUD endpoint’leri, DTO eşleme, Fluent Validation kuralları, xUnit/NUnit testleri, DI kayıtları ve küçük refactor işlerinde iyi sonuç verir. Ancak .NET ekosistemine özgü bazı noktalarda gözünüz üzerinde olsun.

Ayrıca çok projeli solution’larda ajan bazen yanlış projeye dosya ekleyebilir; AGENTS.md’deki klasör yapısı netse bu risk azalır. Generated migration dosyaları ve .csproj değişiklikleri her zaman elle incelenmelidir.

Ajan, basit endpoint ekleme, middleware yazma, test genişletme gibi görevlerde güvenilirdir. Ancak mimari kararlar, veri modeli tasarımı veya performans kritik kodlarda ondan yalnızca öneri isteyin, son sözü kendiniz verin.

Test ve doğrulama: opencode ile .NET’te

Ajan her değişiklikten sonra test komutunu kendisi önerebilir; ancak siz doğrulamayı standart hale getirin. Aşağıdaki komutları düzenli olarak kullanın:

• dotnet build src/MyApp.sln ile çözümün tamamını derleyin.
• dotnet test tests/MyApp.Tests/MyApp.Tests.csproj --no-build ile testleri çalıştırın.
• dotnet test --filter "FullyQualifiedName~OrderServiceTests" ile yalnızca ilgili test sınıfını koşun.
• dotnet format src/MyApp.sln --verify-no-changes ile biçim ihlallerini yakalayın.
• dotnet list package --vulnerable --include-transitive ile bilinen güvenlik açıklarını kontrol edin.

Ajanın önerdiği test kodunu çalıştırmadan önce test adlarının ve assertion’ların gerçek davranışı kapsadığını kontrol edin. xUnit’te paralel test çalıştırma koleksiyonları, paylaşılan durum nedeniyle yanıltıcı sonuç üretebilir; böyle bir durumda testi izole edin. EF Core içeren testlerde gerçek veritabanı yerine in-memory provider kullanılması isteniyorsa, ajanın UseInMemoryDatabase çağrısını doğru yere eklediğinden emin olun.

Daha gerçekçi entegrasyon testleri için Testcontainers kullanmayı düşünebilirsiniz. Ajana “PostgreSQL için Testcontainers ile entegrasyon testi yaz” dediğinizde, gerekli NuGet paketlerini ekleyip test sınıfını oluşturabilir. Ancak container başlatma ve disposal mantığını kontrol edin; ayrıca CI ortamında Docker erişimi olup olmadığını göz önünde bulundurun.

Aynı .NET projesinde birden çok ajanı AgentVera ile çalıştırmak

AgentVera, opencode dahil CLI ajanlarını aynı pencerede, her biri kendi gerçek terminal panelinde yan yana çalıştırır. Aynı .NET solution’ında birden fazla ajanı paralel koşturacaksanız her ajanı ayrı bir git worktree’ye yönlendirmek, .csproj ve ortak dosyaların üzerine yazılmasını önler. Ajanın turu bittiğinde ikinci bir modelin yaptığı otomatik kod incelemesi, C# ve MSBuild hatalarını file:line ile gösterir. Her turun anlık görüntüsü (checkpoint) ise yanlış bir EF Core migration veya refactor’ı tek tıkla geri alıp oturumu adım adım yeniden oynatmayı sağlar.

Sonuç

opencode, .NET projelerinde terminal tabanlı ve komut odaklı bir ajan olarak iyi çalışır. Anahtar; kısa ve gerçek bir AGENTS.md, küçük görevler, her adımda test çalıştırma ve diff incelemesidir. Aynı projede paralel çalışma gerektiğinde AgentVera’nın worktree, otomatik inceleme ve checkpoint özellikleri riski ciddi biçimde azaltır.