Bir yapay zeka aracısına API projenize yazma erişimi verirseniz, gerçek hasara yol açabilir. Kötü niyetli olarak değil; aracılar sadece komutun ima ettiğini yapar. Birine “kullanıcı uç noktalarını temizle” diye sorarsanız, hala bağımlı olduğunuz aktif bir rotayı silebilir. “Şemayı güncelle” diye sorarsanız, diğer üç uç noktanın referans aldığı bir veri modelinin üzerine yazabilir. Aracının üretimde neyin yayında olduğu hakkında hiçbir fikri yoktur. Sadece dokunmasına izin verilen kaynakları görür ve onlara dokunur.
Bu yeni bir risk sınıfıdır. Bir insan bu düzenlemeleri yaptığında, bir uç noktayı silmeden önce tereddüt ederdi. Terminalinizden bir döngüde çalışan bir aracı tereddüt etmez. Komutu çalıştırır, başarılı bir yanıt alır ve devam eder. Eğer bu komut ana dalınıza (main branch) ulaşırsa, değişiklik tasarım kaynağınızda zaten yayına alınmış demektir.
Çözüm, aracıları kilitlemek değil. Onlara kaçamayacakları bir sanal alan vermektir. Apidog'un Yapay Zeka Dalı (AI Branch) tam olarak bunu yapar: aracı tarafından yapılan her düzenleme izole bir dala iner, kaynak dalınız dokunulmadan kalır ve bir insan farkı (diff) inceleyip birleştirene kadar ana dala hiçbir şey ulaşmaz. Bu yazı, CLI akışını baştan sona anlatır, ardından bu akışın etrafında olması gereken genel güvenli aracı hijyenini kapsar. Özelliğin arkasındaki tasarım mantığı için, Yapay Zeka Dalı ve daha güvenli aracı odaklı değişiklikler üzerine daha ayrıntılı yazıyı okuyun; bu yazı uygulamalı bir kılavuzdur.
Aracı yazma erişimi neden varsayılan olarak tehlikelidir
Çoğu araç, bir aracıya tek düzeyde erişim verir: proje. Eğer aracı bir uç nokta oluşturabiliyorsa, bir tane de silebilir. Bir şemayı güncelleyebiliyorsa, onu uyumsuz bir şeyle de değiştirebilir. "Aracı bir değişiklik önerdi" ile "değişiklik doğruluk kaynağınızda" arasında bir boşluk yoktur.
Üç hata modu tekrar tekrar ortaya çıkar:
- Üzerine Yazma. Aracı, API'nizin kısmi bir anlayışıyla bir şemayı yeniden oluşturur ve diğer uç noktaların ihtiyaç duyduğu alanları düşürür.
- Silme. Aracı, uç noktaları “birleştirir” ve canlı istemciler tarafından hala çağrılan rotaları kaldırır.
- Sessiz Sapma. Aracı, bir oturum boyunca düzinelerce küçük düzenleme yapar. Tek bir değişiklik yanlış görünmez, ancak toplamda yayınladığınızdan sessizce sapar.
Bunların hiçbiri egzotik değildir. Yanlış dalda işini yapan bir aracının normal çıktısıdırlar. Amaç, yanlış dala ulaşmayı imkansız hale getirmektir.
Temel düzeltme: izole bir yapay zeka dalı
Yapay Zeka Dalı (AI Branch), harici yapay zeka ve CLI işlemleri için oluşturulmuş özel bir sprint dalı türüdür. Bir tane oluşturduğunuzda, aracı içinde düzenlemeler yapar ve değişiklikler orada kalır. Birleştirmeye karar verene kadar kaynak dalınız ve ana dalınız etkilenmez.
Bunu CLI'dan oluşturursunuz. Önce Apidog CLI'yı kurun ve doğrulayın:
npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
Ardından yapay zeka dalını oluşturun. Belgeler, daha sonra kolayca fark edilmesi için onu tarih, kaynak dal ve amaç ile adlandırmanızı önerir:
apidog branch create --type ai \
--name "ai/20260708-from-main-user-register" \
--from main \
--project <PROJECT_ID>
Burada iki şey önemlidir. Dal, main'den oluşturulur, ancak oluşturmak main'i etkilemez. Ve dal boş başlar. Bir Yapay Zeka Dalı, projenizin tamamını otomatik olarak kendi içine kopyalamaz; yalnızca aracının açıkça getirdiği kaynakları barındırır. Bu kasıtlı bir güvenlik özelliğidir. Aracı yalnızca içe aktardığı şeyi düzenleyebilir, bu nedenle etki alanı (blast radius) projenin tamamı değil, sizin belirlediğiniz kapsamdır.
Herhangi bir dal komutunun tüm bayraklarını görmek için, -h ile çalıştırın:
apidog branch create -h
Kaynakları düzenlemeden önce içe aktarın
Yapay Zeka Dalı boş olduğu için, aracının ilk görevi üzerinde çalışması gereken belirli kaynakları içeri çekmektir. Bu, bir aracının körü körüne çalışmasını önleyen adımdır. Değiştirilmesini istediğiniz uç noktayı, şemayı veya belgeyi içe aktarırsınız ve başka hiçbir şey gelmez.
Aracıyı (veya kendinizi) kimliğe göre tam kaynaklara yönlendirin. Apidog CLI, bu işlemler için çoğul, virgülle ayrılmış kimlik işaretçileri kullanır:
apidog branch pick-to \
--type ai \
--from main \
--to "ai/20260708-from-main-user-register" \
--endpoint-ids 1,2 \
--data-schema-ids 3 \
--project <PROJECT_ID>
Şimdi yapay zeka dalı, main üzerinde var olan uç noktalar 1 ve 2 ile şema 3'ün bir kopyasını içeriyor. Aracı bu kopyalar üzerinde çalışır. Onlara ne yaparsa yapsın, main üzerindeki orijinalleri değişmeden kalır. Eğer aracı burada bir uç noktayı silerse, canlı rotayı değil kopyayı siler. Bu, "aracı API'mizi yok etti" ile "aracı atabileceğimiz bir taslak kopyayı yok etti" arasındaki fark budur.
Eğer bunu bir kodlama aracısı aracılığıyla yönetiyorsanız, aynı komutlar aracı döngüsü içinde çalışır. Apidog CLI, agentHints.nextSteps ile yapılandırılmış JSON döndürür, böylece bir aracı her komutun sonucunu okuyabilir ve sizin çıktıları çevirmenize gerek kalmadan sonraki adımda ne yapacağına karar verebilir. Cursor'daki apidog-cli kılavuzu, bu modelin gerçek bir düzenleyiciye nasıl entegre edildiğini gösterir.
Aracının düzenlemesine izin verin, sonra farkı okuyun
Kaynaklar içe aktarıldıktan sonra, aracının işini yapmasına izin verin. Yapay zeka dalı içinde uç noktaları, şemaları, belgeleri ve test senaryolarını oluşturur, günceller veya siler. Bu yazma işlemlerinin her biri sınırlandırılmıştır.
İşlem tamamlandığında, herhangi bir birleşme olmadan önce incelersiniz. Yapay Zeka Dalı akışında hiçbir şey otomatik değildir; birleştirme bir insan kararıdır. CLI'dan veya Apidog istemcisinden değişiklikleri inceleyin ve farkın gerçekten istediğinizle eşleştiğini doğrulayın. Bu sizin geçidinizdir. Eğer aracı raydan çıktıysa, bunu burada görürsünüz ve düzeltme, üretimi geri almak yerine dalı atmaktır.
Bu incelemeyi isteğe bağlı değil, zorunlu olarak ele alın. Tüm akışın amacı, bir insan aracının çıktısını gerçek hale gelmeden önce görmesidir. İncelemeyi atlamak, izolasyonu bozar.
Değişiklikleri bir birleştirme isteğiyle (merge request) uygulayın
Nasıl birleştireceğiniz, hedef dalın korunup korunmadığına bağlıdır. Korunan bir ana dalın faydası burada ortaya çıkar.
Hedef dal korunmuyorsa, tam olarak taşınacak kaynakları belirterek doğrudan birleştirebilirsiniz:
apidog branch merge \
--type ai \
--from "ai/20260708-from-main-user-register" \
--to main \
--endpoint-ids 1,2 \
--data-schema-ids 3 \
--project <PROJECT_ID>
Eğer main korunuyorsa, ki öyle olmalı, doğrudan birleştirme engellenir. Bunun yerine bir birleştirme isteği (merge request) açar ve değişikliği incelemeden geçirirsiniz:
apidog merge-request create \
--from "ai/20260708-from-main-user-register" \
--to main \
--endpoint-ids 1,2 \
--data-schema-ids 3 \
--reviewer-ids <REVIEWER_USER_IDS> \
--description "AI branch: user register changes" \
--project <PROJECT_ID>
Birleştirme isteği (merge request), aracı tarafından oluşturulan her şey için tercih edilen yoldur. Değişikliği, bir insan katkıcının karşılaşacağı aynı inceleme akışından geçmeye zorlar. Bir ekip arkadaşı onaylar, sonra değişiklik uygulanır. Aracı asla kendi başına main'e yazmaz; yalnızca bir birleştirme isteği aracılığıyla bir insandan çalışmasını kabul etmesini isteyebilir. Birleştirmenin yalnızca listelediğiniz kaynak kimliklerini taşıdığına dikkat edin. Eğer aracı göndermeyi düşünmediğiniz bir şeye dokunduysa, o kimliği birleştirmeden çıkarırsınız ve o geride kalır.
Bu, Git-yerel bir API iş akışının insan katkıcıları nasıl ele aldığını yansıtır: dal oluştur, öner, incele, birleştir. Yapay Zeka Dalı, insan olmayan bir katkıcıya aynı disiplini uygular; bu, doğrudan main'e yazmasını en az istediğiniz kişidir.
Birleştirilmiş ve terk edilmiş dalları temizleyin
Birleştirilmiş veya terk edilmiş yapay zeka dalları, dal listesinin okunabilir kalması için derhal arşivlenmelidir. Bir dal birleştirildiğinde veya ona ihtiyacınız olmadığına karar verdiğinizde, önce arşivleyin, sonra silin:
apidog branch archive "ai/20260708-from-main-user-register" \
--type ai \
--project <PROJECT_ID>
Önerilen ritim, görev başına bir yapay zeka dalıdır. Bir dal, tek bir aracı iş birimine karşılık gelir, incelenir, birleştirilir veya atılır, ardından arşivlenir. Bu, izolasyonu anlamlı kılar; birbiriyle ilgisi olmayan üç düzenleme oturumunun biriktiği bir dalı asla incelemezsiniz.
Dalın etrafındaki güvenli aracı hijyeni
Yapay Zeka Dalı izolasyonu yönetir, ancak bir aracının en başta ulaşabileceği şeyleri sınırlayan bazı alışkanlıklar içinde en iyi şekilde çalışır.
- En az ayrıcalıklı erişim belirteçleri kullanın.
apidog login --with-tokenkomutuna geçirdiğiniz belirteç, aracının ne yapabileceğini sınırlar. Bir otomasyon belirtecine ihtiyaç duyduğu projelere erişim verin ve daha fazlasına değil. Rahat olduğu için bir aracıya kişisel sahibi belirtecinizi vermeyin. Eğer bir belirteç sızarsa veya bir aracı kötü davranırsa, hasarın belirtecin kapsamıyla sınırlı kalmasını istersiniz. - Ana dalınızı (main branch) koruyun. Bu, "birleştirmeden önce inceleme"yi bir öneriden bir kurala dönüştüren tek ayardır.
mainkorunduğunda, doğrudan birleştirme yolu kapanır ve her aracı değişikliğimerge-request createüzerinden geçmek zorunda kalır. Korumak, birleştirme isteğini isteğe bağlı olmaktan çıkarır. - Her seferinde birleştirmeden önce inceleyin. İzolasyon sizi yalnızca bir insan farkı (diff) gerçekten okuduğunda korur. İncelemeyi iş akışına dahil edin, böylece atlanamaz. Bir hafta boyunca güvenilir olan bir aracı, sekizinci günde hala bir komutu yanlış okuyabilir.
- Devredin, sonra doğrulayın. Bu, her şeyi bir araya getiren desendir. Kapsamlı bir görevi aracıya devredersiniz, izole dalında çalışmasına izin verirsiniz, sonra birleştirmeden önce sonucu doğrulayın. İşin çoğunu aracı yapar; kabul sizin sorumluluğunuzdadır. Aynı ayrım, aracılar testleri çalıştırdığında da ortaya çıkar: aracı süiti yürütür, siz test donanımı sonuçlarını ve çıkış kodunu güvenmeden önce kontrol edersiniz. Yapmayı devredin, yargılamayı sizde tutun.
Tüm bunlarla birlikte API spesifikasyonunuzu Git'te versiyonluyorsanız, OpenAPI versiyon kontrolü iş akışı, bir şeyler yanlış göründüğünde karşılaştırabileceğiniz ikinci bir geçmiş katmanı sunar.
Uçtan uca akış sırasıyla
İşte bir aracıya verebileceğiniz veya kendiniz çalıştırabileceğiniz bir dizi olarak tüm süreç:
main'denapidog branch create --type ai. Dal boş vemaindokunulmamış kalır.- Aracının ihtiyaç duyduğu belirli uç noktaları ve şemaları
apidog branch pick-toile alın. Başka hiçbir şey içeri gelmez. - Aracının dal içinde düzenleme yapmasına izin verin. Her yazma işlemi sınırlandırılmıştır.
- CLI'dan veya istemciden farkı inceleyin. Bu insan geçididir.
- Korunan bir
main'e karşıapidog merge-request create. Bir ekip arkadaşı onaylar; aracı asla doğrudan main'e yazmaz. - Birleştirildikten veya terk edildikten sonra
apidog branch archive.
Hiçbir noktada aracının main üzerindeki canlı bir uç noktanın üzerine yazma veya silme yolu yoktur. Yapabileceği en kötü şey, daha sonra birleştirmeyi reddettiğiniz bir taslak kopyada kötü bir değişiklik yapmaktır.
Aracılara anahtarları vermeden çalışma alanı sağlayın
Aracılar tam olarak sormadan hareket ettikleri için faydalıdır. Sınırsız yazma erişimini tehlikeli kılan da budur. Cevap, aracıyı yavaşlatmak değil; hızlı, tereddütsüz yazma işlemlerini güvenli bir yere indirmektir. İzole bir yapay zeka dalı, korunan bir ana dal, en az ayrıcalıklı belirteçler ve zorunlu bir inceleme, "aracı API'mizi yok etti" ifadesini, göz attığınız ve reddettiğiniz bir farka dönüştürür.
Apidog bunu yerleşik olarak sunar, böylece ayrı araçlardan bir araya getirmeniz gerekmez. Apidog CLI'yı edinin, bir yapay zeka dalı oluşturun ve aracılar gerçek şey yerine bir kopyaya karşı düzenleme yapsın. Yapay Zeka Dalı akışını denemek için Apidog'u indirin ve bir üretim iş akışına bağlamadan önce tam komut referansı için Yapay Zeka Dalı belgelerini okuyun.