Memberikan agen AI akses tulis ke proyek API Anda dapat menyebabkan kerusakan nyata. Bukan secara jahat; agen hanya melakukan apa yang disiratkan oleh perintah. Meminta satu agen untuk "membersihkan endpoint pengguna" mungkin akan menghapus rute aktif yang masih Anda butuhkan. Memintanya untuk "memperbarui skema" dapat menimpa model data yang direferensikan oleh tiga endpoint lainnya. Agen tidak memiliki pemahaman tentang apa yang sedang dikirim ke produksi. Ia hanya melihat sumber daya yang diizinkan untuk disentuh, dan ia menyentuhnya.
Ini adalah kelas risiko baru. Ketika seorang manusia melakukan pengeditan tersebut, mereka akan ragu sebelum menghapus sebuah endpoint. Agen yang berjalan dalam loop dari terminal Anda tidak akan ragu. Ia menjalankan perintah, mendapatkan respons sukses, dan melanjutkan. Jika perintah tersebut mengenai cabang utama (main branch) Anda, perubahan sudah aktif dalam sumber desain Anda.
Solusinya bukan mengunci agen. Solusinya adalah memberi mereka sandbox yang tidak bisa mereka lepaskan. AI Branch Apidog melakukan persis seperti itu: setiap pengeditan yang digerakkan agen masuk ke cabang yang terisolasi, cabang sumber Anda tetap tidak tersentuh, dan tidak ada yang mencapai cabang utama sampai manusia meninjau perbedaan (diff) dan menggabungkannya. Postingan ini membahas alur CLI secara menyeluruh, kemudian mencakup kebersihan agen yang aman secara umum yang harus ada di sekitarnya. Untuk alasan desain di balik fitur ini, lihat tulisan yang lebih mendalam di AI Branch dan perubahan yang lebih aman yang digerakkan agen; bagian ini adalah buku panduan praktis.
Mengapa akses tulis agen berbahaya secara default
Sebagian besar alat memberikan agen satu tingkat akses: proyek. Jika agen dapat membuat endpoint, ia juga dapat menghapusnya. Jika ia dapat memperbarui skema, ia juga dapat menggantinya dengan sesuatu yang tidak kompatibel. Tidak ada jeda antara "agen mengusulkan perubahan" dan "perubahan ada di sumber kebenaran Anda."
Tiga mode kegagalan muncul berulang kali:
- Menimpa (Overwrite). Agen membuat ulang skema dari pemahaman parsial tentang API Anda dan menghapus kolom yang dibutuhkan oleh endpoint lain.
- Menghapus (Delete). Agen "mengonsolidasikan" endpoint dan menghapus rute yang masih dipanggil oleh klien aktif.
- Penyimpangan diam-diam (Silent drift). Agen membuat puluhan pengeditan kecil di sepanjang sesi. Tidak ada satu perubahan pun yang terlihat salah, tetapi jumlahnya secara diam-diam menyimpang dari apa yang Anda kirim.
Tak satu pun dari ini adalah hal yang aneh. Itu adalah keluaran normal dari agen yang melakukan pekerjaannya pada cabang yang salah. Tujuannya adalah untuk membuat cabang yang salah tidak mungkin dijangkau.
Perbaikan inti: cabang AI yang terisolasi
AI Branch adalah jenis cabang sprint khusus yang dibuat untuk operasi AI eksternal dan CLI. Ketika Anda membuatnya, agen mengedit di dalamnya dan perubahannya tetap di sana. Cabang sumber Anda dan cabang utama Anda tidak terpengaruh sampai Anda memutuskan untuk menggabungkan.
Anda membuatnya dari CLI. Pertama, instal dan autentikasi Apidog CLI:
npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
Kemudian buat cabang AI. Dokumen merekomendasikan penamaan dengan tanggal, cabang sumber, dan tujuan agar mudah dikenali nanti:
apidog branch create --type ai \
--name "ai/20260708-from-main-user-register" \
--from main \
--project <PROJECT_ID>
Dua hal penting di sini. Cabang dibuat dari `main`, tetapi pembuatannya tidak menyentuh `main`. Dan cabang dimulai dalam keadaan kosong. AI Branch tidak secara otomatis menyalin seluruh proyek Anda ke dalamnya; ia hanya menampung sumber daya yang secara eksplisit dibawa oleh agen. Itu adalah properti keamanan yang disengaja. Agen hanya dapat mengedit apa yang telah diimpornya, sehingga radius ledakan adalah apa pun yang Anda lingkupkan, bukan seluruh proyek.
Untuk melihat semua bendera (flags) untuk setiap perintah cabang, jalankan dengan `-h`:
apidog branch create -h
Impor sumber daya sebelum mengeditnya
Karena AI Branch kosong, tugas pertama agen adalah menarik sumber daya spesifik yang dibutuhkan untuk dikerjakan. Ini adalah langkah yang mencegah agen beroperasi secara buta. Anda mengimpor endpoint, skema, atau dokumen yang ingin Anda ubah, dan tidak ada yang lain ikut serta.
Arahkan agen (atau diri Anda sendiri) ke sumber daya yang tepat berdasarkan ID. Apidog CLI menggunakan bendera ID jamak, dipisahkan koma, untuk operasi ini:
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>
Sekarang cabang AI berisi salinan endpoint `1` dan `2` serta skema `3` seperti yang ada di `main`. Agen bekerja pada salinan ini. Apa pun yang dilakukannya terhadap salinan tersebut, yang asli di `main` tidak berubah. Jika agen menghapus endpoint di sini, ia menghapus salinannya, bukan rute aktif. Inilah perbedaan antara "agen menghancurkan API kita" dan "agen menghancurkan salinan coretan yang bisa kita buang."
Jika Anda menggerakkan ini melalui agen pengkodean, perintah yang sama berjalan di dalam loop agen. Apidog CLI mengembalikan JSON terstruktur dengan `agentHints.nextSteps`, sehingga agen dapat membaca hasil setiap perintah dan memutuskan apa yang harus dilakukan selanjutnya tanpa Anda menerjemahkan keluarannya. Panduan apidog-cli di Cursor menunjukkan pola ini terhubung ke editor nyata.
Biarkan agen mengedit, lalu baca perbedaannya
Setelah sumber daya diimpor, biarkan agen melakukan pekerjaannya. Ia membuat, memperbarui, atau menghapus endpoint, skema, dokumen, dan skenario pengujian di dalam cabang AI. Setiap penulisan tersebut terkandung.
Setelah selesai, Anda meninjau sebelum ada yang digabungkan. Tidak ada dalam alur AI Branch yang otomatis; penggabungan adalah keputusan manusia. Periksa perubahan dari CLI atau klien Apidog dan konfirmasikan bahwa perbedaan sesuai dengan apa yang sebenarnya Anda inginkan. Ini adalah gerbang Anda. Jika agen menyimpang, Anda melihatnya di sini, dan perbaikannya adalah membuang cabang, bukan mengembalikan produksi.
Perlakukan tinjauan ini sebagai wajib, bukan opsional. Inti dari seluruh alur adalah bahwa manusia melihat output agen sebelum menjadi nyata. Melewatkan tinjauan menggagalkan isolasi.
Selesaikan perubahan dengan permintaan gabungan
Cara Anda menggabungkan tergantung pada apakah cabang target dilindungi. Di sinilah cabang utama yang dilindungi membuahkan hasil.
Jika cabang target tidak dilindungi, Anda dapat menggabungkan secara langsung, menamai sumber daya yang tepat untuk dibawa:
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>
Jika `main` dilindungi, dan memang seharusnya begitu, penggabungan langsung diblokir. Sebagai gantinya, Anda membuka permintaan gabungan dan mengarahkan perubahan melalui tinjauan:
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>
Permintaan gabungan adalah jalur yang disukai untuk apa pun yang dihasilkan agen. Ini memaksa perubahan melalui alur tinjauan yang sama yang akan dihadapi oleh kontributor manusia. Seorang rekan tim menyetujuinya, lalu perubahan diterapkan. Agen tidak pernah menulis ke `main` dengan sendirinya; ia hanya dapat meminta, melalui permintaan gabungan, agar manusia menerima pekerjaannya. Perhatikan bahwa penggabungan hanya membawa ID sumber daya yang Anda cantumkan. Jika agen menyentuh sesuatu yang tidak ingin Anda kirimkan, Anda membiarkan ID itu keluar dari penggabungan dan itu tetap tertinggal.
Ini mencerminkan bagaimana alur kerja API Git-native menangani kontributor manusia: cabang, usulkan, tinjau, gabungkan. AI Branch menerapkan disiplin yang sama pada kontributor non-manusia, yang paling tidak Anda inginkan menulis langsung ke main.
Bersihkan cabang yang digabungkan dan ditinggalkan
Cabang AI yang digabungkan atau ditinggalkan harus segera diarsipkan agar daftar cabang tetap mudah dibaca. Setelah cabang digabungkan atau Anda memutuskan tidak lagi membutuhkannya, arsipkan terlebih dahulu, lalu hapus:
apidog branch archive "ai/20260708-from-main-user-register" \
--type ai \
--project <PROJECT_ID>
Ritme yang direkomendasikan adalah satu cabang AI per tugas. Sebuah cabang memetakan ke satu unit pekerjaan agen, ditinjau, digabungkan atau dibuang, lalu diarsipkan. Itu menjaga isolasi tetap berarti; Anda tidak pernah meninjau cabang yang mengumpulkan tiga sesi pengeditan yang tidak terkait.
Kebersihan agen yang aman di sekitar cabang
AI Branch menangani isolasi, tetapi berfungsi paling baik dalam beberapa kebiasaan yang membatasi apa yang dapat dijangkau agen sejak awal.
- Gunakan token akses dengan hak istimewa paling rendah. Token yang Anda berikan ke
apidog login --with-tokenmenentukan cakupan apa yang dapat dilakukan agen. Berikan token otomatisasi akses ke proyek yang dibutuhkan dan tidak lebih. Jangan berikan agen token pemilik pribadi Anda karena itu nyaman. Jika token bocor atau agen berperilaku buruk, Anda ingin kerusakan dibatasi oleh cakupan token. - Lindungi cabang utama Anda. Ini adalah satu-satunya pengaturan yang mengubah "tinjau sebelum gabung" dari saran menjadi aturan. Dengan
mainyang dilindungi, jalur gabung langsung ditutup dan setiap perubahan agen harus melaluimerge-request create. Perlindungan inilah yang membuat permintaan gabung tidak dapat diabaikan. - Tinjau sebelum digabungkan, setiap saat. Isolasi hanya melindungi Anda jika manusia benar-benar membaca perbedaannya. Bangun tinjauan ke dalam alur kerja agar tidak dapat dilewati. Agen yang telah Andal selama seminggu masih bisa salah membaca perintah pada hari kedelapan.
- Delegasikan, lalu verifikasi. Ini adalah pola yang menyatukan semuanya. Anda mendelegasikan tugas yang terlingkup kepada agen, membiarkannya berjalan di cabang yang terisolasi, lalu memverifikasi hasilnya sebelum digabungkan. Agen melakukan pekerjaan; Anda memiliki penerimaannya. Pemisahan yang sama muncul ketika agen menjalankan pengujian: agen menjalankan suite, Anda memeriksa hasil test harness dan kode keluar sebelum mempercayainya. Delegasikan pekerjaan, pertahankan penilaian.
Jika Anda membuat versi spesifikasi API Anda di Git di samping semua ini, alur kerja kontrol versi OpenAPI memberi Anda lapisan riwayat kedua untuk dibandingkan ketika ada sesuatu yang terlihat tidak beres.
Alur ujung-ke-ujung, secara berurutan
Berikut adalah keseluruhan alur sebagai urutan yang dapat Anda berikan kepada agen atau jalankan sendiri:
apidog branch create --type aidarimain. Cabang kosong danmaintidak tersentuh.apidog branch pick-toendpoint dan skema spesifik yang dibutuhkan agen. Tidak ada yang lain yang masuk.- Biarkan agen mengedit di dalam cabang. Setiap penulisan terkandung.
- Tinjau perbedaan dari CLI atau klien. Ini adalah gerbang manusia.
apidog merge-request createterhadapmainyang dilindungi. Seorang rekan tim menyetujui; agen tidak pernah menulis langsung ke main.apidog branch archivesetelah digabungkan atau ditinggalkan.
Pada titik mana pun, agen tidak memiliki jalur untuk menimpa atau menghapus endpoint aktif di `main`. Hal terburuk yang dapat dilakukannya adalah membuat perubahan yang buruk pada salinan awal yang kemudian Anda tolak untuk digabungkan.
Berikan ruang bagi agen untuk bekerja tanpa memberi mereka kuncinya
Agen berguna justru karena mereka bertindak tanpa bertanya. Itu juga yang membuat akses tulis tanpa batas berbahaya. Jawabannya bukan untuk memperlambat agen; melainkan untuk membuat penulisannya yang cepat dan tanpa ragu mendarat di tempat yang aman. Cabang AI yang terisolasi, main yang dilindungi, token hak istimewa paling rendah, dan tinjauan wajib mengubah "agen menghancurkan API kami" menjadi perbedaan yang Anda lihat sekilas dan tolak.
Apidog membangun ini agar Anda tidak perlu merangkainya dari alat terpisah. Dapatkan Apidog CLI, buat cabang AI, dan biarkan agen Anda mengedit salinan daripada objek aslinya. Unduh Apidog untuk mencoba alur AI Branch, dan baca dokumentasi AI Branch untuk referensi perintah lengkap sebelum Anda menghubungkannya ke alur kerja produksi.