Rihpig

Posted on Jul 14 • Originally published at apidog.com

AI 에이전트의 API 장애 예방 방법

AI 에이전트에게 API 프로젝트 쓰기 권한을 부여하면 심각한 문제가 발생할 수 있습니다. 악의적인 의도가 있어서가 아닙니다. 에이전트는 프롬프트가 지시한 작업을 수행할 뿐입니다. 예를 들어 “사용자 엔드포인트를 정리해라”라고 요청하면, 여전히 다른 서비스가 의존하는 라이브 경로를 삭제할 수 있습니다. “스키마를 업데이트해라”라고 요청하면 다른 엔드포인트 세 곳이 참조하는 데이터 모델을 덮어쓸 수도 있습니다. 에이전트는 프로덕션에 무엇이 배포되었는지 알지 못하며, 자신에게 접근 가능한 리소스만 보고 수정합니다.

지금 Apidog 사용해 보기

이것은 새로운 유형의 운영 위험입니다. 사람이 직접 수정할 때는 엔드포인트를 삭제하기 전에 보통 멈추고 확인합니다. 반면 터미널에서 반복 작업을 수행하는 에이전트는 명령을 실행하고 성공 응답을 받으면 다음 단계로 넘어갑니다. 그 명령이 메인 브랜치에 적용됐다면 변경 사항은 이미 API 디자인 소스에 반영된 상태입니다.

해결책은 에이전트를 막는 것이 아닙니다. 에이전트가 빠르게 작업하되, 벗어날 수 없는 샌드박스에서 작업하도록 만드는 것입니다. Apidog의 AI 브랜치는 이 용도로 설계되었습니다. 에이전트가 수행한 모든 편집은 격리된 브랜치에 저장되고, 사람이 검토하고 병합하기 전까지 소스 브랜치와 메인 브랜치는 변경되지 않습니다.

이 글에서는 AI 브랜치를 사용하는 CLI 흐름을 처음부터 끝까지 설명하고, 함께 적용해야 할 안전한 에이전트 운영 원칙도 정리합니다. 기능의 설계 원칙은 AI 브랜치 및 안전한 에이전트 기반 변경 사항에서 확인할 수 있습니다. 여기서는 바로 실행할 수 있는 절차에 집중합니다.

에이전트 쓰기 권한이 기본적으로 위험한 이유

대부분의 도구는 에이전트에게 프로젝트 전체에 대한 단일 접근 수준을 제공합니다. 에이전트가 엔드포인트를 생성할 수 있다면 삭제도 할 수 있습니다. 스키마를 수정할 수 있다면 호환되지 않는 구조로 교체할 수도 있습니다.

즉, “에이전트가 변경을 제안했다”와 “변경이 실제 소스에 반영됐다” 사이에 안전장치가 없습니다.

다음 세 가지 실패 모드가 자주 발생합니다.

덮어쓰기: 에이전트가 API를 부분적으로만 이해한 상태에서 스키마를 재생성하고, 다른 엔드포인트가 필요로 하는 필드를 제거합니다.
삭제: 에이전트가 엔드포인트를 “통합”하면서, 실제 클라이언트가 아직 호출 중인 경로를 제거합니다.
무의식적인 표류: 한 세션에서 수십 개의 작은 변경을 수행합니다. 각 변경은 문제없어 보여도, 전체적으로는 배포된 API와 조용히 멀어질 수 있습니다.

이 문제는 예외 상황이 아닙니다. 에이전트가 잘못된 브랜치에서 작업할 때 발생하는 일반적인 결과입니다.

목표는 에이전트가 잘못된 브랜치에 접근하는 일을 불가능하게 만드는 것입니다.

핵심 해결책: 격리된 AI 브랜치

AI 브랜치는 외부 AI 도구 및 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 브랜치는 비어 있는 상태로 시작합니다.

AI 브랜치는 프로젝트 전체를 자동으로 복사하지 않습니다. 에이전트가 명시적으로 가져온 리소스만 브랜치에 포함됩니다. 따라서 에이전트가 수정할 수 있는 범위는 프로젝트 전체가 아니라, 사용자가 지정한 엔드포인트와 스키마로 제한됩니다.

사용 가능한 전체 옵션은 다음 명령으로 확인할 수 있습니다.

