
Agentic Workflow, AI destekli yazılım geliştirmeyi tek seferlik prompt kullanımından çıkarıp görev planlama, implementasyon, review, test, commit ve deploy kontrolü olan bir çalışma sistemine dönüştüren açık kaynak bir repodur.
Bu yazıda varienos/agentic-workflow reposunun hangi problemi çözdüğünü, Agentbase/Codebase mimarisinin neden önemli olduğunu, Backlog.md ile görev yaşam döngüsünün nasıl kurulduğunu ve bu yaklaşımın yazılım ekipleri için ne tür bir güvenlik ağı oluşturduğunu detaylıca ele alıyoruz.
Bu yazı, 19 Mayıs 2026 itibarıyla GitHub reposundaki README ve yerel repo yapısı temel alınarak hazırlanmıştır. Repo geliştikçe komutlar, modül kapsamı ve desteklenen CLI hedefleri değişebilir.
Bu repoyu özellikle Türkçe açıklamalarla paylaşmamın nedeni, bu konuyu öğrenmek isteyen geliştiricilerin dil bariyerine takılmadan başlayabilmesini sağlamak. Agentic workflow, AI destekli geliştirme, task lifecycle, review agent'ları veya deploy guardrail'leri gibi kavramlar zaten yeterince yoğun; bir de tüm kaynakları yabancı dilden takip etmek birçok kişi için gereksiz bir eşik oluşturuyor.
Burada anlattığım yapı teorik bir deneme değil. Uzun zamandır farklı projelerde edindiğim tecrübelere göre geliştirmeye devam ettiğim, kendi işlerimde de kullanmayı sürdürdüğüm bir workflow. Yeni problem sınıfları, agent hataları, review ihtiyaçları, test eksikleri veya deploy riskleri gördükçe sistemi sadeleştiriyor, sıkılaştırıyor ve repo içinde güncelliyorum.
Bu yüzden Agentic Workflow'u bitmiş bir ürün gibi değil, gerçek projelerde kullanıldıkça olgunlaşan açık bir çalışma düzeni olarak görmek daha doğru. Amacım, bu alana girmek isteyenlerin sıfırdan aynı hataları tekrar etmeden, Türkçe açıklamalarla daha hızlı kavraması ve kendi projelerine uyarlayabilmesi.
Agentic Workflow, Claude Code etrafında tasarlanmış ama yalnızca Claude Code'a sıkışmayan bir yazılım geliştirme workflow sistemidir. Ana fikir basittir: AI agent kod yazmadan önce görevi anlamalı, scope'u bölmeli, kabul kriterlerini netleştirmeli, doğru dosyaları keşfetmeli, testleri çalıştırmalı, review'dan geçmeli ve yaptığı işi backlog üzerinde kapatmalıdır.
Bu yüzden Agentic Workflow bir "prompt koleksiyonu" gibi düşünülmemelidir. Repo; slash komutları, agent şablonları, hook'lar, git güvenlik kapıları, Backlog.md görevleri, proje manifesti ve çoklu CLI dönüşüm katmanını birlikte ele alır.
Klasik AI kodlama denemelerinde sık görülen problem şudur: Agent bir dosyayı değiştirir, kısmi bir çözüm üretir, testleri çalıştırmadan işi bitmiş sayar ve context kaybolduğunda neden o kararı verdiği anlaşılmaz. Agentic Workflow bu kırılmayı görev yaşam döngüsüyle çözer. Her iş bir backlog task'ına bağlanır; her task plan, uygulama, test ve kapanış kanıtı ister.
AI destekli yazılım geliştirme, doğru çerçeve kurulmadığında hız üretirken kontrol kaybı da üretebilir. Özellikle büyük kod tabanlarında agent'ın neyi değiştirdiğini, hangi testleri çalıştırdığını, hangi riski görmezden geldiğini ve bir sonraki göreve neden geçtiğini takip etmek zorlaşır.
Agentic Workflow bu problemi üç seviyede ele alır:
Bu yaklaşım, özellikle birden fazla agent oturumu, worktree, modül ve deployment hedefi olan projelerde değer üretir. Küçük bir script için ağır gelebilir; ama ürün geliştirme, bakım, güvenlik ve release süreçleri iç içe geçtiğinde agent davranışını ölçülebilir hale getirir.
Repo dört ana çalışma alanı üzerinden ilerler. Bu ayrım, agent konfigürasyonunun hedef proje kodundan ayrı kalmasını sağlar.
| Alan | Ne işe yarar? | Neden önemli? |
|---|---|---|
Agentbase/ | Komutlar, şablonlar, üretim betikleri, hook'lar ve agent tanımları | AI workflow mantığı tek yerde durur |
Agentbase/backlog/ | Backlog.md görev yaşam döngüsü | Task planlama, önceliklendirme ve kapanış izlenebilir olur |
Codebase/ | Üzerinde çalışılacak gerçek proje | Git işlemleri ve kod değişiklikleri hedef projede kalır |
Docbase/agentic/ | Bootstrap tarafından üretilen proje manifesti | Proje yapısı, stack ve workflow kararları makine tarafından okunabilir olur |
Bu mimarinin önemli tarafı, .claude/, CLAUDE.md veya agent ayarlarının hedef projenin commit geçmişine karışmamasıdır. Agentbase sabit kalır, Codebase ise gerçek uygulamayı temsil eder. Böylece aynı Agentbase üzerinden farklı worktree'lere veya farklı proje kopyalarına yönelmek mümkün olur.
Agentbase/Codebase ayrımı, AI agent konfigürasyonunu uygulama kodundan ayırdığı için uzun yaşayan projelerde temiz bir sınır oluşturur. Bu sınır, özellikle müşteri projelerinde veya birden çok branch/worktree ile çalışırken önemlidir.
Agentic Workflow'un başlangıç noktası /bootstrap komutudur. Bu komut projeyi tanır, eksik bilgileri kısa bir röportajla toplar ve kullanılacak workflow dosyalarını üretir.
Mevcut bir projeye bağlamak için temel akış şöyledir:
git clone https://github.com/varienos/agentic-workflowcd agentic-workflowrm -rf Codebaseln -s /path/to/your/project Codebasecd Agentbasenpm installclaude
Claude Code içinde:
/bootstrap
Bootstrap süreci şu adımlardan geçer:
Docbase/agentic/project-manifest.yaml üretilir.Agentbase/backlog/ altında başlatılır.Bu akışın amacı, AI agent'a sadece "şu özelliği yap" demek değildir. Amaç, agent'ın çalışacağı işletim modelini projeye göre üretmektir.
Agentic Workflow'un merkezinde Backlog.md vardır. Repo README'si bu bağımlılığı özellikle netleştirir: Backlog.md kurulmadan bootstrap çalışmaz. Çünkü sistemin ana sözleşmesi task yaşam döngüsüdür.
Tipik akış şu şekilde ilerler:
| Aşama | Komut | Çıktı |
|---|---|---|
| Planlama | /task-plan | Backlog görevi, acceptance criteria, etki alanı, complexity ve model önerisi |
| Önceliklendirme | /task-master | Impact, risk, dependency ve complexity skorlarına göre faz planı |
| Uygulama | /task-hunter | Kod değişikliği, test, doğrulama, commit ve task kapanışı |
| Review | /task-review | Kod kalitesi, sessiz hata ve regresyon riski değerlendirmesi |
| Bug çözümü | /bug-hunter | Root cause hipotezleri, minimal fix, regresyon testi ve kapatma |
| Audit | /deep-audit | Domain modülünü API, DB, frontend ve mobil katmanlarda inceleme |
Bu yapı sayesinde agent'ın işi bitirme tanımı daha somut hale gelir. "Kod yazıldı" tek başına yeterli değildir; testin nasıl doğrulandığı, review bulgularının ne olduğu ve task'ın hangi kabul kriterleriyle kapandığı da sürecin parçasıdır.
Agentic Workflow içindeki komutlar, yazılım geliştirme sürecinin farklı karar noktalarını kapsar.
/task-plan, doğal dilde verilen isteği doğrudan implement etmeye çalışmaz. Önce kod tabanını tarar, etkilenen dosyaları tahmin eder, işin büyüklüğünü değerlendirir ve gerekirse scope'u böler. Bu ayrım önemlidir çünkü AI agent'ların en sık yaptığı hatalardan biri, büyük bir görevi küçük ve doğrulanabilir adımlara ayırmadan uygulamaya başlamaktır.
Örnek:
/task-plan "Kullanıcı profil sayfasına avatar yükleme özelliği ekle"
/task-hunter, backlog'daki bir görevi uygular. Görev dosyasını okur, ilgili dosyaları keşfeder, plan yapar, kodu yazar, testleri çalıştırır, commit eder ve görevi kapatır. Karmaşık işlerde paralel agent kullanımı devreye girebilir.
Örnek:
/task-hunter 42/task-hunter 42,43,44/task-hunter auth
/task-review, değişikliği tek gözle incelemek yerine birden fazla perspektiften değerlendirir. Genel kod kalitesi, sessiz hata ihtimali ve regresyon riski ayrı ayrı ele alınır. Güvenlik, auth, ödeme veya migration gibi yüksek riskli alanlarda adversarial bir review perspektifi de devreye girebilir.
Bu model, yazılım geliştirme metodolojisi açısından bakıldığında klasik code review'u AI destekli bir kontrol katmanına dönüştürür. Review, sadece stil yorumu değil; değişikliğin üretimde nasıl kırılabileceğini arayan bir mekanizmadır.
/bug-hunter, bug çözümünü sınırsız araştırma döngüsüne bırakmaz. En fazla üç hipotezle root cause arar, bulduğunda minimal fix uygular ve regresyon testi ister. Üç hipotez sınırı, agent'ın aynı problem etrafında gereğinden fazla token harcamasını ve kapsamı dağıtmasını engeller.
Agentic Workflow'u değerli yapan parçalardan biri, agent'ın sadece kod üreten bir araç gibi değil, belirli kurallara bağlı bir çalışma birimi gibi davranmasını sağlamasıdır.
Başlıca koruma katmanları şunlardır:
Bu katmanlar, AI destekli yazılım geliştirmede "agent yaptı, oldu" riskini azaltır. Özellikle backend, mobil, CI/CD ve güvenlik katmanları olan projelerde bu tür guardrail'ler sürecin parçası olmalıdır. Benzer şekilde tip güvenli backend geliştirme pratiklerinde de amaç, hatayı üretime gitmeden önce daha erken yakalamaktır.
Repo mimarisindeki Agentbase/Codebase ayrımı, git worktree kullanımını kolaylaştırır. Geleneksel yaklaşımlarda .claude/ veya benzeri agent konfigürasyonları proje kökünde durur. Yeni worktree açıldığında bu dosyaların her kopyada güncel kalması gerekir.
Agentic Workflow farklı bir yol izler: Agentbase sabit kalır, Codebase hedefi ise environment değişkeni, manifest veya symlink üzerinden çözülebilir.
| Yöntem | Kullanım | Uygun olduğu durum |
|---|---|---|
AGENTIC_CODEBASE_DIR | Tek terminal oturumunu belirli worktree'ye yönlendirir | Aynı anda birkaç branch üzerinde çalışırken |
Codebase symlink'i | Repo kökündeki aktif Codebase hedefini değiştirir | Tek aktif hedef isteyen kurulumlarda |
| Manifest güncelleme | Kalıcı proje yapısını günceller | Workspace yapısı gerçekten değiştiğinde |
Bu tasarım, paralel agent oturumları için önemlidir. Bir terminal auth işini, başka bir terminal ödeme modülünü, üçüncü terminal UI düzenlemesini yürütürken hepsi aynı Agentbase kurallarını kullanabilir ama farklı worktree'lere çalışabilir.
Agentic Workflow'un ilginç taraflarından biri, Claude Code çıktısını tek hedef kabul etmemesidir. transform.js, Claude canonical çıktısını Gemini CLI, Codex CLI, Kimi CLI ve OpenCode gibi farklı yüzeylere dönüştürebilir.
| Hedef | Üretilen yüzey |
|---|---|
| Gemini CLI | .gemini/commands, .gemini/agents, GEMINI.md |
| Codex CLI | .codex/skills/*/SKILL.md, AGENTS.md |
| Kimi CLI | .kimi/skills, .kimi/agents |
| OpenCode | .opencode/skills, .opencode/agents, .opencode/AGENTS.md |
Bu yaklaşım, agentic workflow tasarımında önemli bir ayrımı gösterir: Asıl kaynak Claude Code şablonlarıdır; diğer CLI yüzeyleri bu kaynaktan dönüştürülür. Codex hedefinde native slash command garantisi yerine skill/context yüzeyi üretilmesi de bu ayrımın parçasıdır.
Bu tür çoklu model ve çoklu araç stratejileri, LLM entegrasyonu tarafında da benzer bir ders verir: Model veya araç tek başına mimari değildir. Mimari, girdinin, bağlamın, karar noktasının ve doğrulama çıktısının nasıl yönetildiğidir.
Agentic Workflow en çok şu tip projelerde anlam kazanır:
Her proje için gerekli olmayabilir. Küçük bir landing page, tek dosyalık otomasyon veya kısa süreli prototip için bu kadar kapsamlı bir workflow fazla gelebilir. Ancak uzun yaşayan ürünlerde AI agent'ın tekrar eden hatalarını azaltmak, kararları backlog'a bağlamak ve doğrulamayı standartlaştırmak ciddi fark yaratır.
Repo, temel olarak şu araçlara ihtiyaç duyar:
| Gereksinim | Rolü |
|---|---|
| Claude Code CLI | Slash komutları ve agent workflow çalıştırma yüzeyi |
| Backlog.md CLI | Görev yaşam döngüsünün kaynağı |
| Node.js 18+ ve npm | Agentbase betikleri ve testleri |
| jq | Hook'larda JSON işleme |
| Git 2.38+ | Pre-push conflict ve merge kontrolleri |
| Docker CLI | Docker veya Coolify deploy modülü aktifse |
| GitHub CLI | Release otomasyonu için opsiyonel destek |
Backlog.md bağımlılığı özellikle önemlidir. Bu repo, görevleri serbest metin notları olarak değil, CLI ile yönetilen bir backlog sistemi olarak ele alır. Bu sayede planlama, uygulama ve kapanış aynı veri kaynağı üzerinden ilerler.
Agentic Workflow'u bir projeye eklerken en sağlıklı yaklaşım, her şeyi ilk günden otomatikleştirmeye çalışmak değildir. Daha kontrollü bir geçiş planı şu şekilde olabilir:
Codebase olarak bağlayın ve /bootstrap ile manifest üretin./task-plan, /task-hunter ve /task-review akışını kullanın.Bu yaklaşım, agentic workflow kurulumunu bir defalık "tool install" işi olmaktan çıkarır. Sistem, proje çalıştıkça öğrenen ve sıkılaşan bir geliştirme sözleşmesine dönüşür.
Agentic Workflow agent davranışını güçlendirir; ama mimari kararı otomatik olarak doğru vermez. Domain sınırları, ürün öncelikleri, güvenlik kabul kriterleri ve production riskleri yine teknik ekip tarafından netleştirilmelidir.
Agentic Workflow gibi repolar, yalnızca geliştirici verimliliği açısından değil, ürün teslimat kalitesi açısından da önemlidir. Çünkü AI destekli yazılım geliştirmede fark artık sadece daha hızlı kod yazmak değildir. Asıl değer, hızlı kodun güvenli şekilde test edilmesi, review edilmesi, deploy öncesi kontrol edilmesi ve sonraki task'a taşınabilir bağlam bırakmasıdır.
Bir ürün ekibi için ölçülmesi gereken metrikler şunlar olabilir:
| Metrik | Neden takip edilmeli? |
|---|---|
| Task kapanış süresi | Agent workflow'un gerçek teslimat hızına etkisini gösterir |
| Review bulgu oranı | Agent'ın hangi hata sınıflarını sık ürettiğini ortaya çıkarır |
| Test çalıştırma oranı | Değişikliklerin kanıtlı kapanıp kapanmadığını ölçer |
| Pre-existing bug sayısı | Eski borçların yeni task'ları nasıl etkilediğini görünür kılar |
| Deploy sonrası smoke sonucu | Workflow'un production güvenliğine katkısını ölçer |
Bu metrikler olmadan AI destekli geliştirme hissi olarak hızlı görünebilir, ama iş sonucuna etkisi belirsiz kalır. Agentic Workflow'un güçlü tarafı, bu hissi task, test, review ve deploy kanıtına bağlamasıdır.
Ana çalışma yüzeyi Claude Code olarak tasarlanmıştır. Ancak repo, transform.js ile Gemini CLI, Codex CLI, Kimi CLI ve OpenCode gibi hedeflere çıktı üretebilir. Burada önemli fark, Claude çıktılarının canonical kaynak olmasıdır; diğer hedefler bu kaynaktan dönüştürülür.
Çünkü sistemin merkezinde görev yaşam döngüsü vardır. Backlog.md olmadan task oluşturma, önceliklendirme, implementasyon, review ve kapatma aynı veri yapısına bağlanamaz. Bu repo için backlog, yardımcı bir not alanı değil, workflow'un ana sözleşmesidir.
Bazı küçük projeler için evet. Eğer tek geliştirici, kısa ömürlü prototip ve düşük production riski varsa daha hafif bir kurulum yeterli olabilir. Ancak uzun yaşayan ürünlerde, özellikle test, release, güvenlik ve bakım süreçleri olan ekiplerde bu yapı daha anlamlıdır.
Hayır. Hook'lar, review komutları ve test zorlaması kalite riskini azaltır; ama domain bilgisi, mimari kararlar ve ürün öncelikleri hâlâ insan sorumluluğundadır. Sistem, doğru kararların uygulanmasını ve doğrulanmasını kolaylaştırır.
Varien gibi web, mobil, backend, AI ve DevOps katmanlarını birlikte yürüten ekiplerde bu yaklaşım özellikle değerlidir. Yapay zeka çözümleri, backend API geliştirme ve mobil uygulama geliştirme gibi çok katmanlı işlerde agent'ın sadece kod değil süreç disiplini de taşıması gerekir.
Agentic Workflow, AI destekli yazılım geliştirmeyi daha kontrollü, ölçülebilir ve ekip süreçlerine uygun hale getiren açık kaynak bir workflow sistemidir. En büyük değeri, agent'ı tekil bir kod yazıcı olmaktan çıkarıp backlog, test, review, deploy ve dokümantasyon disiplini olan bir çalışma akışına yerleştirmesidir.
Bugün AI ile kod yazmak kolaylaştı; zor olan, bu kodun neden yazıldığını, nasıl doğrulandığını, hangi riski taşıdığını ve hangi task'ı kapattığını takip edebilmektir. varienos/agentic-workflow bu ikinci probleme odaklandığı için dikkat çekicidir: hızdan önce izlenebilirlik, otomasyondan önce görev disiplini ve agent özgürlüğünden önce güvenlik sınırları.