AI 에이전트에게 API 프로젝트에 대한 쓰기 권한을 부여하면 심각한 피해를 입을 수 있습니다. 악의적으로가 아니라, 에이전트는 프롬프트가 지시하는 대로만 행동합니다. "사용자 엔드포인트를 정리해라"라고 요청하면 아직 의존하고 있는 라이브 경로를 삭제할 수도 있습니다. "스키마를 업데이트해라"라고 요청하면 다른 세 개의 엔드포인트가 참조하는 데이터 모델을 덮어쓸 수도 있습니다. 에이전트는 프로덕션에 무엇이 배포되는지 알지 못합니다. 에이전트는 자신이 접근할 수 있는 리소스만 보고, 그것들을 건드립니다.
이것은 새로운 종류의 위험입니다. 사람이 그런 수정을 할 때는 엔드포인트를 삭제하기 전에 주저했습니다. 터미널에서 루프를 도는 에이전트는 주저하지 않습니다. 명령을 실행하고 성공 응답을 받은 다음 다음으로 넘어갑니다. 그 명령이 메인 브랜치에 도달했다면, 변경 사항은 이미 디자인 소스에 라이브로 적용된 것입니다.
해결책은 에이전트를 차단하는 것이 아닙니다. 에이전트가 벗어날 수 없는 샌드박스를 제공하는 것입니다. Apidog의 AI 브랜치는 정확히 그 역할을 합니다. 에이전트가 수행하는 모든 편집은 격리된 브랜치에 저장되며, 소스 브랜치는 변경되지 않고, 사람이 변경 사항을 검토하고 병합하기 전까지는 메인 브랜치에 아무것도 도달하지 않습니다. 이 게시물에서는 CLI 흐름을 처음부터 끝까지 안내한 다음, 그 주변에서 유지해야 할 일반적인 안전한 에이전트 위생에 대해 다룹니다. 이 기능의 디자인 원칙에 대한 자세한 내용은 AI 브랜치 및 안전한 에이전트 기반 변경 사항에 대한 심층적인 글을 참조하십시오. 이 글은 실용적인 실행 가이드입니다.
에이전트 쓰기 권한이 기본적으로 위험한 이유
대부분의 도구는 에이전트에게 한 가지 수준의 접근 권한, 즉 프로젝트에 대한 접근 권한을 부여합니다. 에이전트가 엔드포인트를 생성할 수 있다면 삭제할 수도 있습니다. 스키마를 업데이트할 수 있다면 호환되지 않는 것으로 교체할 수도 있습니다. "에이전트가 변경을 제안했다"와 "변경이 실제 소스에 반영되었다" 사이에는 아무런 간극이 없습니다.
세 가지 실패 모드가 계속해서 나타납니다:
- 덮어쓰기. 에이전트가 API에 대한 부분적인 이해를 바탕으로 스키마를 재생성하고 다른 엔드포인트에 필요한 필드를 삭제합니다.
- 삭제. 에이전트가 엔드포인트를 "통합"하고 라이브 클라이언트가 여전히 호출하는 경로를 제거합니다.
- 무의식적인 표류. 에이전트가 한 세션 동안 수십 개의 작은 편집을 합니다. 개별 변경 사항은 잘못되어 보이지 않지만, 전체적으로 보면 배포된 내용과 조용히 멀어집니다.
이 중 어느 것도 특별한 사례가 아닙니다. 이것들은 에이전트가 잘못된 브랜치에서 작업을 수행할 때 발생하는 일반적인 결과입니다. 목표는 잘못된 브랜치에 접근하는 것을 불가능하게 만드는 것입니다.
핵심 해결책: 격리된 AI 브랜치
AI 브랜치는 외부 AI 및 CLI 작업을 위해 구축된 특별한 종류의 스프린트 브랜치입니다. 이를 생성하면 에이전트는 그 안에서 편집하고 변경 사항은 거기에 머무릅니다. 사용자가 병합을 결정할 때까지 소스 브랜치와 메인 브랜치는 영향을 받지 않습니다.
CLI에서 생성합니다. 먼저 Apidog CLI를 설치하고 인증하십시오:
npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
그런 다음 AI 브랜치를 생성하십시오. 문서는 나중에 쉽게 찾을 수 있도록 날짜, 소스 브랜치 및 목적을 사용하여 이름을 지정하도록 권장합니다:
apidog branch create --type ai \
--name "ai/20260708-from-main-user-register" \
--from main \
--project <PROJECT_ID>
여기서 중요한 두 가지가 있습니다. 브랜치는 `main`에서 생성되지만, 생성한다고 해서 `main`이 변경되지는 않습니다. 그리고 브랜치는 비어있는 상태로 시작합니다. AI 브랜치는 자동으로 전체 프로젝트를 복사하지 않습니다. 에이전트가 명시적으로 가져온 리소스만 보관합니다. 이것은 의도적인 안전 속성입니다. 에이전트는 가져온 것만 편집할 수 있으므로, 영향 범위는 전체 프로젝트가 아니라 사용자가 지정한 범위로 제한됩니다.
모든 브랜치 명령에 대한 전체 플래그 세트를 보려면 ` -h `와 함께 실행하십시오:
apidog branch create -h
소스 리소스를 편집하기 전에 가져오기
AI 브랜치가 비어 있으므로, 에이전트의 첫 번째 작업은 필요한 특정 리소스를 가져오는 것입니다. 이 단계는 에이전트가 맹목적으로 작동하는 것을 방지합니다. 변경하려는 엔드포인트, 스키마 또는 문서를 가져오고 다른 것은 가져오지 않습니다.
ID를 통해 에이전트(또는 사용자 자신)가 정확한 리소스를 가리키도록 하십시오. Apidog CLI는 이러한 작업에 복수형, 쉼표로 구분된 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 브랜치에는 `main`에 있는 엔드포인트 `1`, `2` 및 스키마 `3`의 복사본이 포함됩니다. 에이전트는 이 복사본에 대해 작업합니다. 에이전트가 이들에게 무슨 짓을 하든 `main`의 원본은 변경되지 않습니다. 에이전트가 여기서 엔드포인트를 삭제하더라도, 라이브 경로가 아닌 복사본을 삭제하는 것입니다. 이것이 "에이전트가 우리 API를 날려버렸다"와 "에이전트가 우리가 버릴 수 있는 임시 복사본을 날려버렸다"의 차이입니다.
코딩 에이전트를 통해 이 작업을 수행하는 경우, 동일한 명령이 에이전트 루프 내에서 실행됩니다. Apidog CLI는 `agentHints.nextSteps`와 함께 구조화된 JSON을 반환하므로, 에이전트는 각 명령의 결과를 읽고 사용자가 출력을 번역할 필요 없이 다음에 무엇을 할지 결정할 수 있습니다. Cursor 내 apidog-cli 가이드는 이 패턴이 실제 편집기에 어떻게 연결되는지 보여줍니다.
에이전트가 편집하게 한 다음, 변경 사항 확인
리소스를 가져온 후 에이전트가 작업을 수행하도록 합니다. 에이전트는 AI 브랜치 내에서 엔드포인트, 스키마, 문서 및 테스트 시나리오를 생성, 업데이트 또는 삭제합니다. 이러한 모든 쓰기 작업은 격리되어 있습니다.
작업이 완료되면 병합하기 전에 검토합니다. AI 브랜치 흐름에서는 아무것도 자동적이지 않습니다. 병합은 인간의 결정입니다. CLI 또는 Apidog 클라이언트에서 변경 사항을 검사하고 차이점이 실제로 원하는 것과 일치하는지 확인하십시오. 이것이 당신의 게이트입니다. 에이전트가 잘못된 길로 갔다면 여기서 확인할 수 있으며, 해결책은 브랜치를 폐기하는 것이지 프로덕션을 롤백하는 것이 아닙니다.
이 검토를 필수로 취급하고 선택 사항으로 취급하지 마십시오. 전체 흐름의 핵심은 인간이 에이전트의 출력이 실제가 되기 전에 확인하는 것입니다. 검토를 건너뛰는 것은 격리를 무효화합니다.
병합 요청으로 변경 사항 적용
병합 방법은 대상 브랜치가 보호되어 있는지 여부에 따라 다릅니다. 이 지점에서 보호된 메인 브랜치가 효과를 발휘합니다.
대상 브랜치가 보호되지 않은 경우, 가져올 정확한 리소스를 지정하여 직접 병합할 수 있습니다:
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`이 보호되어 있다면 (그리고 그래야 합니다), 직접 병합은 차단됩니다. 대신 병합 요청을 열고 검토를 통해 변경 사항을 라우팅합니다:
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>
병합 요청은 에이전트가 생성한 모든 것에 대해 선호되는 경로입니다. 이는 인간 기여자가 직면할 동일한 검토 흐름을 통해 변경 사항을 강제합니다. 팀원이 승인하면 변경 사항이 적용됩니다. 에이전트는 직접 `main`에 쓰지 않습니다. 병합 요청을 통해 인간에게 자신의 작업을 수락해달라고 요청할 수 있을 뿐입니다. 병합은 나열한 리소스 ID만 전달한다는 점에 유의하십시오. 에이전트가 배포할 의도가 없는 것을 건드렸다면, 해당 ID를 병합에서 제외하고 그대로 둡니다.
이것은 Git-native API 워크플로우가 인간 기여자를 처리하는 방식과 유사합니다: 브랜치, 제안, 검토, 병합. AI 브랜치는 비인간 기여자에게도 동일한 규율을 적용하며, 이는 `main`에 직접 쓰는 것을 가장 원치 않는 경우입니다.
병합되거나 폐기된 브랜치 정리
병합되거나 폐기된 AI 브랜치는 브랜치 목록을 읽기 쉽게 유지하기 위해 즉시 보관해야 합니다. 브랜치가 병합되거나 더 이상 필요 없다고 판단되면 먼저 보관한 다음 삭제하십시오:
apidog branch archive "ai/20260708-from-main-user-register" \
--type ai \
--project <PROJECT_ID>
권장되는 주기는 작업당 하나의 AI 브랜치입니다. 하나의 브랜치는 단일 에이전트 작업 단위에 매핑되고, 검토되고, 병합되거나 폐기된 다음, 보관됩니다. 이는 격리를 의미 있게 유지합니다. 관련 없는 세션의 편집 사항이 누적된 브랜치를 검토하는 일은 결코 없을 것입니다.
브랜치 주변의 안전한 에이전트 위생
AI 브랜치는 격리를 처리하지만, 에이전트가 처음부터 도달할 수 있는 것을 제한하는 몇 가지 습관 내에서 가장 잘 작동합니다.
최소 권한 접근 토큰을 사용하십시오. `apidog login --with-token`에 전달하는 토큰은 에이전트가 수행할 수 있는 범위를 지정합니다. 자동화 토큰에 필요한 프로젝트에만 접근 권한을 부여하고 그 이상은 주지 마십시오. 편리하다고 해서 에이전트에게 개인 소유자 토큰을 넘겨주지 마십시오. 토큰이 유출되거나 에이전트가 오작동하는 경우, 피해를 토큰의 범위 내로 제한하고 싶을 것입니다.
메인 브랜치를 보호하십시오. 이것은 "병합 전 검토"를 제안에서 규칙으로 바꾸는 유일한 설정입니다. `main`이 보호되면 직접 병합 경로는 닫히고 모든 에이전트 변경 사항은 `merge-request create`를 통해야 합니다. 보호는 병합 요청을 선택 사항이 아닌 필수로 만듭니다.
매번 병합하기 전에 검토하십시오. 격리는 인간이 실제로 변경 사항을 읽을 때만 효과가 있습니다. 건너뛸 수 없도록 워크플로우에 검토를 통합하십시오. 일주일 동안 신뢰할 수 있었던 에이전트도 8일째에 프롬프트를 잘못 해석할 수 있습니다.
위임하고 확인하십시오. 이것이 모든 것을 묶는 패턴입니다. 범위가 지정된 작업을 에이전트에 위임하고, 격리된 브랜치에서 실행하도록 한 다음, 병합하기 전에 결과를 확인합니다. 에이전트가 작업을 수행하고, 당신은 승인을 책임집니다. 에이전트가 테스트를 실행할 때도 동일한 분리가 나타납니다. 에이전트가 스위트를 실행하고, 당신은 테스트 하니스 결과와 종료 코드를 신뢰하기 전에 확인합니다. 실행은 위임하고, 판단은 유지하십시오.
이 모든 것과 함께 Git에서 API 사양을 버전 관리하는 경우, OpenAPI 버전 관리 워크플로우는 뭔가 이상해 보일 때 비교할 수 있는 두 번째 기록 계층을 제공합니다.
엔드투엔드 흐름(순서대로)
에이전트에게 전달하거나 직접 실행할 수 있는 전체 시퀀스는 다음과 같습니다:
- `main`에서 `apidog branch create --type ai`를 실행합니다. 브랜치는 비어 있고 `main`은 변경되지 않습니다.
- 에이전트가 필요한 특정 엔드포인트와 스키마를 `apidog branch pick-to`로 가져옵니다. 다른 것은 가져오지 않습니다.
- 에이전트가 브랜치 내에서 편집하도록 합니다. 모든 쓰기 작업은 격리됩니다.
- CLI 또는 클라이언트에서 변경 사항을 검토합니다. 이것이 인간 게이트입니다.
- 보호된 `main`에 대해 `apidog merge-request create`를 실행합니다. 팀원이 승인합니다. 에이전트는 `main`에 직접 쓰지 않습니다.
- 병합되거나 폐기되면 `apidog branch archive`를 실행합니다.
어떤 시점에서도 에이전트가 `main`의 라이브 엔드포인트를 덮어쓰거나 삭제할 수 있는 경로는 없습니다. 에이전트가 할 수 있는 최악의 상황은 임시 복사본에 잘못된 변경을 가하는 것이고, 당신은 그 변경을 병합하지 않으면 됩니다.
에이전트에게 열쇠를 주지 않고도 작업할 공간 제공
에이전트가 묻지 않고 행동하기 때문에 유용합니다. 그것이 또한 무제한 쓰기 접근 권한을 위험하게 만드는 이유입니다. 해답은 에이전트의 속도를 늦추는 것이 아니라, 빠르고 주저하지 않는 쓰기 작업이 안전한 곳에 적용되도록 하는 것입니다. 격리된 AI 브랜치, 보호된 메인 브랜치, 최소 권한 토큰, 그리고 필수 검토를 통해 "에이전트가 우리 API를 날려버렸다"는 한 번 쓱 보고 거절할 수 있는 변경 사항으로 바뀝니다.
Apidog는 당신이 별도의 도구로 조립할 필요 없이 이 기능을 내장합니다. Apidog CLI를 사용하여 AI 브랜치를 생성하고, 에이전트가 실제가 아닌 복사본에 대해 편집하도록 하십시오. AI 브랜치 흐름을 시도하려면 Apidog를 다운로드하고, 프로덕션 워크플로우에 연결하기 전에 AI 브랜치 문서에서 전체 명령 참조를 읽어보십시오.