Kuyruğunuza dokuz dosyada 340 değişmiş satır içeren bir pull request düşüyor. Bunu bir kodlama ajanı yazdı. Diff, ajandan ne yapmasının istendiğini, hangi yaklaşımları deneyip vazgeçtiğini, değişikliğin çalıştığına kendini ikna etmek için ne çalıştırdığını ya da nerede kolaya kaçtığını bildiğini size söylemez. Böylece iki şeyden birini yaparsınız: üstünkörü göz atıp onaylarsınız veya tüm değişikliği sıfırdan yeniden türetirsiniz. İlki, kötü kodun üretime nasıl çıktığıdır. İkincisi, ajanın size hiçbir şey kazandırmadığı anlamına gelir.
Yapay zeka tarafından üretilen kodu iyi incelemek, bir iş arkadaşınızın PR'ını incelemekten farklı bir iştir; çünkü yazar yanınıza oturup gerekçelerini açıklayamaz. Çözüm, diff'i kanıtlarıyla birlikte incelemektir: hedef, çalıştırılan kontroller ve ajanın önceden işaret ettiği sınırlamalar. Sharkly tam da bunun üzerine kurulmuştur. Sharkly, kodlama ajanlarınızın (Claude Code, Codex, Gemini ve diğerleri) üzerinde durur ve her çalıştırmanın hedefini, değişikliğini, doğrulama sonuçlarını ve insan incelemesini terminallere ve PR açıklamalarına dağılmak yerine tek bir Görev'de tutar.
Bu kılavuz, bunun arkasındaki işletim modelini adım adım ele alır: işi kimin atadığı, kimin çalıştırdığı, kimin incelediği, kimin kabul ettiği, bir ajanın işini insanınkinden ayıran durumlar ve kapılar ve talepten merge edilmiş bir PR'a kadar işlenmiş bir örnek.
Hızlı yanıt
Yapay zeka tarafından üretilen kodu diff düzeyinde değil, Görev düzeyinde inceleyin. Ajandan bir değişiklik özeti, çalıştırdığı typecheck/test/build sonuçlarını ve bilinen sınırlamaları ortak bir Görev'e eklemesini isteyin, ardından o Görev'i bir inceleme durumuna taşıyın. Bir insan kanıtları diff ile birlikte okur, değişiklik ister veya kabul eder ve merge kararını verir. Ajanlar üretir ve doğrular; insanlar kabul eder.
Diff'i tek başına incelemek neden başarısız olur
Kod okumak, yazmaktan daha zordur. Kod incelemesinin iyi belgelenmiş bir gerçeği şudur: inceleyen kişi, yazardan daha az bağlama sahiptir ve yazar bir ajan olduğunda bu boşluk tamamen aleyhinize işler. Bir GitHub diff'i size varış noktasını gösterir, asla izlediği yolu göstermez. Ajanın önce bir önbellekleme katmanı denediğini, bir yarış durumuna çarptığını ve onu geri aldığını göremezsiniz. Test paketini çalıştırdığını ve değişiklikle ilgisiz, kararsız çalışan bir testin başarısız olduğunu göremezsiniz.
Bu bağlam olmadan inceleme iki başarısızlık moduna indirgenir. Kör onay, ajanın hiç düşünmediği bir uç durumu sessizce bozan makul görünen kodu onaylar. Değişikliği baştan tamamen türetmek, gerekçeyi kendiniz yeniden kurmanıza yol açar; bu noktada ajanın hız avantajı yok olur. Üç ajan aynı anda PR açarken ikisi de ölçeklenmez. Çıkış yolu, ajanın yalnızca çıktısını değil, işini de incelenebilir kılmaktır.
Görev düzeyinde kanıt gerçekte ne anlama gelir
Görev düzeyinde kanıt, bir Ajanın Görev'ine eklediği kayıttır: üzerinde çalıştığı hedef, ürettiği değişiklik, çalıştırdığı kontroller ve hakkında bilgi sahibi olduğu sınırlamalar. Çıplak bir diff yerine, köken izi taşıyan bir diff elde edersiniz.
Pratikte kanıt paketi dört şeyden oluşur:
- Hedef ve kabul kriterleri, Görev açıklamasında yer alır; böylece inceleme, makul görünene göre değil, istenene göre ölçülür.
- Değişiklik özeti, ajanın kendi sözleriyle: neye dokunduğu ve neden.
- Doğrulama sonuçları: ajanın devretmeden önce çalıştırdığı typecheck, test ve build çıktısı.
- Bilinen sınırlamalar: ajanın saklamak yerine işaret ettiği uç durumlar, varsayımlar ve takip işleri.
Bunların hepsi Görev'e geri döner. Yürütme, engeller, sonuçlar ve takip tartışmaları tek bir zaman çizelgesinde yaşar; böylece inceleyen kişi bir PR'ı, bir Slack konuşmasını ve yarı hatırlanan bir prompt'u birleştirmek yerine tek bir kaydı açar. Bu, izlenebilir bir gereksinimlerden koda iş akışının arkasındaki disiplindir: kanıt, teslimatın bir parçasıdır.
İşletim modeli: kim atar, kim çalıştırır, kim inceler, kim kabul eder
İyi inceleme, net rollere bağlıdır. Sözleşme kısadır: ajanlar araştırır, yürütür, test eder ve raporlar; insanlar yön belirler, yetki verir ve sonucu kabul eder. Otomasyon, ekip muhakemesinin gerektiği yerde durur.
| Rol | Kim | İş |
|---|---|---|
| Atayan | Bir kişi (genellikle Görev Sahibi) | İhtiyacı tanımlar, kabul kriterlerini belirler, Görev'i atar |
| Çalıştıran | Bağlı bir Computer üzerinde, bir Runtime aracılığıyla bir Ajan | Görev'i üstlenir, izole bir worktree'de yürütür, kanıt ekler |
| İnceleyen | Bir kişi | Diff'i kanıtlarla karşılaştırarak okur, değişiklik ister veya onaylar |
| Kabul eden | Bir kişi (Sahip veya yetkilendirilmiş bir onaylayıcı) | Nihai kabul ve merge/release kararını verir |
Sharkly, Claude Code, Codex veya diğer yürütme araçlarının yerini almaz. Ekibinizin hâlihazırda kullandığı araçların etrafına ortak Görev, Computer, bağlam ve inceleme katmanını ekler. Runtime kodu yazar; Sharkly incelemenin kimin kuyruğuna düşeceğine ve bir insan bakmadan önce hangi kanıtların hazır olması gerektiğine karar verir. Atama tarafının daha ayrıntılı hâlini isterseniz, ajan işini kimin atadığına ve kimin kabul ettiğine bakın.
Durumlar ve inceleme kapıları: ajanlar İncelemeye hazır durumuna, insanlar Bitti durumuna taşır
İnceleme kapısı bir durum sınırıdır. Sharkly'de her görev durumu, sistem anlamı taşıyan sabit bir kategoriye aittir: Backlog (beklemede), Başlamadı (hazır, başlamamış), Başladı (devam ediyor) ve Tamamlandı (nihai). Birkaç görünür durum aynı kategoriyi paylaşabilir; bu nedenle bir görev türünün iş akışı, herhangi bir şey Tamamlandı'ya ulaşmadan önce Geliştirme ve İncelemeye hazır'ı iki ayrı Başladı durumu olarak çalıştırabilir.
Kapıyı gerçek kılan şey bu yapıdır. Bir Ajan, bir Görev'i Geliştirme'den İncelemeye hazır'a taşıyabilir ve Görev'i insan incelemesi bekler hâlde bırakabilir. Görev'i kendi başına Tamamlandı durumuna taşıma yetkisi yoktur. Kabul, tasarım gereği insanın yaptığı bir geçiştir.
| Durum | Kategori | Buraya kim taşır |
|---|---|---|
| Backlog | Backlog | İşi beklemeye alırken kişi |
| Yapılacak | Başlamadı | Görev hazır olduğunda kişi |
| Geliştirme | Başladı | Görevi üstlenip üzerinde çalıştığında ajan |
| İncelemeye hazır | Başladı | Kanıt eklendiğinde ajan |
| Bitti | Tamamlandı | Kabul ettikten sonra kişi |
İş akışını, Tamamlandı durumuna geçişin bir insan gerektireceği şekilde yapılandırın; o zaman ajanlar izleyebileceğinizden daha hızlı üretse bile ayakta kalan bir inceleme kapınız olur. Bu, kodlama ajanları için insanı döngüde tutmanın mekanik hâlidir ve ajanları merge etmeden önce nerede durduracağınıza karar verdiğiniz yerdir.
İşlenmiş bir örnek: talepten merge edilmiş PR'a
SH-312'yi ele alalım: "Herkese açık arama uç noktasına rate limiting ekle, API anahtarı başına dakikada 60 istek."
- Bir kişi SH-312'yi bu hedefle ve iki kabul kriteriyle açar: sınırı aşan istekler HTTP 429 döndürür ve sınır IP başına değil, anahtar başına geçerlidir. Görev, Yapılacak durumunda başlar.
- Bir Ajan onu üstlenir, Geliştirme'ye taşır ve izole bir worktree'de çalıştırır; böylece checkout'u aynı repo üzerinde çalışan diğer ajanlarla asla çakışmaz. (Paralel çalıştırmaların temiz kalmasının nedeni worktree'lerdir; bkz. görev başına bir checkout.)
- Ajan token-bucket tabanlı bir sınırlayıcı uygular, bir PR açar ve kanıtlarını SH-312'ye ekler: bir değişiklik özeti, geçen typecheck ve birim testleri, build sonucu ve bir bilinen sınırlama: "Bucket, süreç belleğinde yaşar; bu yüzden sınırlar deploy'da sıfırlanır ve instance'lar arasında paylaşılmaz."
- Ajan SH-312'yi İncelemeye hazır durumuna taşır. Görev, diff ve kanıtlarla birlikte bir insanın kuyruğuna düşer.
- İnceleyen kişi önce bilinen sınırlama notunu okur, bellek içi bucket'ın şimdilik uygun olduğuna karar verir ve tek bir değişiklik ister: 429 yanıtında
Retry-Afterbaşlığını döndür. Ajan değişikliği yapar ve güncellenmiş test çıktısını yeniden ekler. - İnceleyen kişi kabul eder, PR'ı merge eder ve SH-312'yi Bitti durumuna taşır; paylaşımlı bir sınırlayıcı için takip ticket'ı zaten bağlanmıştır.
İnceleme dakikalar sürdü çünkü inceleyen kişi değişikliği hiç yeniden kurmadı; bu işi kanıtlar yaptı. Bu, issue'dan incelemeye Claude Code proje yönetimi ile aynı döngüdür; kanıt paketi, incelemeyi darboğaz olmaktan çıkarıp hızlandırır.
Kanıtlar hızlı nasıl incelenir ve ne zaman hafif davranılır
Her değişiklik tam kapsamlı işlem gerektirmez. Bir karar kuralı kullanın.
Değişiklik auth, faturalandırma, veri migrasyonları, herkese açık API'ler veya geri alınması zor herhangi bir şeye dokunuyorsa ağır davranın: diff'i satır satır okuyun, testleri kendiniz yeniden çalıştırın ve bilinen sınırlamalar notunu kendi uç durumlarınızla karşılaştırın. Değişiklik bir metin düzeltmesi, iyi test edilmiş bir iç refactor veya kontrolleri yeşil bir bağımlılık güncellemesiyse hafif davranın: özeti okuyun, diff'e göz atın, doğrulamanın geçtiğini teyit edin ve kabul edin.
Hızlı bir ağır inceleme kontrol listesi:
- Diff her kabul kriterini karşılıyor mu, yalnızca mutlu yolu değil?
- Ajan kontrolleri gerçekten çalıştırdı mı, yoksa çalıştırdığını mı iddia etti? Eklenen çıktıyı doğrulayın.
- Bilinen sınırlamalar notunu okuyun. Herhangi bir sınırlama takip işi olmaktan çok bir engelleyici mi?
- Değişiklik istekle sınırlı mı, yoksa ajan ilgisiz dosyalara mı dokundu?
Hâlihazırda birkaç kodlama ajanı çalıştırıyorsanız, bu, Sharkly'nin tek yerden yönetmenizi sağladığı iş akışıdır: Görev'i atayın, ajanın kanıt eklemesine izin verin, kapıda inceleyin. Parçaları worktree'ler, PR şablonları ve bir durum panosuyla elle kurabilir veya Sharkly'yi indirin ve Görev, kanıt ve kapıyı tek bir sistem olarak elde edin.
SSS
Yapay zeka tarafından üretilen kod için görev düzeyinde kanıt nedir? Bir ajanın diff'in yanı sıra Görev'ine eklediği kayıttır: hedef, değişiklik özeti, çalıştırdığı typecheck/test/build sonuçları ve bilinen sınırlamalar. Bu paketi incelemek, yalnızca bir diff'i incelemekten daha hızlı ve daha güvenlidir.
Bir yapay zeka ajanı kendi kodunu onaylayabilir mi? Hayır ve inceleme kapısının amacı da budur. Bir ajan bir Görev'i İncelemeye hazır durumuna taşıyabilir, ancak Tamamlandı durumuna geçiş insan kararıdır. Ajanlar üretir ve doğrular; insanlar kabul eder.
Yapay zeka kodunu kör onay vermeden nasıl daha hızlı inceleyebilirim? Çabayı riske göre ayarlayın. Her değişiklik için kanıtları okuyun, ancak satır satır incelemeyi ve testleri yeniden çalıştırmayı auth ve migrasyonlar gibi yüksek riskli alanlara saklayın. Ajanlar insanları geride bıraktığında inceleme kapasitesinin nasıl ölçeklendiğine bakın.
Hâlâ pull request kullanıyor muyum? Evet. Ajanlar gerçek GitHub pull request'leri açar; Görev katmanı, kanıtları ve kapıyı onların etrafına ekler; böylece bağlamın yaşadığı tek yer PR olmaz.
