Agentic Workflow: AI Destekli Yazılım Geliştirme Süreci Nasıl Kurulur?

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 Repoyu Neden Türkçe Paylaştım?

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 Nedir?

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.

Hangi Problemi Çözüyor?

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:

• Görev seviyesi. İstekler doğrudan koda dönüşmez; önce Backlog.md üzerinde task'a, kabul kriterlerine ve scope kararına dönüşür.
• Kod seviyesi. Agent değişiklik yaparken test, review, dokümantasyon drift'i ve config sınırları gibi korumalar devreye girer.
• Operasyon seviyesi. Deploy öncesi kontroller, pre-push hook'ları, migration güvenliği ve post-deploy doğrulama akışı süreçten ayrı düşünülmez.

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.

Temel Mimari

Repo dört ana çalışma alanı üzerinden ilerler. Bu ayrım, agent konfigürasyonunun hedef proje kodundan ayrı kalmasını sağlar.

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.

Bootstrap Akışı Nasıl Çalışır?

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-workflow
cd agentic-workflow

rm -rf Codebase
ln -s /path/to/your/project Codebase

cd Agentbase
npm install
claude

Claude Code içinde:

/bootstrap

Bootstrap süreci şu adımlardan geçer:

1. Backlog.md CLI, Node.js, Codebase erişimi ve önceki manifest gibi ön koşullar kontrol edilir.
2. Proje tipi, paket yöneticisi, test araçları, modül adayları ve dizin yapısı analiz edilir.
3. Proje, teknik tercihler, geliştirici profili ve domain kuralları için fazlı röportaj yapılır.
4. Docbase/agentic/project-manifest.yaml üretilir.
5. Manifest üzerinden komutlar, agent'lar, hook'lar, kurallar ve yardımcı dokümanlar oluşturulur.
6. Backlog Agentbase/backlog/ altında başlatılır.
7. Onboarding raporu, eklenti önerileri ve git hook etkinleştirme komutu gösterilir.

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.

Görev Yaşam Döngüsü

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:

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.

Öne Çıkan Komutlar

Agentic Workflow içindeki komutlar, yazılım geliştirme sürecinin farklı karar noktalarını kapsar.

Task Plan

/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

/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

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

Koruma Katmanları

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:

• Codebase config guard. Agent config dosyalarının hedef Codebase içine yazılmasını engeller.
• Test enforcer. Kaynak dosya değiştiğinde ilgili testlerin yazılması veya çalıştırılması gerektiğini hatırlatır.
• Doc drift check. Kod değişikliklerinden sonra README, CHANGELOG veya OpenAPI dokümanlarının geride kalabileceğini işaretler.
• Pre-push hook. Push öncesinde test, localhost leak, migration ve env sync kontrollerini son kapı olarak çalıştırır.
• Deploy komutları. Docker, Coolify veya Vercel gibi hedeflere göre pre-deploy ve post-deploy kontrol listeleri üretir.

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.

Worktree Dostu Tasarım

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.

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.

Çoklu CLI Desteği

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.

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.

Hangi Projeler İçin Uygun?

Agentic Workflow en çok şu tip projelerde anlam kazanır:

• Birden fazla modülü olan web, mobil veya backend projeleri
• AI agent ile düzenli görev kapatmak isteyen ürün ekipleri
• Backlog, test, review ve deploy disiplinini tek akışta toplamak isteyen ekipler
• Worktree ile paralel geliştirme yapan teknik ekipler
• Claude Code ana araç olsa bile Codex, Gemini, Kimi veya OpenCode çıktısı da üretmek isteyen ekipler
• Migration, auth, ödeme, güvenlik veya production deploy riski taşıyan kod tabanları

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.

Başlamadan Önce Gereksinimler

Repo, temel olarak şu araçlara ihtiyaç duyar:

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.

Uygulama Stratejisi

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:

1. Önce mevcut projeyi Codebase olarak bağlayın ve /bootstrap ile manifest üretin.
2. Başlangıçta yalnızca /task-plan, /task-hunter ve /task-review akışını kullanın.
3. Test ve pre-push hook'larını proje gerçeklerine göre doğrulayın.
4. Deploy modüllerini production ortamına bağlamadan önce staging üzerinde deneyin.
5. Çoklu CLI transform çıktılarını, gerçekten kullanacağınız araçlar için üretin.
6. İlk birkaç task sonunda hatalı varsayımları backlog veya proje kurallarına geri yazı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.

Ürün ve Teslimat Perspektifi

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:

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.

Sık Sorulan Sorular

Agentic Workflow sadece Claude Code için mi?

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.

Backlog.md neden zorunlu?

Çü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.

Bu sistem küçük projeler için fazla mı?

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.

Agentic Workflow kod kalitesini tek başına garanti eder mi?

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 bu yaklaşımı nerede kullanabilir?

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.

Sonuç

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