apidog branch create -h

소스 리소스를 편집하기 전에 가져오기

AI 브랜치는 비어 있으므로, 에이전트가 작업을 시작하기 전에 필요한 리소스를 가져와야 합니다. 이 단계는 에이전트가 프로젝트 전체를 대상으로 무분별하게 수정하는 일을 방지합니다.

수정할 엔드포인트, 데이터 스키마, 문서만 선택해서 가져오세요. 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를 삭제하는 대신 버려도 되는 임시 복사본만 잘못 수정하게 됩니다.

코딩 에이전트와 함께 CLI를 사용하는 경우에도 같은 명령을 에이전트 루프에서 실행할 수 있습니다. Apidog CLI는 agentHints.nextSteps와 함께 구조화된 JSON을 반환하므로, 에이전트는 명령 결과를 읽고 다음 작업을 결정할 수 있습니다. 실제 에디터 통합 방식은 Cursor에서 apidog-cli 사용하기에서 확인할 수 있습니다.

에이전트가 편집하게 한 다음 변경 사항 확인

필요한 리소스를 가져온 뒤에만 에이전트에게 작업을 맡깁니다.

에이전트는 AI 브랜치에서 다음 작업을 수행할 수 있습니다.

엔드포인트 생성, 수정, 삭제
데이터 스키마 생성 및 업데이트
API 문서 수정
테스트 시나리오 생성 및 변경

이 모든 쓰기 작업은 AI 브랜치에만 적용됩니다.

작업이 끝나면 병합 전에 반드시 변경 사항을 검토합니다. AI 브랜치 흐름에서는 자동 병합이 기본 동작이 아닙니다. 병합은 사람이 내리는 결정이어야 합니다.

CLI 또는 Apidog 클라이언트에서 차이를 확인하고 다음 항목을 검토하세요.

변경된 엔드포인트가 요청한 범위에 포함되는가?
제거된 필드가 다른 엔드포인트에 영향을 주지 않는가?
응답 형식이나 인증 요구 사항이 호환성을 깨지 않는가?
에이전트가 의도하지 않은 리소스를 수정하지 않았는가?

에이전트가 잘못된 방향으로 작업했다면 프로덕션을 롤백할 필요가 없습니다. 해당 AI 브랜치를 폐기하면 됩니다.

검토는 선택 사항이 아니라 이 흐름의 핵심 게이트입니다. 검토를 건너뛰면 격리의 효과도 사라집니다.

병합 요청으로 변경 사항 적용

병합 방법은 대상 브랜치가 보호되어 있는지에 따라 달라집니다. 운영 환경에서는 main을 보호 브랜치로 설정하는 것이 좋습니다.

대상 브랜치가 보호되지 않은 경우, 병합할 리소스 ID를 명시하여 직접 병합할 수 있습니다.

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 브랜치는 이 규율을 비인간 기여자인 에이전트에게도 적용합니다.

병합되거나 폐기된 브랜치 정리

병합이 완료됐거나 더 이상 필요 없는 AI 브랜치는 즉시 보관하세요. 브랜치 목록을 정리하고, 오래된 작업이 다시 사용되는 실수를 줄일 수 있습니다.

apidog branch archive "ai/20260708-from-main-user-register" \
  --type ai \
  --project <PROJECT_ID>

권장 패턴은 작업 하나당 AI 브랜치 하나입니다.

각 브랜치는 다음 수명 주기를 가져야 합니다.

하나의 에이전트 작업을 위해 생성
필요한 리소스만 가져오기
에이전트 편집 수행
사람 검토
병합 또는 폐기
브랜치 보관

이 방식이면 관련 없는 세션의 변경 사항이 한 브랜치에 누적되지 않으며, 검토 범위도 항상 명확하게 유지됩니다.

브랜치 주변의 안전한 에이전트 운영 원칙

AI 브랜치는 변경 사항을 격리하지만, 에이전트가 처음부터 접근할 수 있는 범위도 제한해야 합니다.

최소 권한 접근 토큰 사용

apidog login --with-token에 전달하는 토큰은 에이전트가 할 수 있는 작업 범위를 결정합니다.

자동화용 토큰에는 다음 원칙을 적용하세요.

