Bir kodlama ajanı bir görevi tamamladığında aynı boşluk ortaya çıkıyor. Bir farklılık (diff) ve neşeli bir “tamamlandı” mesajı alıyorsunuz, ancak neyin değiştiğini, neyin atlandığını, nelerin test edildiğini veya ajanın henüz tam olarak emin olup olmadığını öğrenemiyorsunuz. Bu yüzden diff'i tekrar okuyorsunuz, testleri kendiniz yeniden çalıştırıyorsunuz ve ajanın size teslim ettiğinde cevaplayabileceği soruları tekrar soruyorsunuz. İki ajan çalıştırmanız gerekiyorsa, bu maliyet iki katına çıkıyor. Sorun işin kendisi değil. Devir teslim (handoff): isteyen kişi ile yapan ajan arasında neyin geçtiği ve geri ne geldiğidir.
Bir kodlama ajanı devir teslim şablonu (handoff template), bir görevin eller değişirken taşıması gereken şeyin sabit bir yapısıdır: bir kişiden ajana iş atanırken ve bir ajandan tekrar kişiye (yorum aşamasında) geri dönerken. Her transferin şeklini sıfırdan icat etmek yerine, her seferinde aynı alanları doldurursunuz. Ajan, başlamadan neyin "tamam" anlamına geldiğini bilir; siz ise iş durduğunda aynı özet, kanıt ve açık soruları alırsınız.
Bu makale, Sharkly'yi iş akışı olarak kullanarak pratik olarak işe yarayan iki şablonu inceliyor: kodlama ajanlarınızın üzerindeki katman olan Sharkly, isteğin gönderilmesinden yayınlanmaya kadar bağlamı, ilerlemeyi, engelleyici durumları, sonuçları ve insan incelemesini görünür tutuyor. Zaten kodlama ajanlarınız var. Sharkly onları bir takıma dönüştürüyor ve bu devir teslim şablonu, her transferin bir tahminden ziyade bir kayıt olmasını sağlıyor.
Bir kodlama ajanı devir teslim şablonu nedir
Bir devir teslim şablonu, yapılandırılmış bir kontrol listesidir. Saf bir diff'in asla cevaplayamayacağı üç soruyu yanıtlar: ne istendi, ne oldu ve şimdi sıra kimde? Bu üç bilgi bir arada ilerlediğinde, sonraki çalışan üç ayrı parçayı yeniden inşa etmek yerine tek bir kaydı okur.
Şablonlamaya değer iki devir teslim vardır, çünkü ters yönlerde çalışırlar ve birbirlerine zıt şeyler taşırlar:
- İş Atama Devri (Assignment handoff) (Kişi veya lider Ajan, bir Ajana): İş başlamadan iletilen hedef, sınırlar ve tamamlanma tanımı.
- İnceleme Devri (Review handoff) (Ajan, bir kişiye): İş durduğunda iletilen değişiklik, çalıştığının kanıtı ve bir insanın hala yargılaması gereken kısımlar.
İkisini şablonlamak amacımız. Çoğu ekip kaba bir görev yazar ve geri dönüş yolunda hiçbir şey şablonlamaz; bu yüzden her inceleme bir sorgulama gibi başlar. Geri dönüş yolunu düzeltmek gereken yer tam da burasıdır.
Şablonun Kodladığı İşletme Modeli
Bir şablon, altındaki işletme modelinden başka hiçbir şeye bağlı değildir. Dört fiil, her bir çizginin kime ait olduğunu belirler: kim atar, kim çalıştırır, kim inceler, kim kabul eder. Ajanlar araştırır, yürütür, test eder ve raporlar. İnsanlar yön belirler, yetki verir ve sonucu kabul eder. Otomasyon, ekip kararına ihtiyaç duyulan noktada durur.
Bu söz, iki şablonun neden farklı alanlara sahip olduğunu açıklar. Bir Ajan, kabulün nasıl görüneceği konusunda asla tahmin yürütmemeli, bu yüzden atama şablonu isteği yazan kişiyi bunu not etmeye zorlar. Bir kişi de yeşil ışığın güvenliğin ne anlama geldiğini tahmin etmemeli, bu yüzden inceleme şablonu Ajanı çalışmasını göstermeye zorlar. İşte atama devrinin kopyala-yapıştır bloğu:
## Assignment handoff
Task ID: SH-###
Goal: one sentence, in plain language
In scope: the specific files, endpoints, or behaviors to touch
Out of scope: what to leave alone (auth, billing, public contracts)
Definition of done:
- [ ] observable acceptance criterion 1
- [ ] observable acceptance criterion 2
Constraints: framework, patterns, or limits to respect
Assignee: the exact Agent that owns this
“Out of scope” (Kapsam dışı) ve “definition of done” (Tamamlanma tanımı) satırları ağır yükü taşır. Bunlar olmadan bir ajan, sizin kastettiğiniz sonuç için değil, sadece geçebilecek bir diff için optimize eder. Bunlar olduğunda, tek bir kod satırı yazılmadan kabul kontrolü önceden yazılmış olur.
İnceleme Devri: Geri Dönenler
Geri dönüş şablonu çoğu iş akışının atladığı, ancak sizi kurtaracak olan şablondur. Bir Ajan bittiğinde size sadece “hazır” ve bir linkle ping atmamalıdır. Doldurulmuş bir yapı geri vermelidir:
## Review handoff
Task ID: SH-###
Summary: what changed, in 2-3 sentences
Acceptance: each definition-of-done item, checked with how it was verified
Tests: typecheck / unit / build results, pasted or linked
Diff: the PR or worktree branch
Known limits: what this does NOT cover, and any risky assumption
Open questions: decisions left for a human
“Known limits” (Bilinen sınırlamalar) ve “open questions” (Açık sorular) alanları, gerçek bir devir teslim ile yeşil onay işaretlerinden oluşan bir duvarı ayıran şeydir. Dürüst bir sınırlama (“Redis sayacı tek bir bölge varsayımı yapıyor”) kör bir birleştirmeyi bilgili bir birleştirmeye dönüştürür. Bu, görev düzeyinde kanıtlarla yapay zeka tarafından üretilen kodun nasıl inceleneceği konuluyla aynı prensibe sahiptir: inceleyici bir diff yerine bir iddia artı kanıt okur.
Netçe belirtilmesi gereken bir sınır vardır: inceleme devri bir birleştirme talebi değildir. Bir inceleme talebidir. Ajan sunar; kişi karar verir. Bu iki eylemi ayrı tutmak, incelenmemiş işin yayılmasını engeller.
Durumlar ve İnceleme Kapıları: Şablon Nerede Yaşıyor
Bir kaydırma tamponunda yaşayan bir şablon, kimsenin okumadığı bir şablondur. Devir teslim, ortak bir şeye bağlı olmalı ve durumlar (statuses) bunun doğal yuvasıdır. Her Görev tek bir kanalda ilerler ve her durum değişikliği, şablonuyla birlikte bir devir teslimdir:
| Status | Owner | Template attached |
|---|---|---|
| Todo | Person or leader Agent | Assignment handoff |
| In progress | Agent | (working in an isolated worktree) |
| Ready for review | Agent | Review handoff |
| Done | Person | acceptance note + merge decision |
Bunu okunabilir kılan kural şudur: Ajan bir Görevi "İncelemeye Hazır" durumuna taşır; Kişi ise onu "Tamamlandı" durumuna taşır. Bir Ajan asla kendi işini "Tamamlandı" olarak işaretlemez ve bir kişi asla ne olduğunu yeniden inşa etmek zorunda kalmaz, çünkü inceleme devri zaten Görev üzerinde yer alır. Sharkly'de yürütme, engelleyici durumlar, sonuçlar ve takip tartışmaları Görev zaman çizelgesine geri döner, böylece on ajan çalışırken onlarca terminal okumak yerine panoyu okursunuz. Bu, ajanların neler tamamladığını takip etmek ile commit geçmişinin bunu sonradan açıklamayı ummak arasındaki farktır. Otonom çalışmanın durması gereken yer kendisi bir tasarım tercihidir ve onay kapılarının nereye yerleştirileceği başlığında incelenir.
Uygulamalı Bir Örnek: Bilet Yönetiminden Birleştirilmiş PR'a
SH-441: “Raporlar sayfasına CSV dışa aktarma ekle.” adlı gerçek bir Görev alalım. Kodun değil, şablonların dolduğunu izleyin.
Bir kişi SH-441'i açar ve lider bir Ajan iş atama devrini tamamlar: hedef (“kullanıcıların mevcut raporu CSV olarak indirmesine izin vermek”), kapsam (raporlar kontrolörü ve yeni bir dışa aktarma modülü), kapsam dışı (auth, mevcut rapor sorguları) ve üç denetlenebilir öğeden oluşan bir tamamlanma tanımı (bir indirme düğmesi, virgüller ve tırnaklar için doğru kaçış dizileri, 10k satırlık bir fixture ile bir test). Atanılan Ajan bir arka uç (backend) Ajanıdır. Şablon bunu reddettiği için hiçbir şey muğlak değildir.
Arka uç Ajanı Görevi üstlenir, diğer çalışmalarla çakışmaması için bir yalıtılmış çalışma alanı içinde çalışır ve tamamlanma tanımı maddelerini kendi kontrol listesi olarak çalıştırır. Typecheck (yazı tipi kontrolü), birim testleri ve derleme yeşil olduğunda, SH-441'i dönüş şablonu doldurulmuş olarak "İncelemeye Hazır" durumuna taşır: kısa bir özet, her kabul maddesi doğrulama şekliyle işaretlenmiş hali, diff ve bilinen bir sınırlama (“100k satırdan fazla çıktı bellekte tamponlanır; akış uygulanmamıştır”).
Şimdi devir teslim yön değiştirir. Bir kişi bir kaydı okur, kaydırılan bir ekranı değil. Kaçış testini onaylar, bellek sınırını gerçek rapor boyutlarıyla tartarak şu an için kabul eder ve SH-441'i Tamamlandı olarak işaretleyerek birleştirmeyi tetikler. Her iki ekleminde de dolu bir şablon ve kimin hangi görevin sahibi olduğuna dair bir kayıtla: Bilet yönetiminden birleştirilmiş PR'a (pull request) ulaşılmıştır. Bu, ihtiyaçlardan koda izlenebilir ajan iş akışının uçtan uca ulaşmasıdır.
Şablon Ne Zaman Fazla Detaylı Olur
Şablonların bir maliyeti vardır, bu yüzden işte dürüst karar ikilisi. Tek bir Ajanın tek bir geçişte tamamladığı, hedef ve kabulün Görev başlığından açık olduğu küçük, iyi tanımlanmış çalışmalar için tam şablondan kaçının. İş, önemli bir eklemi (birçok ajan tarafından hedeflenen bir amaç, halka açık bir sözleşmenin değişmesi veya güvenlikle ilgili, faturalandırma veya kolayca geri alınamayan herhangi bir veri) geçtiği anda bunu kullanın. Bir şablon, kaybolan bağlama karşı bir sigortadır ve kayıp büyük zarar vereceği yerlerde sigorta almalısınız.
Bunların tümünü ortak bir pano ve disiplinle el ile çalıştırabilirsiniz. Ancak ajan, görev ve depoların sayısı arttığında ve disiplin ilk kaybedilen şey olduğunda işe yaramaz. Eğer halihazırda birden fazla ajan çalıştırıyorsanız, Sharkly görevlerini ve sonuçlarını yönetmek için tek bir yer sunar: iş ataması ve inceleme devirlerini taşıyan ortak Görevler, Görev bazlı atanmış Ajanlar, yalıtılmış çalışma alanları ve Ajanların İncelemeye Hazır olduğu ve Kişilerin Tamamlandı diye karar verdiği bir durum kanalı. Mevcut kodlama ajanlarınızı kullanmaya devam edin. Ajanlar arasındaki eklemler işten daha fazla maliyet almaya başladığında Sharkly'i indirin.
SSS
Kodlama ajanı devir teslim şablonu nedir? Bir görevin eller değişirken taşıdığı şey için sabit bir yapıdır. İki tanesi vardır: bir iş atama devri (hedef, kapsam ve tamamlanma tanımı, kişiden ajana) ve bir inceleme devri (özet, kanıt ve bilinen sınırlamalar, ajandan kişiye). Her seferinde aynı alanları doldurmak, bağlamın çalışanlar arasında bu şekilde buharlaşmasını engeller.
Neden sadece görevi değil, dönüş yolunu da şablonlamalıyız? Çoğu ekip bir görev yazar ve geri dönüş yolunda hiçbir şey şablonlamaz, bu yüzden her inceleme bir sorgulama gibi başlar. Özet, kontrol edilmiş kabul maddeleri ve bilinen sınırlamaları içeren inceleme devri, bir şablonun en çok zaman kazandığı yerdir. insan döngüsündeki kodlama ajanları başlığına bakın.
Bir ajan kendi işini tamamlanmış olarak işaretlemeli mi? Hayır. Bir Ajan'a bir Görevi dolu dönüş şablonu ile "İncelemeye Hazır" konumuna taşımasına izin verin; "Tamamlandı"ya geçme ve birleştirme kararını bir kişiye bırakın. "Sunulan" ile "kabul edilen" arasında bir ayrım yapmak, incelenmemiş kodun canlıya ulaşmasını engeller.
Şablon nerede yaşamalı? Tek bir ajanın gördüğü bir terminalde değil, ortak bir Görev üzerinde, durum değişikliğine bağlı olmalıdır. Devir teslim, şablonuyla birlikte bir durum olduğunda, bir sonraki çalışan tam olarak neyin kendisini beklediğini görür. Bu aynı zamanda çok sayıda ajan aynı anda bittiğinde incelemenin darboğaz haline gelmesini engeller.
Bunun için bir araca mı ihtiyacım var, yoksa manuel yapabilir miyim? Ortak bir pano ve disiplinle çalıştırabilirsiniz. Özel bir katman, birden fazla depo genelinde birden fazla ajanı koordine ettiğinizde ve manuel takibin iş haline geldiğinde karşılığını verir. Geniş kapsamlı bir ajan işleri için yapay zeka görev yöneticisi ile karşılaştırın.
