Agent benimsemesinin sessizce tökezlediği yer, gereksinimlerden koda uzanan süreçtir. Agent kötü kod yazmadı. Sorun şu: altı hafta sonra kimse bir değişikliğin hangi gereksinimden çıktığını, kapsamı kimin onayladığını ya da gözden geçiren kişinin kabul etmeden önce hangi kanıtı gördüğünü gösteremiyor. Kod hızlıca geldi. Kayıt gelmedi.
Bu eğitim, kaydı bilinçli olarak inşa ediyor: yazılı bir gereksinimden birleştirilmiş bir pull request'e uzanan, her adımını açıp inceleyebileceğiniz tek bir zincir. GitHub'ın Spec Kit'i aynı boşluğu depodaki dosyalarla kapatıyor. Bu rehber ise aynı sorunu bir çalışma sistemiyle çözüyor; Sharkly kullanıyoruz çünkü tüm zinciri tek bir Task üzerinde tutuyor, ancak bu desen aynı bağlantıları tutabilen her takip aracına uyarlanabilir. Önce işleyiş döngüsünü görmek isterseniz, AI agent proje yönetimi rehberimizle başlayın.
TL;DR
İzlenebilir bir gereksinimden koda iş akışı, her artefaktın kendisine yol açan artefaktı işaret ettiği iş akışıdır: gereksinim, Task, alt görevler, çalıştırmalar, pull request, kabul. Sharkly'de gereksinim bir Task'a dönüşür, bir Agent Plan modunda iş kırılımını önerir ve bir kişi bunu onaylar, her alt görev bir yürütme günlüğüyle birlikte yalıtılmış bir worktree'de çalışır, pull request Task ID'si üzerinden geri bağlanır ve bir kişi sonucu başlangıçta yazılan kabul kriterlerine göre kabul eder. Agent'lar araştırır, yürütür, test eder ve raporlar. Yönü insanlar belirler, yetkiyi insanlar verir ve sonucu insanlar kabul eder.
İzlenebilirlik ne anlama gelmeli
İzlenebilirlik, sonunda ürettiğiniz bir rapor değildir. Zincirin bir özelliğidir: her halka kendinden önceki sayesinde vardır ve zinciri her iki yönde de yürüyebilirsiniz. Bir özelliği kapsamak için altı adım yeterlidir.
| Adım | Nerede bulunur | Onu bir önceki adıma bağlayan nedir |
|---|---|---|
| Gereksinim | Task açıklaması, Requirement veya User Story türü | Onu yazan kişi |
| Kırılım | Üst Task altındaki alt görevler | Onaylanmış Plan modu önerisi |
| Yürütme | Task çalıştırmaları ve yürütme günlüğü | Atama artı hazır durumu |
| Kanıt | Kontrolleri ve sonuçları içeren Agent yorumu | Onu üreten çalıştırma |
| Değişiklik | Pull request | Dal, başlık veya gövdedeki Task ID |
| Kabul | Belirli bir kişi tarafından yapılan durum değişikliği | Kabul kriterlerine göre gözden geçirme |
Adımlardan biri eksikse zincir süs olmaktan öteye geçmez. En sık görülen boşluk son adımdır: değişikliği gereksinimle kimse karşılaştırmadığı hâlde birleştirilmiş bir pull request'in kabul sayılması.
1. Adım: Gereksinimi bir Task olarak yazın
Task, Sharkly'de izlenen işin temel birimidir ve yazılım geliştirme için kurulmuş bir Space, Requirement, Bug, Task ve User Story görev türleriyle başlar. Üst görev için Requirement veya User Story kullanın. Tür, hangi özel alanların ve hangi Workflow durumlarının geçerli olacağını belirler; böylece bir Requirement, Bug iş akışını kirletmeden kendi gözden geçirme durumunu taşıyabilir.
Yükü açıklama taşır. Sohbeti hiç görmemiş biri için yazın: iş neden önemli, neler kapsam içinde neler dışında, ilgili dosyalar veya gözlemlenen davranış, hâlihazırda alınmış kararlar ve tamamlanmanın nasıl gözden geçirileceği. Bu son madde kabul kriterleridir ve altıncı adımın çıpasıdır. Henüz yazamıyorsanız gereksinim hazır değildir; Backlog tam da bunun için var: bir Agent'a atanmış bir Task, orada beklediği sürece başlamaz.
Depoları Space düzeyinde ekleyin ki her alt görev bunları devralsın. Deposu bağlanmamış bir Agent, Space'in Git depolarına geri döner; çok Task'lı bir özellik için istediğiniz davranış da budur.
2. Adım: Kırılımı bir Agent şekillendirsin, sonra siz onaylayın
Task'ın Agent sohbetini açın ve oturumu Plan moduna alın. Plan modunda Agent, incelemeniz için eylemler önerebilir ve Sharkly planlanan Task ile alt görevleri ancak siz öneriyi onayladıktan sonra oluşturur. İşi başlatmadan onaylayabilir ya da onaylayıp işi başlatabilirsiniz.
Çoğu ekibin atladığı adım budur ve kırılımı doğaçlama olmaktan çıkarıp izlenebilir kılan da bu adımdır. Öneri, işe dönüşmeden önce görünür olur: kapsamı genişleten alt görevi çıkarın, Agent'ın atladığı migration adımını ekleyin. Alt görevler üst görevleriyle aynı Space'te kalır ve Sharkly kendi kendini üst edinmeyi ve döngüleri reddeder, böylece hiyerarşi bir ağaç olarak kalır.
Tek bir rolün üstesinden gelebileceği bir gereksinim için tek bir Agent kullanın. Liderin hedefi yorumlaması, test yazarı gibi diğer Agent üyelerini devreye sokması ve sonuçlarını tek bir Task'ta toplaması gerektiğinde bir Crew kullanın. Üç dosyalık bir değişiklik için Crew, izlenebilirlik katmadan yalnızca hareketli parça sayısını artırır. Sharkly Crews rehberimiz lider öncelikli modeli ele alıyor.
Sohbette kararlaştırılan her şeyi Task açıklamasına kopyalayın. Bir Task üzerindeki sohbet yorum değildir ve Activity'de görünmez; dolayısıyla yalnızca orada yaşayan bir karar zincir açısından görünmezdir.
3. Adım: Yalıtım içinde, iz bırakarak yürütün
Her alt görevi Assignee denetimi üzerinden bir Agent'a atayın, ardından Backlog'dan çıkarın. Sharkly durum kategorisini ve yürütmeye hazır olup olmadığını kontrol eder, çalıştırmayı kuyruğa alır ve seçili Computer'a gönderir; burada yerel servis yalıtılmış bir görev dizini hazırlar ve Runtime'ı başlatır.
İki ayrıntı bu adımı dürüst tutar. Çalıştırma; Task başlığını ve açıklamasını, son yorumları ve izin verilen durumlarıyla birlikte Task türü Workflow'unu içerir; böylece Agent bir özetten değil, doğrudan gereksinimden çalışır. Ayrıca depoya bağlı her çalıştırma Temporary modunda kendi worktree'sini alır, böylece paralel alt görevler birbirinin üzerine yazamaz. Agent'ları merge çakışması olmadan paralel çalıştırma yazımız yalıtımın fan-out'u neden güvenli kıldığını açıklıyor.
İlerleme, iz olayları ve sonuç Task'a geri döner. Yürütme günlüğü; çalıştırmanın neden kuyruğa alındığını, ne zaman başlayıp bittiğini, araç çağrılarını ve Runtime olaylarını, tetikleyici kaynağını ve hata ayrıntılarını kaydeder. Bu günlük dördüncü adımdır.
4. Adım: Pull request'i ID ile bağlayın
GitHub organizasyonunu bir kez bağlayın, ardından Task ID'sini pull request başlığına, açıklamasına veya kaynak dal adına koyun. Tek başına SH-312 de Fixes SH-312 de bağlantıyı oluşturur. Linkback'ler, Task URL'sini pull request'e yorum olarak ekler; özel depolar için varsayılan olarak açıktır.
Şimdi sınırı çizelim, çünkü izlenebilirlik açısından bu önemli: fixes ve closes gibi kelimeler ekstra bir anlam taşımaz ve bir pull request'i birleştirmek Task durumunu değiştirmez. Sharkly değişikliği Task'a bağlar; Task'ın bittiğine karar vermez. Durum bir insan kararı olarak kalır; altıncı adımın bütün amacı da budur. Bir Jira ticket'ını AI agent'a atayıp PR geri alma rehberimiz aynı bağlantıyı takip aracı tarafından gösteriyor.
5. Adım: Gereksinime göre gözden geçirin, sonra kabul edin
Bir Agent, bir Task'ı insan incelemesi bekler durumda bırakabilir ve bu sinyal sorumlu kişinin Inbox'ında Primary altında görünür. Sırayla üç şeyi okuyun: birinci adımdaki kabul kriterleri, Agent'ın çalıştırdığı kontrolleri ve belirsiz kalan noktaları listeleyen yorumu ve yürütme günlüğü. Ancak ondan sonra diff'e bakın.
Değişikliği ayrı bir test Task'ı doğruluyorsa, bu ilişkiyi açıkça kaydedin. Organization Owner'ları ve Admin'leri özel bağlantı türleri oluşturabilir; dokümanların kendi örneği olan validates / is validated by, bu adımın izlenebilirlik kenarıdır. İlişkiler kendi başına durumu değiştirmez, dolayısıyla kabul yine bir kişinin yaptığı durum değişikliği olmak zorundadır.
Burada bir kategori kuralı sizi korur: bir Task'ı Completed'a taşımak onu terminal yapar ama hâlihazırda etkin olan bir çalıştırmayı iptal etmez. Agent hâlâ çalışıyorsa önce iptal edin, sonra karar verin.
Zincir nerede kopar
Yukarıdaki iş akışında bilinen üç kırılma noktası var ve bunları açıkça belirtmekte fayda var.
Sohbette bırakılan sonuçlar. Bağımsız Agent Chat oturumları, onları oluşturan kişiye aittir. Tasarım orada netleştiyse Task'ın bundan haberi olmaz.
Task dışında başlatılan çalıştırmalar. Bir otomasyon iş akışındaki Run Agent eylemi Task oluşturmaz; çalıştırma Agent üzerinde kaydedilir. Gecelik bir kontrol için sorun değil, özellik geliştirme için yanlış.
Kayıt yerine dosyalar. Spec Kit'in spec.md, plan.md ve tasks.md dosyaları, tek bir depoda çalışan tek geliştirici için güçlü bir zincirdir. Ekip yalnızca sizseniz bunları kullanın. İkinci bir kişinin sizin çalışma kopyanızı açmadan gözden geçirmesi, kabul etmesi ya da ne olduğunu sorması gerekiyorsa paylaşılan bir çalışma sistemi kullanın. Sharkly, Claude Code, Codex veya diğer yürütme araçlarının yerine geçmez; onların etrafında zinciri görünür tutan katmandır. Dokümanlar her kavramı daha ayrıntılı olarak docs.sharkly.ai adresinde ele alıyor.
SSS
Gereksinimden koda ifadesi, gereksinimi Agent'ın yazdığı anlamına mı gelir? Hayır. Gereksinimi ve kabul kriterlerini bir kişi yazar. Bir Agent kod tabanını araştırıp Plan modunda bir kırılım önerebilir, ancak öneri ancak bir kişi onayladıktan sonra Task'lara dönüşür.
Gereksinimi Jira'da tutup yine de izi elde edebilir miyim? Evet. Jira içe aktarma ve senkronizasyon, kuruluşunuzun okuduğu takip aracını korurken yürütme kaydını Sharkly tutar. İnsan-agent ekipleri için Jira alternatifleri yazımız, takip aracının kendisinin değiştirilmesinin gündemde olduğu durumu ele alıyor.
Pull request incelemeden önce birleşirse ne olur? Task durumu değişmez, dolayısıyla zincir birleştirilmiş bir değişikliğe sahip, kabul edilmemiş bir Task gösterir. Bu doğru sinyaldir: bir kişi hâlâ bir karar borçludur.
İlk izlenebilir özellik ne kadar küçük olmalı? Bir gereksinim, iki üç alt görev, bir Agent. Claude Code proje yönetimi rehberimiz döngüyü tek bir Task üzerinde baştan sona çalıştırıyor.