필요한 프로젝트에만 접근 권한 부여
필요한 역할과 권한만 부여
개인 소유자 토큰을 자동화에 사용하지 않기
토큰 유출 또는 에이전트 오작동 시 피해 범위 최소화

편의를 위해 과도한 권한을 부여하면 AI 브랜치의 격리 효과도 약해집니다.

메인 브랜치 보호

main을 보호하면 “병합 전 검토”가 권장 사항이 아니라 강제 규칙이 됩니다.

보호된 main에서는 직접 병합 경로가 닫히고, 에이전트가 만든 모든 변경은 merge-request create를 통해 검토자에게 전달되어야 합니다.

매번 병합 전에 검토

격리는 사람이 실제 변경 내용을 읽을 때만 의미가 있습니다. 에이전트가 이전 작업에서 정확한 결과를 냈더라도, 다음 작업에서 프롬프트를 잘못 해석할 수 있습니다.

검토 단계를 자동화 파이프라인에서 생략할 수 없는 게이트로 만드세요.

위임하고, 확인하기

안전한 에이전트 운영의 핵심 패턴은 다음과 같습니다.

범위가 제한된 작업을 에이전트에 위임합니다.
에이전트는 격리된 브랜치에서 작업합니다.
사람은 병합 전에 결과를 확인합니다.

에이전트는 실행을 담당하고, 사람은 승인과 판단을 담당합니다.

테스트에서도 같은 원칙을 적용할 수 있습니다. 에이전트가 테스트 스위트를 실행할 수는 있지만, 결과와 종료 코드를 신뢰하기 전에 사람이 확인해야 합니다. 테스트 하니스를 사용하더라도 실행은 위임하고 판단은 유지하세요.

API 명세를 Git으로 버전 관리하고 있다면 OpenAPI 버전 관리 워크플로우도 유용합니다. 예상치 못한 변경이 보일 때 비교할 수 있는 두 번째 변경 이력을 제공합니다.

엔드투엔드 흐름

에이전트에게 전달하거나 직접 실행할 전체 절차는 다음과 같습니다.

main에서 apidog branch create --type ai를 실행합니다. 새 브랜치는 비어 있으며 main은 변경되지 않습니다.
필요한 엔드포인트와 스키마만 apidog branch pick-to로 AI 브랜치에 가져옵니다.
에이전트가 AI 브랜치 안에서만 리소스를 편집하도록 합니다.
CLI 또는 Apidog 클라이언트에서 변경 사항을 검토합니다.
보호된 main을 대상으로 apidog merge-request create를 실행합니다.
검토자가 승인하면 변경 사항을 병합합니다.
작업이 끝난 AI 브랜치는 apidog branch archive로 보관합니다.

이 흐름에서는 에이전트가 main의 라이브 엔드포인트를 직접 덮어쓰거나 삭제할 수 있는 경로가 없습니다.

에이전트가 할 수 있는 최악의 실수는 임시 복사본을 잘못 수정하는 것입니다. 그 경우 해당 변경을 병합하지 않으면 됩니다.

에이전트에게 열쇠를 주지 않고 작업 공간 제공하기

에이전트는 매 단계마다 확인을 요청하지 않고 행동하기 때문에 유용합니다. 동시에 그 특성 때문에 무제한 쓰기 권한은 위험합니다.

해답은 에이전트의 속도를 늦추는 것이 아닙니다. 빠르고 주저 없는 쓰기 작업이 안전한 공간에서만 일어나도록 설계하는 것입니다.

격리된 AI 브랜치, 보호된 메인 브랜치, 최소 권한 토큰, 필수 검토를 함께 적용하면 “에이전트가 API를 망가뜨렸다”는 사고를 “검토에서 거절한 변경 사항”으로 바꿀 수 있습니다.

Apidog는 별도 도구를 조합하지 않아도 이 흐름을 지원합니다. Apidog CLI로 AI 브랜치를 만들고, 에이전트가 실제 API가 아닌 격리된 복사본에서 편집하도록 구성하세요.

AI 브랜치 흐름을 시작하려면 Apidog를 다운로드하고, 프로덕션 워크플로우에 연결하기 전에 AI 브랜치 문서에서 전체 명령 참조를 확인하세요.

DEV Community