หากคุณให้สิทธิ์การเขียน (write access) แก่ตัวแทน AI ในโปรเจกต์ API ของคุณ มันสามารถสร้างความเสียหายที่แท้จริงได้ ไม่ใช่โดยประสงค์ร้าย แต่ตัวแทน AI เพียงแค่ทำตามที่คำสั่งแนะนำ หากคุณขอให้ "ทำความสะอาด endpoint ของผู้ใช้" มันอาจลบเส้นทาง (route) ที่ใช้งานจริงที่คุณยังคงต้องพึ่งพาอยู่ หากคุณขอให้ "อัปเดต schema" มันอาจเขียนทับโมเดลข้อมูลที่ endpoint อื่นอีกสามจุดอ้างอิงอยู่ ตัวแทน AI ไม่มีแนวคิดว่าอะไรกำลังถูกใช้งานจริงใน production มันเห็นเฉพาะทรัพยากรที่ได้รับอนุญาตให้แตะต้อง และมันก็จะแตะต้องมัน
นี่คือความเสี่ยงประเภทใหม่ เมื่อมนุษย์ทำการแก้ไขเหล่านั้น พวกเขาจะลังเลก่อนที่จะลบ endpoint แต่ตัวแทน AI ที่ทำงานวนลูปจากเทอร์มินัลของคุณจะไม่ลังเล มันจะรันคำสั่ง ได้รับการตอบสนองที่สำเร็จ และดำเนินการต่อไป หากคำสั่งนั้นกระทบกับ main branch ของคุณ การเปลี่ยนแปลงก็จะถูกใช้งานจริงในแหล่งออกแบบของคุณแล้ว
วิธีแก้ปัญหาไม่ใช่การปิดกั้นตัวแทน AI แต่เป็นการจัดหา sandbox ที่พวกมันไม่สามารถหลุดรอดไปได้ AI Branch ของ Apidog ทำเช่นนั้นอย่างแม่นยำ: การแก้ไขที่ขับเคลื่อนโดยตัวแทน AI ทุกรายการจะไปอยู่บน branch ที่แยกออกมา ซึ่ง source branch ของคุณจะไม่ถูกแตะต้อง และไม่มีสิ่งใดจะไปถึง main branch จนกว่ามนุษย์จะตรวจสอบความแตกต่าง (diff) และรวม (merge) มัน โพสต์นี้จะแนะนำขั้นตอนการทำงานของ CLI แบบครบวงจร จากนั้นจะกล่าวถึงสุขอนามัยทั่วไปสำหรับตัวแทน AI ที่ปลอดภัยซึ่งควรนำมาใช้ร่วมกัน สำหรับเหตุผลเบื้องหลังการออกแบบคุณสมบัตินี้ โปรดดูบทความเชิงลึกเกี่ยวกับ AI Branch และการเปลี่ยนแปลงที่ขับเคลื่อนด้วยตัวแทน AI ที่ปลอดภัยยิ่งขึ้น; บทความนี้เป็นคู่มือการใช้งานจริง
เหตุใดการให้สิทธิ์การเขียนแก่ตัวแทน AI จึงเป็นอันตรายโดยค่าเริ่มต้น
เครื่องมือส่วนใหญ่ให้สิทธิ์การเข้าถึงแก่ตัวแทน AI เพียงระดับเดียว: คือทั้งโปรเจกต์ หากตัวแทน AI สามารถสร้าง endpoint ได้ มันก็สามารถลบ endpoint ได้เช่นกัน หากมันสามารถอัปเดต schema ได้ มันก็สามารถแทนที่ด้วยสิ่งที่ไม่เข้ากันได้ ไม่มีช่องว่างระหว่าง "ตัวแทน AI เสนอการเปลี่ยนแปลง" กับ "การเปลี่ยนแปลงอยู่ในแหล่งความจริงของคุณ"
มีรูปแบบความล้มเหลวสามประการที่เกิดขึ้นซ้ำๆ:
- การเขียนทับ (Overwrite) ตัวแทน AI สร้าง schema ใหม่จากการทำความเข้าใจ API ของคุณเพียงบางส่วน และลบฟิลด์ที่ endpoint อื่นๆ ต้องการออกไป
- การลบ (Delete) ตัวแทน AI "รวม" endpoint และลบเส้นทาง (route) ที่ยังคงถูกเรียกใช้งานโดยไคลเอนต์ที่ใช้งานจริง
- การเบี่ยงเบนอย่างเงียบๆ (Silent drift) ตัวแทน AI ทำการแก้ไขเล็กๆ น้อยๆ จำนวนมากตลอดเซสชัน การเปลี่ยนแปลงแต่ละรายการอาจดูไม่ผิดปกติ แต่ผลรวมโดยรวมกลับเบี่ยงเบนไปจากสิ่งที่คุณนำไปใช้งานจริงอย่างเงียบๆ
สิ่งเหล่านี้ไม่ใช่เรื่องแปลก เป็นผลลัพธ์ปกติที่เกิดจากตัวแทน AI ทำงานใน branch ที่ผิดพลาด เป้าหมายคือการทำให้ branch ที่ผิดพลาดไม่สามารถเข้าถึงได้
วิธีแก้ปัญหาหลัก: AI branch ที่แยกออกมา
AI Branch คือ sprint branch ชนิดพิเศษที่สร้างขึ้นสำหรับการทำงานของ AI ภายนอกและการดำเนินการ CLI เมื่อคุณสร้าง branch นี้ ตัวแทน AI จะแก้ไขภายในนั้น และการเปลี่ยนแปลงจะยังคงอยู่ตรงนั้น source branch และ main branch ของคุณจะไม่ได้รับผลกระทบจนกว่าคุณจะตัดสินใจรวม (merge)
คุณสร้างมันจาก CLI อันดับแรก ติดตั้งและยืนยันตัวตน Apidog CLI:
npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
จากนั้นสร้าง AI branch เอกสารแนะนำให้ตั้งชื่อโดยใช้ วันที่, source branch และวัตถุประสงค์ เพื่อให้ง่ายต่อการระบุในภายหลัง:
apidog branch create --type ai \
--name "ai/20260708-from-main-user-register" \
--from main \
--project <PROJECT_ID>
มีสองสิ่งสำคัญที่นี่ branch ถูกสร้างขึ้นจาก main แต่การสร้างมันไม่ได้กระทบ main และ branch จะเริ่มต้นว่างเปล่า AI Branch จะไม่คัดลอกโปรเจกต์ทั้งหมดของคุณเข้าไปโดยอัตโนมัติ มันจะเก็บเฉพาะทรัพยากรที่ตัวแทน AI นำเข้ามาอย่างชัดเจนเท่านั้น นั่นคือคุณสมบัติด้านความปลอดภัยที่ตั้งใจไว้ ตัวแทน AI สามารถแก้ไขได้เฉพาะสิ่งที่มันนำเข้า ดังนั้นขอบเขตของผลกระทบ (blast radius) จะเป็นไปตามที่คุณกำหนด ไม่ใช่ทั้งโปรเจกต์
หากต้องการดูชุด flag ทั้งหมดสำหรับคำสั่ง branch ใดๆ ให้รันด้วย -h:
apidog branch create -h
นำเข้าทรัพยากรต้นฉบับก่อนแก้ไข
เนื่องจาก AI Branch ว่างเปล่า งานแรกของตัวแทน AI คือการดึงทรัพยากรเฉพาะที่จำเป็นต้องใช้งานเข้ามา นี่คือขั้นตอนที่ป้องกันไม่ให้ตัวแทน AI ทำงานอย่างมืดบอด คุณนำเข้า endpoint, schema หรือเอกสารที่คุณต้องการเปลี่ยนแปลง และไม่มีสิ่งอื่นใดถูกนำเข้ามาด้วย
ชี้ตัวแทน AI (หรือตัวคุณเอง) ไปยังทรัพยากรที่แน่นอนโดยใช้ ID Apidog CLI ใช้ flag ID แบบพหูพจน์และคั่นด้วยเครื่องหมายจุลภาคสำหรับการดำเนินการเหล่านี้:
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>
ตอนนี้ AI branch มีสำเนาของ endpoint 1 และ 2 และ schema 3 ตามที่มีอยู่ใน main ตัวแทน AI จะทำงานกับสำเนาเหล่านี้ ไม่ว่ามันจะทำอะไรกับสำเนา ต้นฉบับบน main จะยังคงไม่เปลี่ยนแปลง หากตัวแทน AI ลบ endpoint ที่นี่ มันจะลบสำเนา ไม่ใช่เส้นทางที่ใช้งานจริง นี่คือความแตกต่างระหว่าง "ตัวแทน AI ทำลาย API ของเรา" กับ "ตัวแทน AI ทำลายสำเนาชั่วคราวที่เราสามารถทิ้งไปได้"
หากคุณกำลังควบคุมสิ่งนี้ผ่าน coding agent คำสั่งเดียวกันจะทำงานภายใน agent loop Apidog CLI จะคืนค่า JSON ที่มีโครงสร้าง พร้อมด้วย agentHints.nextSteps เพื่อให้ตัวแทน AI สามารถอ่านผลลัพธ์ของแต่ละคำสั่งและตัดสินใจว่าจะทำอะไรต่อไป โดยที่คุณไม่จำเป็นต้องแปลผลลัพธ์ให้มัน คู่มือ apidog-cli ใน Cursor แสดงรูปแบบนี้ที่เชื่อมต่อเข้ากับ editor จริง
ให้ตัวแทน AI แก้ไข จากนั้นอ่านความแตกต่าง (diff)
เมื่อนำเข้าทรัพยากรแล้ว ให้ตัวแทน AI ทำงาน มันจะสร้าง, อัปเดต หรือลบ endpoint, schemas, docs และ test scenarios ภายใน AI branch ทุกการเขียนเหล่านั้นจะถูกจำกัดอยู่ในขอบเขต
เมื่อเสร็จสิ้น คุณจะตรวจสอบก่อนที่จะรวม (merge) สิ่งใด ไม่มีสิ่งใดในขั้นตอนการทำงานของ AI Branch ที่เป็นอัตโนมัติ การรวม (merge) เป็นการตัดสินใจของมนุษย์ ตรวจสอบการเปลี่ยนแปลงจาก CLI หรือไคลเอนต์ Apidog และยืนยันว่าความแตกต่าง (diff) ตรงกับสิ่งที่คุณต้องการจริง นี่คือประตูของคุณ หากตัวแทน AI ทำงานผิดพลาด คุณจะเห็นได้ที่นี่ และวิธีแก้ปัญหาคือการทิ้ง branch นั้นไป ไม่ใช่การย้อนกลับ (rollback) production
ถือว่าการตรวจสอบนี้เป็นภาคบังคับ ไม่ใช่ทางเลือก จุดประสงค์ของขั้นตอนการทำงานทั้งหมดคือเพื่อให้มนุษย์ตรวจสอบผลลัพธ์ของตัวแทน AI ก่อนที่มันจะกลายเป็นจริง การข้ามการตรวจสอบจะทำให้การแยกตัว (isolation) ไม่มีผล
นำการเปลี่ยนแปลงเข้าสู่ระบบด้วย merge request
วิธีการรวม (merge) ขึ้นอยู่กับว่า target branch ได้รับการป้องกันหรือไม่ นี่คือประโยชน์ของ main branch ที่ได้รับการป้องกัน
หาก target branch ไม่ได้รับการป้องกัน คุณสามารถรวม (merge) โดยตรง โดยระบุทรัพยากรที่แน่นอนที่จะนำเข้ามา:
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>
หาก main ได้รับการป้องกัน ซึ่งควรจะเป็น การรวม (merge) โดยตรงจะถูกบล็อก แทนที่จะเป็นเช่นนั้น คุณจะต้องเปิด merge request และส่งการเปลี่ยนแปลงผ่านการตรวจสอบ:
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>
merge request เป็นเส้นทางที่แนะนำสำหรับการสร้างสรรค์ใดๆ ที่เกิดจากตัวแทน AI มันจะบังคับให้การเปลี่ยนแปลงผ่านกระบวนการตรวจสอบแบบเดียวกับที่ผู้ร่วมให้ข้อมูลที่เป็นมนุษย์จะต้องเผชิญ เพื่อนร่วมทีมอนุมัติ จากนั้นมันก็จะถูกนำไปใช้งาน ตัวแทน AI จะไม่เขียนไปยัง main ด้วยตัวเอง มันสามารถร้องขอให้มนุษย์ยอมรับงานของมันผ่าน merge request เท่านั้น โปรดทราบว่าการรวม (merge) จะนำมาเฉพาะ ID ทรัพยากรที่คุณระบุ หากตัวแทน AI ไปยุ่งเกี่ยวกับสิ่งที่คุณไม่ได้ตั้งใจจะนำไปใช้ คุณก็ไม่ต้องรวม ID นั้นในการ merge และมันจะยังคงอยู่เบื้องหลัง
สิ่งนี้สะท้อนวิธีการที่ เวิร์กโฟลว์ API แบบ Git-native จัดการกับผู้ร่วมให้ข้อมูลที่เป็นมนุษย์: branch, เสนอ (propose), ตรวจสอบ (review), รวม (merge) AI Branch ใช้ระเบียบวินัยเดียวกันกับผู้ร่วมให้ข้อมูลที่ไม่ใช่มนุษย์ ซึ่งเป็นคนที่คุณไม่ต้องการให้เขียนไปยัง main โดยตรงมากที่สุด
จัดการสาขาที่รวมแล้วและถูกละทิ้ง
AI branch ที่รวมแล้วหรือถูกละทิ้งควรถูเก็บถาวรทันทีเพื่อให้รายการ branch อ่านง่าย เมื่อ branch ถูกรวมแล้ว หรือคุณตัดสินใจว่าไม่ต้องการมัน ให้เก็บถาวรมันก่อน จากนั้นจึงลบ:
apidog branch archive "ai/20260708-from-main-user-register" \
--type ai \
--project <PROJECT_ID>
จังหวะการทำงานที่แนะนำคือหนึ่ง AI branch ต่องานหนึ่งงาน หนึ่ง branch จะสอดคล้องกับหน่วยงานของตัวแทน AI เพียงหน่วยเดียว ได้รับการตรวจสอบ ถูกรวมหรือทิ้งไป จากนั้นจึงถูกเก็บถาวร นั่นทำให้การแยกตัว (isolation) มีความหมาย คุณจะไม่ต้องตรวจสอบ branch ที่มีการแก้ไขจากสามเซสชันที่ไม่เกี่ยวข้องสะสมอยู่
สุขอนามัยสำหรับตัวแทน AI ที่ปลอดภัยรอบๆ branch
AI Branch จัดการการแยกตัว (isolation) ได้ แต่จะทำงานได้ดีที่สุดเมื่อใช้ร่วมกับพฤติกรรมบางอย่างที่จำกัดสิ่งที่ตัวแทน AI สามารถเข้าถึงได้ตั้งแต่แรก
- ใช้โทเค็นการเข้าถึงที่มีสิทธิ์น้อยที่สุด (least-privilege access tokens) โทเค็นที่คุณส่งไปยัง
apidog login --with-tokenจะกำหนดขอบเขตสิ่งที่ตัวแทน AI สามารถทำได้ ให้สิทธิ์การเข้าถึงโทเค็นอัตโนมัติเฉพาะโปรเจกต์ที่จำเป็นเท่านั้น และไม่มีอะไรมากไปกว่านั้น อย่ามอบโทเค็นเจ้าของส่วนตัวของคุณให้ตัวแทน AI เพียงเพราะมันสะดวก หากโทเค็นรั่วไหลหรือตัวแทน AI ทำงานผิดพลาด คุณต้องการให้ความเสียหายจำกัดอยู่ภายในขอบเขตของโทเค็น - ป้องกัน main branch ของคุณ นี่เป็นการตั้งค่าเดียวที่เปลี่ยน "ตรวจสอบก่อนรวม (merge)" จากคำแนะนำให้เป็นกฎ เมื่อ
mainได้รับการป้องกัน เส้นทางการรวม (merge) โดยตรงจะถูกปิด และการเปลี่ยนแปลงทั้งหมดของตัวแทน AI จะต้องผ่านmerge-request createการป้องกันคือสิ่งที่ทำให้ merge request ไม่ใช่ทางเลือก - ตรวจสอบก่อนรวม (merge) ทุกครั้ง การแยกตัว (isolation) จะปกป้องคุณก็ต่อเมื่อมนุษย์ได้อ่านความแตกต่าง (diff) จริงๆ สร้างการตรวจสอบให้เป็นส่วนหนึ่งของเวิร์กโฟลว์เพื่อไม่ให้ข้ามได้ ตัวแทน AI ที่เชื่อถือได้มาเป็นเวลาหนึ่งสัปดาห์ก็ยังสามารถอ่านคำสั่งผิดพลาดในวันที่แปดได้
- มอบหมายงาน จากนั้นตรวจสอบ นี่คือรูปแบบที่เชื่อมโยงทุกสิ่งเข้าด้วยกัน คุณมอบหมายงานที่กำหนดขอบเขตให้ตัวแทน AI ปล่อยให้มันทำงานใน branch ที่แยกออกมา จากนั้นตรวจสอบผลลัพธ์ก่อนที่จะรวม (merge) ตัวแทน AI ทำงาน; คุณเป็นผู้รับผิดชอบการยอมรับ การแบ่งแยกแบบเดียวกันนี้ปรากฏขึ้นเมื่อตัวแทน AI รันการทดสอบ: ตัวแทน AI จะดำเนินการชุดทดสอบ คุณตรวจสอบผลลัพธ์ test harness และ exit code ก่อนที่จะเชื่อถือมัน มอบหมายการลงมือทำ แต่ยังคงรักษาการตัดสินใจไว้
หากคุณกำลังจัดการเวอร์ชัน API spec ของคุณใน Git ควบคู่ไปกับสิ่งเหล่านี้ เวิร์กโฟลว์ การควบคุมเวอร์ชัน OpenAPI จะให้ประวัติอีกชั้นหนึ่งที่คุณสามารถใช้เปรียบเทียบ (diff) ได้เมื่อมีบางอย่างดูผิดปกติ
ขั้นตอนการทำงานแบบครบวงจร ตามลำดับ
นี่คือทั้งหมดเป็นลำดับที่คุณสามารถมอบหมายให้ตัวแทน AI หรือดำเนินการเองได้:
apidog branch create --type aiจากmainโดย branch จะว่างเปล่าและmainจะไม่ถูกแตะต้องapidog branch pick-toเฉพาะ endpoint และ schema ที่ตัวแทน AI ต้องการ ไม่มีสิ่งอื่นเข้ามา- ให้ตัวแทน AI แก้ไขภายใน branch ทุกการเขียนจะถูกจำกัดอยู่ในขอบเขต
- ตรวจสอบความแตกต่าง (diff) จาก CLI หรือไคลเอนต์ นี่คือประตูการตรวจสอบของมนุษย์
apidog merge-request createกับmainที่ได้รับการป้องกัน เพื่อนร่วมทีมอนุมัติ ตัวแทน AI จะไม่เขียนไปยัง main โดยตรงapidog branch archiveเมื่อรวมแล้วหรือถูกละทิ้ง
ไม่มีจุดใดที่ตัวแทน AI จะสามารถเขียนทับหรือลบ endpoint ที่ใช้งานจริงบน main ได้ สิ่งที่เลวร้ายที่สุดที่มันสามารถทำได้คือการสร้างการเปลี่ยนแปลงที่ไม่ดีกับสำเนาชั่วคราวที่คุณเลือกที่จะไม่รวม (merge)
ให้ตัวแทน AI มีพื้นที่ทำงานโดยไม่ต้องมอบกุญแจให้พวกมัน
ตัวแทน AI มีประโยชน์อย่างยิ่งเพราะพวกมันสามารถดำเนินการได้โดยไม่ต้องรอคำถาม นั่นคือสิ่งที่ทำให้การเข้าถึงการเขียนแบบไม่จำกัดเป็นอันตราย คำตอบไม่ใช่การทำให้ตัวแทน AI ทำงานช้าลง แต่เป็นการทำให้การเขียนที่รวดเร็วและไม่ลังเลของมันไปอยู่บนพื้นที่ที่ปลอดภัย AI branch ที่แยกออกมา, main ที่ได้รับการป้องกัน, โทเค็นที่มีสิทธิ์น้อยที่สุด และการตรวจสอบภาคบังคับ จะเปลี่ยนประโยคที่ว่า "ตัวแทน AI ทำลาย API ของเรา" ให้กลายเป็นความแตกต่าง (diff) ที่คุณเหลือบมองแล้วปฏิเสธ
Apidog สร้างสิ่งนี้มาให้คุณ คุณจึงไม่ต้องประกอบมันจากเครื่องมือแยกต่างหาก ใช้ Apidog CLI, สร้าง AI branch และปล่อยให้ตัวแทน AI ของคุณแก้ไขกับสำเนาแทนที่จะเป็นของจริง ดาวน์โหลด Apidog เพื่อทดลองขั้นตอนการทำงานของ AI Branch และอ่าน เอกสาร AI Branch สำหรับการอ้างอิงคำสั่งแบบเต็มก่อนที่คุณจะนำไปใช้ในเวิร์กโฟลว์การผลิต