Tobias Hoffmann

Posted on Jul 6 • Originally published at apidog.com

Yapay Zeka Alanı: Ajan Destekli Güvenli Proje Değişiklikleri

Bu seri, Apidog'un API testi ve API yaşam döngüsü yönetimi için geliştirdiği komut satırı aracı olan Apidog CLI'nın nasıl tasarlandığını ve neden bu yaklaşıma ihtiyaç duyulduğunu anlatır. Sırayla okuyabilir veya doğrudan ilgilendiğiniz bölüme geçebilirsiniz:

Apidog'u bugün deneyin

	Başlık	Odak Noktası
1	126 MCP Aracı İnşa Ettik. Ama Ajan İçin En İyi Çözüm Bu Değil	Sorun keşfi
2	Neden Yepyeni Apidog CLI Geliştirdik?	Mimari geliştirme
3	Altın Kural: CLI Gerçekleri Üretir, Model Gerçekler Üzerinde Hareket Eder	Çekirdek felsefe
4	`agentHints`: CLI'lara Ajanlarla Konuşmayı Öğretmek	Yapılandırılmış çıktı
5	YETENEK: Operasyonel Deneyimi Kod Olarak Göndermek	Operasyonel deneyim
6	Sayılar Yalan Söylemez: %30 Daha Az Araç Çağrısı, %25 Daha Az Token	Nicel sonuçlar
7	PRD'den Test Döngüsüne: Apidog CLI ile Eksiksiz Bir Ajan İş Akışı	Pratik eğitim
8	CI/CD Uyumluluğunun Ajan Araçları İçin Neden Tartışılamaz Olduğu	DevOps perspektifi
9	Yapay Zeka Dalı: Yapay Zeka Ajanları ile Daha Güvenli Proje Değişiklikleri	Güvenlik katmanı
10	Önce Belirtim Dündü. Önce Yetenek'e Hoş Geldiniz.	Vizyon ve gelecek

Bir Ajan proje kaynaklarını değiştirdiğinde iki şey kritik hale gelir: izolasyon ve inceleme. AI Branch, yapay zeka tarafından yapılan değişiklikleri hedef dala doğrudan yazmak yerine ayrı bir düzenleme dalında tutar. Değişiklikler ancak insan onayından sonra hedef dala girer.

Güvenlik Problemi

Yapay zeka ajanları API geliştirme ve test süreçlerine dahil olduğunda CLI üzerinden proje kaynaklarını oluşturabilir, güncelleyebilir veya silebilir.

Bu, güçlü ama riskli bir yetkidir.

Risk	Ne Olabilir
Tahmin edilemeyen çıktı	Ajan beklenmedik içerik yazar
Alan hataları	Yanlış iddialar veya eksik parametreler oluşur
Kapsam kayması	Ajan görev dışındaki kaynakları değiştirir
İnceleme izi yok	Değişiklikler doğrudan ana dalda görünür
Ekip aksaklığı	Paylaşılan işbirliği dalı aniden değişir

Temel soru şudur:

Ajanların gerçek proje kaynakları üzerinde çalışmasına izin verirken ana dalı nasıl korursunuz?

AI Branch Nedir?

AI Branch, harici yapay zeka ve CLI operasyonları için tasarlanmış özel bir Sprint Dalı türüdür.

Apidog CLI'dan başlatılan düzenleme operasyonları varsayılan olarak yapay zeka veya yapay zeka ajanı tarafından başlatılmış kabul edilir. AI Branch bu işlemleri izole bir dalda tutar.

Ajan CLI aracılığıyla değişiklik yapar
        ↓
Değişiklikler AI Branch'ta saklanır
        ↓
Kullanıcı farkları inceler
        ↓
Kullanıcı kaynak kapsamını onaylar
        ↓
Değişiklikler hedef dala birleştirilir

Sonuç: Onay verilene kadar ana dal dokunulmadan kalır.

AI Branch Ne Zaman Gerekli?

Apidog CLI; uç noktalar, şemalar, test senaryoları, test paketleri ve diğer API kaynakları üzerinde yazma işlemleri yapabilir. Yapay zeka bu işlemleri tetiklediğinde güvenli varsayılan davranış, değişiklikleri izole etmektir.

AI Branch Olmadan	AI Branch ile
Ajan doğrudan ana dala yazar	Ajan izole bir dala yazar
Değişiklikler hemen görünür	Değişiklikler incelemeyi bekler
Güvenlik ağı yoktur	İnsan onayı gerekir
İstenmeyen değişiklik riski yüksektir	Kapsam belirli kaynaklarla sınırlandırılır

AI Branch özellikle şu durumlarda kullanışlıdır:

