Bir kodlama ajanına küçük bir görev veriyorsunuz: başarısız olan bir testi düzelt. Yirmi dakika sonra ajan alakasız üç dosyayı yeniden yazmış, kabuğunuzda bulduğu DATABASE_URL hangisiyse ona karşı bir veritabanı göçü çalıştırmış ve başkasının kullandığı bir dala force-push yapmış oluyor. İstemde bunların hiçbiri istenmemişti. Ajanın makine üzerinde serbest yetkisi vardı, o da bu serbestliği sonuna kadar kullandı.
İzinler, bir ajanın nelere dokunabileceğine önceden karar verme biçiminizdir. Kodlama ajanı izni, belirli bir ajanın bir çalıştırma sırasında hangi dosyalara, komutlara, kimlik bilgilerine ve depolara erişebileceğini ve nerede bir insanın devreye girmesi gerektiğini söyleyen kuraldır. Doğru kurgularsanız, senaryodan çıkan bir ajan sizin çizdiğiniz kutunun içinde güvenle başarısız olur. Yanlış kurgularsanız, tek bir kötü çalıştırma üretime ulaşır.
Bu makale izin modelini katman katman ele alıyor, her adımda o adıma özgü hata biçimini adlandırıyor ve bugün uygulayabileceğiniz bir kontrol listesiyle bitiyor. Her katmanı somutlaştırmak için Sharkly'den yararlanıyor; çünkü Sharkly'nin işi kodlama ajanlarınızın üzerinde durup bu kapsamı tek bir yerde tutmak. Kodlama ajanlarınız zaten var. Sharkly onları bir ekibe dönüştürür ve bir ekibin kimin ne yapabileceğine dair kurallara ihtiyacı vardır.
Ajan izinlerinin bulunduğu üç katman
Bir kodlama ajanının izinleri tek bir ayar değildir. Üç ayrı yerde bulunurlar ve bunlardan birindeki boşluk diğer ikisini de boşa çıkarır.
- Çalışma zamanı (runtime), ajanın hangi araçları çağırabileceğine karar verir: bir dosyayı okumak, bir dosyayı düzenlemek, bir kabuk komutu çalıştırmak, ağa erişmek. Bu katman Claude Code, Codex, Gemini CLI ya da işi fiilen yürüten hangi ajan varsa odur.
- Makine, bu araçların nelere erişebileceğine karar verir: hangi dizinler, hangi kimlik bilgileri, hangi ortam değişkenleri, hangi ağ. Sharkly'deki bir Computer "bir Ajanın ihtiyaç duyduğu işletim sistemini, dosyaları, kimlik bilgilerini, ağ erişimini ve araçları sağlar", dolayısıyla gerçek hasar yarıçapı makinedir.
- Görev, niyetin sınırını belirler: bu çalıştırma hangi depoyla sınırlı, ajan hangi durumları ayarlayabilir ve bir insanın sonucu kabul ettiği nokta neresi.
Açıkça belirtilmesi gereken bir sınır var: izin, onay kapısı değildir. İzin, ajanın yapabildiği şeydir. Bir onay kapısı ise bir insanın karar verdiği yerdir. İkisine de ihtiyacınız var. Sıkı izinler ama kapı yoksa, sonucu kimse kontrol etmez. Kapı var ama izinler gevşekse, biri bakana kadar hasar çoktan verilmiştir.
1. Adım: Çalışma zamanının araçlarını sınırlayın
Ajanın devreye girdiği yerden başlayın. Çoğu kodlama ajanı bir izin sistemiyle gelir: araçlar için bir izin listesi ile bir reddetme listesi ve yıkıcı bir işlem çalışmadan önce sorulan bir onay. Örneğin Claude Code, belirli araçlara izin vermenize ya da onları reddetmenize olanak tanır ve kabuk komutlarını çalıştırmadan önce sorar; ayar adları çalışma zamanına göre değişir ve sık sık güncellenir, bu yüzden geçen yıl bulduğunuz bir kod parçasına değil, ajanınızın güncel dokümanlarına bakın.
Güvenli varsayılan, okumalarda cömert, yazmalarda cimri olmaktır. Ajan depoyu okuyabilsin, testleri çalıştırabilsin, tip kontrolü yapabilsin ve derleyebilsin; bunlar için onay sorulmasın. Dosya düzenlemelerini ve kabuk komutlarını ise bir onay sorusunun ya da açık bir izin listesinin arkasına koyun.
Bu hata biçiminin bir adı var ve teslim tarihi baskısı altında herkesin başvurduğu şey de bu: her şeyi atla modu. Her çalışma zamanında tüm onay sorularını kapatan bir bayrak vardır ve bu, gözetim altındaki bir oturum için kullanışlıdır. Tehlike, bu bayrağı gözetimsiz bir çalıştırma için açık bırakmaktır. Hiç sormak zorunda kalmayan bir ajan, yanlış çıkan bir plana göre çalışırken yanlış anladığı şeyi seve seve siler. İzlerken otomatik kabulü kullanın. Başından ayrıldığınızda kapatın.
2. Adım: Makineyi ve kimlik bilgilerini sınırlayın
Makine ajana her şeyi sunuyorsa çalışma zamanının araç listesi hiçbir işe yaramaz. Günlük kullandığınız makinede kabuk komutu çalıştırma izni olan bir ajan, her SSH anahtarını, her .env dosyasını ve kendi oturum açma bilgilerinizin erişebildiği her kimlik bilgisini okuyabilir. Bu hata biçimi sessizdir: ajan hiç görmemesi gereken bir üretim anahtarını kullanana kadar hiçbir şey yanlış görünmez.
İki hamle hasar yarıçapını küçültür. Birincisi, ajanları gerçek sırlarınızı tuttuğunuz dizüstü bilgisayarda değil, kapsamı sınırlandırılmış bir ortamda çalıştırın. Sharkly, bir Computer'ı kısa ömürlü ve tek kullanımlık bir kerelik kurulum token'ıyla kaydeder ve dokümanlar açık sözlüdür: bu token'ı yeniden kullanılabilir bir imaja, betiğe, Göreve veya yoruma koymayın. Computer bir konteyner, bir sunucu ya da yedek bir makine olsun, ajanın erişimi sizin değil o ortamın erişimidir. Ajanların siz çevrimdışıyken de çalışmasını istiyorsanız, onları açık duran dizüstünüz yerine uzak bir Computer'da çalıştırın.
İkincisi, yalnızca bir çalıştırmanın ihtiyaç duyduğunu verin. Bir Sharkly çalıştırmasının ortamı açık yapılandırmadan oluşturulur: bağlanmış depolar, ortam değişkenleri, gizli anahtar bağlamaları ve bir çalışma dizini. Bir Ajan, Space varsayılanından daha dar bir kod kapsamına ihtiyaç duyduğunda depoları o Ajana bağlayın; böylece bir ön yüz Ajanı fatura servisini asla checkout etmez. Her çalıştırmayı kendi izole worktree'sinde tutun; kötü bir düzenlemenin tek bir checkout'ta kalmasıyla iki ajanın aynı çalışma ağacını bozması arasındaki fark budur. Ev kuralı her alan için geçerlidir: yalnızca ürünün istediği yapılandırmayı girin ve parolaları ya da token'ları alakasız alanlara veya başlangıç komutlarına asla yapıştırmayın.
3. Adım: Görevi sınırlayın, birleştirmeyi insana bırakın
Son katman niyettir. Doğru şekilde sandbox'a alınmış ve kimlik bilgileri sınırlandırılmış bir ajan bile yanlış işi yapabilir: kendi görevini tamamlandı olarak işaretlemek, yarım kalmış bir değişikliği paylaşılan bir dala göndermek ya da bir PR'ın birleştirilmeye hazır olduğuna karar vermek.
İnsan-ajan sözleşmesinin yeri tam burasıdır. 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 muhakemesinin devreye girmesi gereken yerde durur. Bir ajanın taslak PR açmasına ve test çıktısını eklemesine izin verilmelidir; o PR'ı onaylamamalı ya da korumalı dalınıza birleştirmemelidir. Depo sunucusundaki dal koruması ile görev üzerindeki insan incelemesi, bu çizgiyi koruyan iki kilittir.
Sharkly'de bu sınırı görevin kendisi taşır. Bir Görev tipi Workflow, bir Ajanın hangi durumları seçebileceğini kısıtlar; böylece Ajan, işi sessizce bir insanın sahip olduğu "Tamamlandı" veya "Yayınlandı" durumuna taşıyamaz. Bir Ajan karar gerektiğinde, Görevi insan incelemesi ya da insan yanıtı bekleyecek şekilde bırakır ve bu, sorumlu kişinin kabul etmesi, değişiklik istemesi veya yeniden ataması için Gelen Kutusu'nda görünür. Yürütme, engeller, sonuçlar ve inceleme, beş ayrı terminale dağılmak yerine hep aynı Göreve döner.
Kendin yap kurulumunun ölçeklenmeyi bıraktığı yer de burasıdır. Tek ajan, tek depo, tek dikkatli mühendis: tüm izin modelini kafanızda tutabilirsiniz. İkinci ve üçüncü bir ajan, daha fazla depo ve bir ekip arkadaşı eklediğinizde, "burada her ajanın ne yapmasına izin var" sorusunu kimse ezberden yanıtlayamaz. Bir görev panosu bu kuralları paylaşılan ve incelenebilir bir yapılandırmaya dönüştürür: işi kim atadı, çalıştırmanın kapsamı neydi, hangi kanıt geri geldi ve kim kabul etti. Bu, kodlama ajanlarınızın üzerindeki yönetim katmanıdır. Bunu worktree'ler, sınırlandırılmış kimlik bilgileri ve dal korumasıyla elle kurabilir ya da mevcut kodlama ajanlarınızı Sharkly üzerinden çalıştırıp izinleri, görevleri ve incelemeyi tek bir yerden yönetebilirsiniz.
Bugün uygulayabileceğiniz izin kontrol listesi
Gerçek bir depoya dokunmasına izin verdiğiniz her ajan için şu listeyi gözden geçirin:
- Çalışma zamanı: okumalar ve testler onay sorulmadan izinli; düzenlemeler ve kabuk komutları kapılı; gözetimsiz çalıştırmalarda her şeyi atla modu kapalı.
- Makine: ajan günlük kullandığınız makinede değil, kapsamı sınırlandırılmış bir Computer'da çalışıyor; kurulum ve erişim token'ları tek kullanımlık ve asla commit edilmiyor.
- Kimlik bilgileri: yalnızca bu çalıştırmanın ihtiyaç duyduğu ortam değişkenleri ve gizli anahtar bağlamaları var; alakasız alanlara hiçbir şey yapıştırılmamış.
- Depo kapsamı: ajan, Space'teki her depoya değil, işinin gerektirdiği depolara bağlı.
- İzolasyon: her çalıştırma kendi worktree'sini alıyor, böylece kötü bir değişiklik paylaşılan bir checkout'u bozamıyor.
- Görev kapsamı: ajan çalışma durumlarını ayarlayabiliyor ama bir görevi insanın sahip olduğu kabul edildi veya yayınlandı durumuna taşıyamıyor.
- Birleştirme: dal koruması ve görev düzeyinde kanıtla yapılan insan incelemesi, ajanın PR'ı ile main arasında duruyor.
Satırlardan biri gevşekse, neden önemli olduğunu size öğreten olaydan sonra değil, bir sonraki çalıştırmadan önce sıkın.
SSS
Kodlama ajanı izinleri ile onay kapıları arasındaki fark nedir? İzinler, bir ajanın teknik olarak neleri yapabildiğini tanımlar: hangi dosyalara, komutlara ve kimlik bilgilerine erişebildiğini. Onay kapısı ise bir insanın ajanın yaptığını kabul edip etmeyeceğine karar verdiği noktadır. İkisine de ihtiyacınız var; çünkü sıkı izinler bile bir insanın onaylaması gereken işler bırakır ve ajanın zarar verme izni zaten varsa onay kapıları işe yaramaz.
Bir kodlama ajanına kendi PR'larını birleştirme izni hiç verilmeli mi? Hayır, varsayılan olarak verilmemeli. Ajan taslak bir PR açsın ve doğrulama çıktısını eklesin; birleştirmeyi ise bir insana ya da zorunlu bir incelemeye bırakın. Gerekçe insan-ajan sözleşmesidir: ajanlar yürütür ve raporlar, insanlar kabul eder ve yayınlar. Bu, işin büyük kısmını ajanın yaptığı insanın döngüde olduğu iş akışları için de geçerlidir.
Bir ajanı tüm izin onayları kapalıyken çalıştırmak güvenli mi? Yalnızca onu izlerken. Otomatik kabul modları, yanlış bir adımı durdurabileceğiniz gözetimli oturumlar için kullanışlıdır. Gözetimsiz ya da gece boyu süren çalıştırmalarda onay sorularını veya bir izin listesini açık tutun ve bir hata ortamda kalsın diye ajanı kapsamı sınırlandırılmış bir makinede çalıştırın.
