API 스펙을 수동으로 편집하는 것은 번거로운 작업입니다. 필드 이름을 바꾸고, 열거형 값을 추가하고, 필수 플래그를 강화하는 등 각 변경 사항은 작지만, 이를 참조하는 엔드포인트를 손상시키지 않고 올바른 위치에 적용되어야 합니다. 이는 정밀하고 기계적인 작업이며, 전체 스키마를 엉망으로 만들지 않을 것이라고 신뢰할 수만 있다면 AI 에이전트에게 맡길 만한 종류의 작업입니다.
가능합니다. Apidog CLI는 에이전트가 스펙을 책임감 있게 변경하는 데 필요한 모든 것을 제공합니다: 모든 쓰기 작업 전의 스키마 유효성 검사, 작업할 격리된 브랜치, 그리고 검토를 위한 병합 요청입니다.
이는 에이전트가 API 문서를 생성하도록 하는 것의 _변형_ 동반자입니다. 생성은 추가적이고 위험이 낮지만, 기존 계약을 업데이트하는 것은 안전 장치가 중요한 부분이므로, 이 가이드의 대부분은 아무것도 손상시키지 않고 이를 수행하는 방법에 관한 것입니다.
CLI에서 "스펙 업데이트"의 의미
Apidog의 스펙은 프로젝트 내의 엔드포인트 및 데이터 스키마 세트입니다. 이를 업데이트하는 것은 다음 세 가지 명령어 중 하나를 의미합니다:
endpoint update: 경로, 파라미터, 응답 변경.schema update: 엔드포인트가 참조하는 데이터 모델 변경.import: 프로젝트와 조정하기 위해 완전히 새로운 OpenAPI 파일을 가져오기.
이들 중 어느 하나라도 에이전트에게 지시하기 전에, 두 가지 동작을 이해해야 합니다. 이들을 잘못 이해하면 스펙이 손상될 수 있기 때문입니다. 첫 번째는 권한 모델이고, 두 번째는 데이터를 조용히 삭제하는 함정입니다.
당신을 물게 될 함정: 업데이트는 완전한 교체입니다
이것이 에이전트에게 가르쳐야 할 가장 중요한 단일 사항입니다. CLI의 `update` 명령어는 JSON Patch가 아닙니다. 이 명령어들은 당신이 제공하는 필드를 직접 제출합니다; ID로 배열 항목을 병합하지 않습니다. 하나의 파라미터를 변경할 의도로 부분적인 `parameters` 배열로 업데이트를 보내면, 그 파라미터를 편집하는 것이 아닙니다. 당신이 보낸 하나만으로 전체 배열을 교체하며, 나머지는 모두 사라집니다.
올바른 순서는 항상 _완전한_ 객체에 대한 읽기-수정-쓰기입니다:
# 1. Get the full current resource
apidog endpoint get <endpointId> --project <projectId>
# 2. Edit the complete structure locally (keep every field you're not changing)
# 3. Validate the whole object against the schema
apidog cli-schema get endpoint-create
apidog cli-schema validate endpoint-create --file ./endpoint-full.json
# 4. Write the complete object back
apidog endpoint update <endpointId> --project <projectId> --file ./endpoint-full.json
이것을 에이전트 지침에 명확히 명시하십시오: _`update`에 부분적인 객체를 절대 보내지 마십시오; 항상 전체 리소스를 가져오고, 수정하고, 전체를 다시 보내십시오._ `get` 단계를 건너뛰는 에이전트는 필드를 조용히 삭제할 것입니다. `cli-schema validate`를 먼저 실행하는 에이전트는 실수가 프로젝트에 도달하기 전에 자신의 실수를 잡아냅니다.
안전한 경로: 에이전트가 AI 브랜치에서 작업하게 하십시오
에이전트에게 메인 브랜치에 대한 직접 편집 권한을 줄 수도 있습니다. 적어도 처음에는 그렇게 하지 마십시오. Apidog에는 정확히 이러한 목적을 위해 설계된 전용 격리 메커니즘인 AI 브랜치가 있습니다: 에이전트가 소스 브랜치에 영향을 주지 않고 리소스를 수정하며, 당신이 승인할 때까지 아무것도 다시 병합되지 않습니다. 이를 API 스펙에 대한 풀 리퀘스트라고 생각하십시오.
단계 1: AI 브랜치 생성
apidog branch create --project <projectId> --type ai \
--from main --name "ai/20260713-from-main-refund-fields"
명명 규칙은 `ai/YYYYMMDD-from-source-feature`로, 브랜치의 원본과 목적을 한눈에 알아볼 수 있도록 합니다. `--from` 값은 일반 브랜치가 아닌 메인 브랜치 또는 일반 스프린트 브랜치여야 합니다. 한 가지 유용한 세부 사항: 원본과 차이가 없는 AI 브랜치는 24시간 후에 자동으로 보관되므로, 버려진 실험은 스스로 정리됩니다.
단계 2: 에이전트가 편집할 리소스 가져오기
AI 브랜치는 비어있는 상태로 시작합니다. 소스 브랜치를 자동으로 복제하지 않습니다. 에이전트가 _기존_ 엔드포인트 또는 스키마를 편집하려면 먼저 `pick-to`를 사용하여 해당 리소스를 브랜치로 가져와야 합니다:
apidog branch pick-to --project <projectId> --type ai \
--from main --to "ai/20260713-from-main-refund-fields" \
--endpoint-ids <ids>
에이전트가 브랜치에서 새로 _생성하는_ 리소스는 이 작업이 필요하지 않습니다; 수정하거나 삭제하려는 기존 리소스만 해당됩니다. 이것은 사람들이 자주 잊어버리는 단계입니다: 이 단계를 건너뛰면 에이전트는 비어있는 브랜치를 가지게 되어 편집할 것이 없게 됩니다.
단계 3: 에이전트가 변경 작업을 수행하게 하십시오
이제 에이전트는 이전에 설명한 읽기-수정-쓰기 루프를 실행하지만, `--branch`는 AI 브랜치를 가리킵니다. 모든 편집 내용은 다음 안에 포함됩니다:
apidog endpoint get <endpointId> --project <projectId> \
--branch "ai/20260713-from-main-refund-fields"
apidog endpoint update <endpointId> --project <projectId> \
--branch "ai/20260713-from-main-refund-fields" \
--file ./endpoint-full.json
이 모든 시간 동안 메인 브랜치는 건드려지지 않습니다. 에이전트가 무언가 잘못하더라도, 영향 범위는 하나의 임시 브랜치로 제한됩니다.
단계 4: 검토 후 병합
AI 브랜치의 변경 사항은 자동으로 다시 기록되지 않습니다. 에이전트가 작업을 마치면, _당신_이 어떻게 할지 결정합니다. 대상이 보호되어 있다면, 직접 병합하는 대신 병합 요청을 여십시오:
apidog merge-request --help
apidog branch merge --project <projectId> --type ai \
--from "ai/20260713-from-main-refund-fields" --to main --endpoint-ids <ids>
차이를 검토하고 승인하면, 검증된 변경 사항이 메인 브랜치에 적용됩니다. CLI에서 직접 병합하려면 소스 및 대상 브랜치 모두에 대한 직접 편집 권한이 필요합니다. 메인 브랜치가 보호되어 있다면 `merge-request`를 선호하고 Apidog 클라이언트에서 승인하십시오.
실제 사례: 필드 이름을 안전하게 변경하기
추상적인 규칙은 고개를 끄덕이기는 쉽지만 적용하기는 어렵습니다. 여기 구체적인 예시가 있습니다. 정수형 센트 단위로 변경하기 위해 `Refund` 데이터 모델에서 `amount`를 `amountCents`로 이름을 바꾸고 싶다고 가정해 봅시다.
에이전트에게 이렇게 지시합니다: _“Refund 스키마의 `amount` 필드를 `amountCents`로 변경하고 정수형으로 만드십시오.”_ 에이전트는 규칙에 따라 다음을 수행합니다:
# 1. Fetch the FULL current schema on the AI branch
apidog schema get <refundSchemaId> --project $PID --branch "ai/20260713-from-main-refund-fields"
전체 객체를 다시 가져와서 _전체_ `jsonSchema`를 편집하며, 건드리지 않는 모든 필드를 유지합니다:
{
"name": "Refund",
"jsonSchema": {
"type": "object",
"required": ["orderId", "amountCents"],
"properties": {
"orderId": { "type": "string" },
"amountCents": { "type": "integer" },
"reason": { "type": "string" }
}
}
}
_발생하지 않은_ 일을 주목하십시오: 변경된 하나의 속성만 보내지 않았습니다. `update`는 교체하기 때문에 `orderId`와 `reason`을 그대로 유지한 채 전체 스키마를 보냈습니다. 그리고 다음을 수행합니다:
# 2. Validate the complete object
apidog cli-schema validate schema-create --file ./refund-full.json
# 3. Write it back to the AI branch
apidog schema update <refundSchemaId> --project $PID \
--branch "ai/20260713-from-main-refund-fields" --file ./refund-full.json
AI 브랜치 diff를 검토하고(하나의 필드 이름이 변경되었고, 다른 것은 방해받지 않음) 병합합니다. 이것이 전체 규칙입니다: 완전한 객체, 유효성 검사 완료, 브랜치에서, 검토 후 병합.
병합하기 전에 호환성을 깨는 변경 사항 플래그 지정
필수 필드의 이름을 변경하는 것은 호환성을 깨는 변경 사항입니다: 이제 `amount`를 보내는 모든 클라이언트는 유효성 검사에 실패할 것입니다. 좋은 에이전트 지침 세트는 모델이 조용히 병합하는 대신 _그렇게 말하도록_ 만듭니다. 에이전트 규칙에 다음을 추가하십시오:
Before merging any spec change, classify it:
- Non-breaking (new optional field, new endpoint, loosened constraint) → summarize and proceed to merge-request.
- Breaking (renamed/removed field, new required field, tightened type) → STOP.
Report the breaking change and the affected endpoints, and wait for explicit human approval.
AI 브랜치가 이를 안전하게 강제할 수 있도록 합니다: 아무것도 자동으로 병합되지 않으므로, “중지하고 보고”는 이미 발생한 쓰기 작업에 대한 경쟁이 아니라 실제 검문소입니다.
대신 OpenAPI 파일에서 업데이트하기
때로는 변경 사항이 이미 코드에서 생성되었거나, 다른 곳에서 편집되었거나, 다른 팀에서 전달받은 OpenAPI 파일 형태로 존재할 수 있습니다. 필드별로 편집 내용을 다시 재생하는 대신, 에이전트가 파일을 가져와 프로젝트와 조정할 수 있습니다:
apidog import --project <projectId> --format openapi --file ./openapi.json \
--branch "ai/20260713-from-main-refund-fields"
`import`는 OpenAPI 3.x, Swagger 2.0, Postman 등을 지원합니다. 먼저 AI 브랜치에 대해 실행하여 들어오는 스펙 변경 사항이 메인 브랜치에 도달하기 전에 검토할 수 있도록 하십시오. 병합 후, 조정된 스펙을 다시 내보내 결과를 확인할 수 있습니다:
apidog export --project <projectId> --format openapi --oas-version 3.1 --output ./openapi.json
이 방법은 진실의 원천이 Apidog 외부에 있고 이를 동기화할 때 가장 좋습니다. Apidog이 진실의 원천이고 정밀한 변경을 할 때는 필드별 `update` 방법이 가장 좋습니다.
에이전트가 잘못했을 때: 롤백
AI 브랜치에서 작업하는 이유는 실수를 되돌리기가 쉽기 때문입니다. 에이전트가 원치 않는 변경 사항을 생성하더라도, 당신이 병합하지 않았으므로 메인 브랜치는 이미 올바른 상태입니다. 그냥 브랜치를 보관하고 다음으로 넘어가십시오:
apidog branch archive "ai/20260713-from-main-refund-fields" --project <projectId> --type ai
어차피 승인된 차이가 없는 AI 브랜치는 24시간 후에 자동으로 보관되므로, 잊혀진 실험조차도 스스로 정리됩니다. 이는 나쁜 `update`가 즉시 적용되고 유일한 해결책이 휴지통이나 수동 되돌리기뿐인 에이전트가 메인 브랜치를 직접 편집하는 경우와 비교됩니다. 브랜치는 관료주의가 아니라 실행 취소 버튼입니다.
권한에 대한 참고
`update` 또는 `import`가 차단되면, 프로젝트의 외부 AI 편집 권한이 꺼져 있는 것입니다. 이는 의도적인 제한이며, 위의 AI 브랜치 흐름이 그 해결책입니다: 에이전트가 격리된 브랜치를 편집하고 당신이 병합을 승인합니다. 직접 편집을 허용하고 싶다면, 스위치는 프로젝트 설정 → 기능 설정 → AI 기능 설정(Apidog 클라이언트 2.8.32 이상)에 있습니다. 에이전트가 권한 장벽에 부딪히면, 조용히 해결책을 찾게 하지 말고 인간에게 선택권을 제시하십시오.
일반적인 문제
- 부분 업데이트로 필드가 지워짐. 가장 손상적이고 흔한 실수입니다.
update는 교체합니다; 병합하지 않습니다. 전체 객체를 가져와서 전체를 편집하고, 유효성 검사를 거친 다음 쓰십시오. 필드가 사라졌다면 에이전트가 부분 페이로드를 보낸 것입니다. - AI 브랜치에서 기존 리소스를 가져오지 않고 편집. 브랜치는 비어있는 상태로 시작합니다. 먼저
pick-to로 리소스를 가져와야 합니다. 그렇지 않으면 에이전트가 편집할 것이 없습니다. - AI 브랜치에 대한 잘못된
--from값. 소스는 메인 브랜치 또는 스프린트 브랜치여야 하며, 일반 브랜치는 절대 안 됩니다. 이 값을 잘못 지정하면branch create명령어가 오류를 발생시킬 것입니다. - 유효성 검사 건너뛰기.
cli-schema validate는 당신의 머신에서 잘못 구성된 페이로드를 잡아냅니다. 유효성 검사 없이 쓰는 에이전트는 오타를 실패한 API 호출로 만들거나, 더 나쁘게는 잘못된 병합을 초래합니다. - 호환성을 깨는 변경 사항을 조용히 병합. '먼저 분류' 규칙 없이는 에이전트가 필수 필드의 이름을 기꺼이 바꾸고 병합할 것입니다. 호환성을 깨는 변경 사항 감지를 명시적인 검문소로 만드십시오.
자주 묻는 질문
- 에이전트가 메인 브랜치를 직접 편집하도록 할 수 있나요? 외부 AI 편집 권한을 활성화하면 할 수 있지만, AI 브랜치에서 시작하는 것이 더 안전합니다: 병합을 승인할 때까지 메인 브랜치에 아무것도 적용되지 않습니다. 직접 편집은 위험이 낮고 신뢰도가 높은 자동화에 한정하여 사용하십시오.
branch merge와merge-request의 차이점은 무엇인가요?branch merge는 변경 사항을 즉시 반영하며 양쪽 브랜치에 대한 직접 편집 권한이 필요합니다.merge-request는 검토 가능한 요청을 열어주며, 메인 브랜치가 보호되어 있을 때 올바른 선택입니다.- 에이전트가 Apidog 데스크톱 앱을 필요로 하나요? 아닙니다, CLI는 독립적입니다. 앱은 외부 AI 편집 권한 설정을 전환하는 데만 중요하며, 이는 일회성 구성입니다.
- 에이전트가 필드 이름을 임의로 만들지 않도록 어떻게 보장하나요?
cli-schema get→validate루프가 안전 장치입니다. 임의로 만든 필드가 포함된 페이로드는 프로젝트에 도달하기 전에 로컬에서 유효성 검사에 실패합니다.
마무리
에이전트가 API 스펙을 업데이트하도록 하는 것은 세 가지 조건이 충족될 때 안전합니다: 격리된 AI 브랜치에서 작업하고, 모든 업데이트를 패치보다는 완전한 읽기-수정-쓰기로 처리하며, 사람이 병합을 승인하는 경우입니다. Apidog CLI는 이 세 가지를 명령어로 제공하며, 이는 전체 루프(편집, 유효성 검사, 검토)가 스크립트 가능하고 감사 가능하며, 잘못된 변경 사항은 `archive` 한 번으로 제거될 수 있음을 의미합니다.
AI 브랜치를 설정하고, 에이전트에게 읽기-수정-쓰기 규칙과 호환성을 깨는 변경 사항 검문소를 전달하면, 스펙 유지 관리는 계속 미루던 번거로운 작업 대신 당신이 승인하는 diff가 됩니다. CLI를 얻으려면 Apidog를 다운로드하고, 에이전트가 문서를 생성하도록 하는 것과 결합하여 전체 작성 및 유지 관리 루프를 다루십시오.