Senaryo	AI Branch Nasıl Yardımcı Olur
Koddan API taslakları oluşturma	Ajan uç noktaları AI Branch'ta oluşturur; ekip birleştirmeden önce inceler
API kaynaklarını toplu düzenleme	Klasörler, açıklamalar ve modeller işbirliği dalı etkilenmeden güncellenir
Otomatik test taslakları üretme	Test senaryoları inceleme için izole dalda oluşturulur
API dokümantasyon boşluklarını doldurma	Eksik alanlar ana dala yazılmadan önce kontrol edilir
CI/CD'de toplu yazma	Otomasyon AI Branch'a yazar, kullanıcı birleştirmesini bekler

Temel Özellikler

Özellik	Açıklama
İzole düzenleme	Değişiklikler AI Branch'ta saklanır; ana veya kaynak dal etkilenmez
Net kaynak	Müşteride oluşturulamaz; CLI/MCP üzerinden gelir ve kaynak dal bilgisi korunur
İnsan onayı	Değişiklikler birleştirmeden önce onaylanmalıdır
Miktar sınırı yok	Farklı görevler için gerektiği kadar AI Branch oluşturulabilir
Otomatik arşivleme	Farkı olmayan dallar her 24 saatte bir arşivlenir

AI Branch üzerinde tipik operasyonlar:

Operasyon	Nerede Gerçekleşir
Yapay zeka uç nokta oluşturur	AI Branch'ta
Yapay zeka test senaryosu günceller	AI Branch'ta
Ekip değişiklikleri inceler	Apidog istemcisinde veya CLI önizlemesinde
Kullanıcı birleştirmeyi onaylar	Kullanıcı eylemiyle
Değişiklikler hedef dala girer	Onaydan sonra

Kullanıcıların istemci içindeki normal düzenlemeleri yine proje üyesi izinlerini ve dal koruma kurallarını takip eder.

Uygulanabilir AI Branch İş Akışı

Aşağıdaki akış, yapay zeka destekli bir API değişikliğini güvenli şekilde yönetmek için kullanılabilir:

1. AI Branch oluştur
2. Gerekirse mevcut kaynakları AI Branch'a içe aktar
3. Ajan kaynakları AI Branch üzerinde oluşturur veya günceller
4. Yazmadan önce JSON şeması doğrulanır
5. Değişiklikler önizlenir
6. Kullanıcı kapsamı inceler
7. Değişiklikler doğrudan birleştirilir veya merge request açılır
8. Birleştirilmiş kaynaklar üzerinde test çalıştırılır

1. AI Branch Oluşturma

Yeni bir AI Branch oluşturmak için branch create --type ai kullanın:

apidog branch create \
  --project 123456 \
  --type ai \
  --name "ai/20260312-from-main-userRegister" \
  --from main

Adlandırma için pratik bir format:

ai/YYYYAAGG-kaynakDal-özellikVeyaModül

Örnekler:

ai/20260312-from-main-userRegister
ai/20260312-from-dev-paymentTests
ai/20260312-from-main-orderDocs

Sık kullanılan dal komutları:

Komut	Amaç
`branch create --type ai`	AI Branch oluşturur
`branch list --type ai`	Projedeki AI Branch'ları listeler
`branch list --type all`	Tüm dal türlerini listeler
`branch get --type ai`	AI Branch ayrıntılarını görüntüler

2. AI Branch'ta Kaynak Düzenleme

CLI ile proje kaynağı yazarken hedef AI Branch'ı --branch parametresiyle belirtin.

Kaynak	Komut Örneği
HTTP uç noktası	`apidog endpoint create --project <id> --branch <aiBranchName> --file ./endpoint.json`
Veri modeli	`apidog schema update <schemaId> --project <id> --branch <aiBranchName> --file ./schema.json`
Test senaryosu	`apidog test-scenario update <scenarioId> --project <id> --branch <aiBranchName> --file ./scenario.json`
Test paketi	`apidog test-suite create --project <id> --branch <aiBranchName> --file ./suite.json`

Önerilen yazma akışı:

# 1. İlgili CLI şemasını al
apidog cli-schema get endpoint-create

# 2. Yazmadan önce dosyayı doğrula
apidog cli-schema validate endpoint-create --file ./endpoint.json

# 3. Ana dala değil, AI Branch'a yaz
apidog endpoint create \
  --project 123456 \
  --branch "ai/20260312-from-main-userRegister" \
  --file ./endpoint.json

Bu akış iki şeyi garanti etmeye yardımcı olur:

JSON yapısı yazmadan önce doğrulanır.
Ajanın ürettiği değişiklik doğrudan ana dala gitmez.

3. Mevcut Kaynakları AI Branch'a İçe Aktarma

Mevcut bir uç noktayı, modeli veya test kaynağını değiştirecekseniz önce kaynak daldan AI Branch'a taşıyın.

Örnek:

apidog branch pick-to \
  --project 123456 \
  --from main \
  --to "ai/20260312-from-main-userRegister" \
  --endpoint-ids 1001,1002

