Bir Geliştirici, Dört Uzman: OpenCode İçin Kendi Ajan Ekibim 🧑‍💻

Genel Bakış 👋#

Uzun bir süre boyunca OpenCode iş akışım tek bir ajan ve devasa bir sohbetten ibaretti. Aynı ajandan önce kod yazmasını, sonra incelemesini, ardından SEO düzeltmelerini yapmasını ve son olarak dokümantasyonu güncellemesini istiyordum. Bu yöntem çalışsa da bağlam (context) hızla karmaşıklaşıyor ve kodu az önce yazan ajan, o kodu denetlemek için en kötü aday haline geliyordu.

Bu sorunu çözmek için kurulumumu küçük bir ekip olarak yeniden inşa ettim: kodu geliştiren bir birincil ajan ve görev devrettiği dört alt ajan (subagent). Her birinin kendi rolü, sınırları ve özel yeteneği (skill) bulunuyor. Her ajan tek bir Markdown dosyasından oluştuğu için tüm sistemi okumak, ince ayar yapmak ve versiyonlamak oldukça kolay. Yazılım geliştirme süreçlerinde tekil ve şişkin bağlamlar yerine sorumlulukların ayrılması (Separation of Concerns) ilkesini ajan mimarisine taşımak, çıktı kalitesini doğrudan artırır.

Ekip 👥#

Sistemin merkezinde doğrudan iletişim kurduğum ve uygulamayı sahiplenen birincil ajan olan web-developer (Astro, Vue, TypeScript, Vite, Bulma ve Tailwind konularında kıdemli web geliştirici) yer alıyor. Bu birincil ajanın başlattığı dört uzman alt ajan ise şunlar:

• ux-ui-expert: Projenin tasarım sistemine sadık kalarak UI, UX ve grafikleri tasarlar ve inceler.
• code-reviewer: Değişiklikleri, yeni bir özelliği veya tüm kod tabanını inceler ve sorunları önem derecesine göre raporlar.
• seo-expert: Sayfa içi (on-page), teknik ve içerik odaklı SEO denetimleri yapar.
• documentation-updater: README, değişiklik günlüğü (changelog) ve rehberleri kodla senkronize tutar.

İş akışı oldukça doğal ilerliyor: Ben bir özelliği tarif ediyorum, web-developer bir plan öneriyor, onayımdan sonra kodu inşa ediyor ve işi tamamlandı saymadan önce ilgili uzmanları devreye sokuyor.

Altın Kural: Önce Öner, Onaydan Sonra Uygula ✋#

Kurulumun kalbinde yer alan bu kural her ajan için geçerlidir. Hiçbir ajan ilk aşamada dosyaları doğrudan düzenlemez. Önce somut bir öneri (değişecek dosyalar, neyin neden değişeceği) sunarlar ve açık onayımı beklerler. Değişiklikleri uygularken de her yazma işlemi bir ask (sor) izniyle korunur; böylece işlemi tekrar onaylarım.

Ajanlar arası iletişim de kritiktir. Bir alt ajan düzeltme önerdiğinde, web-developer bunu kendi başına uygulamak yerine bana iletir. İki kontrol noktası sayesinde sessiz değişiklikler önlenir. Uygulama sırasında beklenmedik bir durum çıkarsa, ajan doğaçlama yapmak yerine durup rapor vermekle yükümlüdür. Pratik çıkarım olarak; üretim ortamlarında otonom ajanlara sınırsız yazma yetkisi vermek yerine "insan onaylı" (human-in-the-loop) kapılar eklemek, istenmeyen kod bozulmalarını engeller.

Bir Ajan Dosyasının Anatomisi 🔧#

OpenCode'da doğrudan konuştuğunuz (Tab ile geçiş yapılan) birincil ajanlar ve birincil ajan tarafından veya @ bahsetmesiyle çağrılan alt ajanlar bulunur. Ajanlar .opencode/agents/ dizininde yaşar ve dosya adı ajanın adı olur.

Örneğin code-reviewer ajanının yapılandırmasında (frontmatter) şu izinler tanımlıdır:

• skill (code-review - allow): İlgili özel yeteneği yükler ve takip eder.
• edit (* - ask): Onay kapısı; her dosya düzenlemesi için kullanıcıdan onay ister.
• webfetch (* - allow): Dokümantasyon ve bilinen sorunlar için web erişimine izin verir.
• MCP sunucuları (*_* - allow): Gerektiğinde bağlı MCP sunucularını kullanır.
• external_directory (* - deny): Sandbox kuralı; çalışma alanı dışındaki hiçbir şeye erişemez.

Burada iki pratik mimari detay öne çıkıyor: İlk olarak, sandbox kuralı özellikle en sona yazılır. external_directory için son eşleşen kural geçerli olduğundan, deny (reddet) kuralı MCP dahil üstteki tüm izinleri ezer. Böylece ajanlar terminal üzerinden bile mevcut proje dışını okuyamaz ve yazamaz. İkinci olarak, web erişimi ve MCP sunucuları açık olsa da, sistem istemi (prompt) ajana bunları aşırı kullanmamasını ve önce proje içi bilgiyi denemesini söyler.