Bu adım, ajanın doğru temel sürüm üzerinde çalışmasını sağlar. Özellikle mevcut kaynakları güncelleyen işlerde pick-to kullanmak kapsam karışıklığını azaltır.

4. Birleştirmeden Önce Değişiklikleri Önizleme

AI Branch'taki değişiklikleri hedef dala yazmadan önce inceleyin:

apidog merge-request preview \
  --project 123456 \
  --from "ai/20260312-from-main-userRegister" \
  --to main

Alternatif olarak Apidog istemcisinde tam fark görünümünü kullanabilirsiniz.

Komut	Amaç
`merge-request preview`	Aday değişiklikleri tarar
`branch get --type ai`	AI Branch bilgilerini görüntüler

İnceleme sırasında özellikle şunlara bakın:

Ajan yalnızca beklenen kaynakları mı değiştirdi?
Gerekli dizinler, modeller, yanıt bileşenleri ve testler kapsamda mı?
Üretilen açıklamalar ve alan adları doğru mu?
Test senaryoları gerçek API davranışıyla uyumlu mu?

5. AI Branch'ı Birleştirme

İncelemeden sonra iki yol vardır:

Korunmasız dala doğrudan birleştirme
Korumalı dal için birleştirme isteği oluşturma

Doğrudan Birleştirme

Korunmasız bir hedef dala doğrudan birleştirme:

apidog branch merge \
  --project 123456 \
  --from "ai/20260312-from-main-userRegister" \
  --to main \
  --endpoint-ids 1001,1002

Birleştirme İsteği Oluşturma

Korumalı dal için merge request oluşturma:

apidog merge-request create \
  --project 123456 \
  --from "ai/20260312-from-main-userRegister" \
  --to main \
  --reviewer-ids 20001,20002 \
  --endpoint-ids 1001,1002

İlgili komutlar:

Komut	Amaç
`branch merge`	Korunmasız dala doğrudan birleştirme yapar
`merge-request create`	İnceleme için birleştirme isteği oluşturur
`merge-request approve`	Birleştirme isteğini onaylar
`merge-request reject`	Birleştirme isteğini reddeder

Önemli: Birleştirme komutları yalnızca açıkça verilen kaynak listesini işler. Birleştirmeden önce bağımlı kaynakları da onaylayın: dizinler, modeller, yanıt bileşenleri, testler vb.

6. AI Branch'ı Arşivleme veya Silme

Değişiklikler birleştirildikten veya dal artık gerekmedikten sonra dal listesini temiz tutun.

# Arşivle
apidog branch archive "ai/20260312-from-main-userRegister" \
  --project 123456 \
  --type ai

# Sil
apidog branch delete "ai/20260312-from-main-userRegister" \
  --project 123456 \
  --type ai

Genel öneri:

İş tamamlandıysa arşivleyin.
Arşiv sonrası artık ihtiyaç yoksa silin.
Görev başına ayrı AI Branch kullandığınızda temizlik daha kolay olur.

Harici Yapay Zeka Düzenleme İzinleri

Varsayılan yaklaşım, CLI'ın AI Branch'a yazmasıdır. Böylece yapay zeka tarafından oluşturulan değişiklikler kullanıcı onayına kadar izole kalır.

Ana dal veya diğer dal türlerine doğrudan düzenlemeyi etkinleştirmek için:

Proje Ayarları
→ Özellik Ayarları
→ Yapay Zeka Özellik Ayarları
→ Harici Yapay Zeka Düzenleme İzinleri

İzin	Neye İzin Verir
Ana dal doğrudan düzenleme	CLI doğrudan ana dala yazar ve AI Branch'ı atlar
Standart sprint dalı doğrudan düzenleme	CLI doğrudan sprint dallarına yazar
Genel dal doğrudan düzenleme	CLI doğrudan genel dallara yazar
AI Branch doğrudan düzenleme	CLI AI Branch'lara yazar

Tavsiye: AI Branch izolasyonunu etkin tutun. Doğrudan düzenlemeyi yalnızca otomasyon iş akışınız açıkça gerektiriyorsa açın.

En İyi Uygulamalar

Uygulama	Neden
Görev başına bir AI Branch kullanın	Kapsamı net tutar: kullanıcı kayıt API'si, ödeme testleri, sipariş dokümanı vb.
Mevcut kaynakları düzenlemeden önce içe aktarın	`pick-to` kaynak karışıklığını önler
Yazmadan önce doğrulayın	`cli-schema validate` hataları erken yakalar
Birleştirmeden önce önizleyin	`merge-request preview` veya istemci fark görünümü beklenmeyen değişiklikleri gösterir
Birleştirme kapsamını açık belirtin	Uç noktaları, modelleri, dizinleri ve testleri birlikte değerlendirin
İnsan incelemesini koruyun	API tanımları ve test betikleri birleştirmeden önce gözden geçirilmelidir
İş bitince arşivleyin	Dal listesini temiz ve izlenebilir tutar

CLI + SKILL İş Akışında AI Branch

AI Branch, CLI + SKILL yaklaşımıyla birlikte güvenli bir yazma hattı oluşturur.

Aşama	CLI + SKILL + AI Branch
Oku	Herhangi bir daldan `endpoint get`
Oluştur	Ajan JSON üretir
Doğrula	Yerel olarak `cli-schema validate`
Yaz	AI Branch'a `endpoint create --branch <aiBranchName>`
İncele	`merge-request preview`
Birleştir	Kullanıcı onaylar, ardından `branch merge` çalışır
Doğrula	Birleştirilmiş kaynaklar üzerinde `apidog run`

Bu modelde her yazma işlemi şu yoldan geçer:

AI Branch → İnsan incelemesi → Birleştirme → Test

Güvenlik Katmanları

AI Branch tek başına değil, diğer güvenlik katmanlarıyla birlikte kullanıldığında daha etkili olur.

Katman	Koruma
`cli-schema validate`	Yazmadan önce yapısal hataları yakalar
`agentHints`	Ajanı güvenli sonraki adımlara yönlendirir
AI Branch	Değişiklikleri ana daldan izole eder
İnsan incelemesi	İçeriği birleştirmeden önce doğrular
Birleştirme kapsamı	Hangi kaynakların hedef dala gireceğini kullanıcı seçer

Bu katmanlar birlikte, ajan odaklı API değişiklikleri için daha güvenli ve incelenebilir bir döngü oluşturur.

Uçtan Uca Örnek

Aşağıdaki örnek, mevcut iki uç noktayı AI Branch'a alıp değişiklikleri inceleme ve birleştirme akışını gösterir.

# 1. AI Branch oluştur
apidog branch create \
  --project 123456 \
  --type ai \
  --name "ai/20260312-from-main-userRegister" \
  --from main

# 2. Mevcut uç noktaları AI Branch'a içe aktar
apidog branch pick-to \
  --project 123456 \
  --from main \
  --to "ai/20260312-from-main-userRegister" \
  --endpoint-ids 1001,1002

# 3. Ajanın ürettiği endpoint JSON'unu doğrula
apidog cli-schema validate endpoint-create \
  --file ./endpoint.json

# 4. AI Branch'a yaz
apidog endpoint create \
  --project 123456 \
  --branch "ai/20260312-from-main-userRegister" \
  --file ./endpoint.json

# 5. Farkları önizle
apidog merge-request preview \
  --project 123456 \
  --from "ai/20260312-from-main-userRegister" \
  --to main

# 6. İnceleme sonrası birleştir
apidog branch merge \
  --project 123456 \
  --from "ai/20260312-from-main-userRegister" \
  --to main \
  --endpoint-ids 1001,1002

Temel Çıkarımlar

AI Branch, yapay zeka ve CLI operasyonları için izole düzenleme sağlar.
Değişiklikler insan onayı olmadan ana dala girmez.
branch create --type ai ile AI Branch oluşturun.
Yazma komutlarında --branch parametresiyle AI Branch'ı hedefleyin.
Mevcut kaynakları düzenlemeden önce branch pick-to ile içe aktarın.
cli-schema validate ile yazmadan önce doğrulama yapın.
merge-request preview ile farkları inceleyin.
Korunmasız dalda branch merge, korumalı dalda merge-request create kullanın.
Doğrudan düzenleme izinleri AI Branch'ı atlayabilir; dikkatli kullanın.
En iyi pratik: görev başına bir AI Branch, yazmadan önce doğrulama, birleştirmeden önce insan incelemesi.

Sıradaki Ne?

AI Branch ile güvenlik katmanı tamamlandığında seri şu parçaları bir araya getirir:

Araç bağlantısı için MCP
İş akışı yürütme için CLI + SKILL
Doğrulama ve ölçüm sonuçları
Pratik ajan iş akışları
CI/CD uyumluluğu
Güvenli değişiklik yönetimi için AI Branch

Bölüm 10'da, Önce Belirtim Dündü. Önce Yetenek'e Hoş Geldiniz. başlığıyla API geliştirmenin yapay zeka ajanlarıyla nasıl değiştiğini ve ekiplerin bundan sonra hangi yaklaşıma hazırlanması gerektiğini ele alacağız.

Tek bir çalışma alanında API'ları tasarlamak, sahte verilerini oluşturmak, test etmek ve belgelendirmek için Apidog'u kullanabilirsiniz. Komut satırı API testi, CI otomasyonu ve yapay zeka ajan iş akışları için Apidog CLI hakkında daha fazla bilgi edinin.

DEV Community