AI Branch(베타)

AI Branch는 Sprint Branch의 특수한 유형입니다.

Apidog CLI에서 시작된 모든 편집 작업은 기본적으로 AI / AI 에이전트가 시작한 것으로 처리됩니다.

AI Branch는 Apidog 프로젝트에서 AI 에이전트에 격리된 편집 브랜치를 제공하도록 설계되었습니다. AI Branch를 사용하면 AI가 메인 브랜치 또는 표준 스프린트 브랜치를 직접 변경하지 않고도 프로젝트 리소스를 생성하고 업데이트할 수 있습니다. 변경이 완료된 후 사용자는 클라이언트 또는 CLI에서 차이를 검토한 다음, 결과를 대상 브랜치에 직접 병합하거나 병합 요청을 통해 병합할 수 있습니다.

AI Branch가 필요한 이유

AI가 시작한 편집은 예측하기 어려울 수 있으며, Apidog CLI는 광범위한 편집 기능을 제공합니다. AI Branch는 이러한 고위험 AI 시작 편집 작업을 위해 설계되었으며, AI 에이전트가 통제된 범위 내에서 프로젝트 리소스를 편집할 수 있도록 합니다.

또한 Apidog 2.8.31 이상으로 업그레이드하고, 필요에 따라 Project Settings -> Feature Settings -> External AI Edit Permissions에서 메인 브랜치, 표준 스프린트 브랜치 및 일반 브랜치에 대한 직접 편집 권한을 활성화할 수도 있습니다. 활성화되면 이러한 권한은 일반적으로 AI Branch가 필요한 직접 편집 제한을 우회합니다.

AI Branch란 무엇입니까?

AI Branch는 특수한 스프린트 브랜치입니다. 표준 스프린트 브랜치와 마찬가지로 프로젝트 리소스에 대한 변경 사항을 저장합니다. 하지만 기본적으로 CLI 기반 편집과 같은 외부 AI 작업을 위한 것이며, 변경 사항이 병합되기 전에 사람이 확인하는 단계를 유지합니다.

AI Branch의 주요 특징은 다음과 같습니다.

격리된 편집: CLI에서 API, 문서, 데이터 모델, 테스트 시나리오 등의 리소스에 수행한 변경 사항은 AI Branch에 저장되며, 메인 브랜치 또는 소스 브랜치에 직접 영향을 주지 않습니다.

명확한 출처: AI Branch는 Apidog 클라이언트에서 직접 생성할 수 없습니다. 반드시 CLI 또는 MCP 소스에서 생성해야 합니다. AI Branch는 해당 소스 브랜치를 기록하며 일반적으로 해당 소스 브랜치로 다시 병합되므로, AI가 생성한 변경 사항의 맥락을 더 쉽게 이해할 수 있습니다.

사람의 확인: AI Branch의 변경 사항은 병합되기 전에 사용자가 확인해야 합니다. 사용자는 차이를 검토하고, 리소스 범위를 선택하며, 직접 병합할지 병합 요청을 생성할지 선택할 수 있습니다.

수량 제한 없음: 현재 생성할 수 있는 AI Branch 수에는 활성 제한이 없습니다. AI 에이전트는 비즈니스 도메인, 반복 작업 또는 기능별로 데이터를 처리하는 데 이를 사용할 수 있습니다.

자동 보관: 프로젝트 협업 중 AI Branch가 통제되지 않고 증가하는 것을 방지하기 위해 각 AI Branch는 24시간마다 해당 소스 브랜치와 비교됩니다. 차이가 발견되지 않으면 자동으로 보관됩니다. 보관된 AI Branch는 Apidog에서 언제든지 복원할 수 있으며, Apidog CLI에서 새 AI Branch를 제한 없이 다시 생성할 수도 있습니다.

TIP

AI Branch는 외부 AI 또는 CLI 작업의 쓰기 결과를 저장하는 데 사용됩니다. 사용자가 클라이언트 내에서 수행하는 일반적인 편집, 병합 및 검토는 여전히 프로젝트 멤버 권한과 브랜치 보호 규칙을 따릅니다.

사용 사례

AI Branch는 브랜치 격리와 사람의 확인을 유지해야 하면서도 AI가 프로젝트 리소스 유지 관리에 참여해야 하는 경우에 적합합니다.

시나리오	설명
코드에서 API 초안 생성	코드를 읽은 후 AI가 AI Branch에서 HTTP API 엔드포인트를 생성하거나 업데이트합니다. 사용자는 병합 전에 변경 사항을 확인합니다.
API 리소스 일괄 정리	AI는 현재 협업 브랜치에 직접 영향을 주지 않고 API 디렉터리를 조정하고, 설명을 추가하며, 데이터 모델 또는 응답 컴포넌트를 업데이트할 수 있습니다.
자동화 테스트 초안 생성	AI는 테스터의 후속 확인을 위해 AI Branch에서 테스트 시나리오, 테스트 케이스 또는 테스트 데이터를 생성할 수 있습니다.
API 문서의 누락 부분 보완	AI는 버그 보고서, API 구현 또는 OpenAPI 파일을 기반으로 누락된 필드를 보완할 수 있습니다.
CI/CD에서 일괄 쓰기	자동화 워크플로는 생성된 결과를 AI Branch에 쓰고, 병합 전 사용자 검토를 기다릴 수 있습니다.

기본 워크플로

일반적인 AI Branch 워크플로는 다음과 같습니다.

AI Branch를 생성하고 기반이 되는 소스 브랜치를 지정합니다.

편집해야 하는 리소스를 AI Branch로 가져오거나, AI Branch에서 새 리소스를 생성합니다.

AI 에이전트, CLI 또는 자동화 스크립트가 AI Branch의 리소스를 수정합니다.

사용자가 AI Branch와 소스 브랜치 간의 차이를 검토한 다음, 병합할 리소스 범위를 확인합니다.

대상 브랜치 보호 규칙에 따라 직접 병합하거나 병합 요청을 생성합니다.

AI Branch 생성

AI Branch를 생성하려면 branch create --type ai를 사용하십시오. 기존 sprint-branch 및 sb 진입점은 계속 호환되지만, 통합된 branch 진입점을 사용하는 것을 권장합니다.

명령	설명	예시
`branch create --type ai`	AI Branch를 생성합니다.	`apidog branch create --project <projectId> --type ai --name "ai/20260312-from-main-userRegister" --from main`
`branch list --type ai`	프로젝트의 AI Branch를 확인합니다.	`apidog branch list --project <projectId> --type ai`
`branch list --type all`	프로젝트의 모든 브랜치 유형을 확인합니다.	`apidog branch list --project <projectId> --type all`
`branch get --type ai`	지정된 AI Branch의 브랜치 유형 및 소스 정보를 포함한 세부 정보를 확인합니다.	`apidog branch get <branchName> --project <projectId> --type ai`

예시: 사용자 등록 API용 AI Branch 생성

TIP

AI Branch 이름은 ai/YYYYMMDD-from-sourceBranch-featureOrModule 형식으로 지정하는 것을 권장합니다. 예: ai/20260312-from-main-userRegister. 명확한 이름은 팀이 브랜치의 소스, 목적 및 생성 시간을 이해하는 데 도움이 됩니다.

AI Branch에서 리소스 편집

CLI가 프로젝트 리소스를 쓸 때 브랜치 매개변수를 사용하여 해당 리소스를 AI Branch에 쓸 수 있습니다. 매개변수는 리소스 명령마다 약간씩 다릅니다. 사용하기 전에 해당 명령 도움말과 JSON Schema를 확인하십시오.

리소스 유형	일반 명령	예시
HTTP API 엔드포인트	`endpoint create`, `endpoint update`	`apidog endpoint create --project <projectId> --branch <aiBranchName> --file ./endpoint.json`
데이터 모델	`schema create`, `schema update`	`apidog schema update <schemaId> --project <projectId> --branch <aiBranchName> --file ./schema.json`
Markdown 문서	`doc create`, `doc update`	`apidog doc create --project <projectId> --branch <aiBranchName> --file ./doc.json`
테스트 시나리오	`test-scenario create`, `test-scenario update`	`apidog test-scenario update <scenarioId> --project <projectId> --branch <aiBranchName> --file ./scenario.json`
테스트 스위트	`test-suite create`, `test-suite update`	`apidog test-suite create --project <projectId> --branch <aiBranchName> --file ./suite.json`
테스트 데이터	`test-data create`, `test-data update`	`apidog test-data create --project <projectId> --branch <aiBranchName> --file ./test-data.json`

복잡한 리소스를 생성하거나 업데이트할 때는 먼저 cli-schema를 사용하여 데이터 구조를 확인하고 검증하는 것을 권장합니다.

소스 브랜치에서 리소스 가져오기

AI Branch가 기존 리소스를 수정해야 하는 경우, 먼저 branch pick-to를 사용하여 소스 브랜치의 리소스를 AI Branch로 가져오십시오. 가져온 후 AI는 AI Branch에서 해당 리소스를 계속 편집할 수 있습니다.

명령	설명	예시
`branch pick-to`	소스 브랜치의 리소스를 대상 AI Branch로 가져옵니다.	`apidog branch pick-to --project <projectId> --from <sourceBranchName> --to <aiBranchName> --endpoint-ids <ids>`

예시: 엔드포인트를 가져와 AI가 수정하도록 하기

TIP

pick-to는 명령에서 명시적으로 지정한 리소스만 가져옵니다. 디렉터리, 데이터 모델, 응답 컴포넌트 또는 기타 관련 리소스가 필요한 경우 가져오기 전에 리소스 범위를 확인하십시오.

AI Branch 변경 사항 보기

병합하기 전에 AI Branch와 대상 브랜치 간의 후보 변경 사항을 미리 보는 것을 권장합니다. CLI는 merge-request preview를 사용하여 현재 지원되는 리소스 유형을 스캔할 수 있습니다. 클라이언트에서 더 완전한 브랜치 차이를 확인할 수도 있습니다.

명령	설명	예시
`merge-request preview`	병합 전에 리소스 범위를 확인하기 위해 후보 변경 사항을 스캔합니다.	`apidog merge-request preview --project <projectId> --from <aiBranchName> --to <targetBranchName>`
`branch get --type ai`	기본 AI Branch 정보를 확인합니다.	`apidog branch get <aiBranchName> --project <projectId> --type ai`

예시: 병합 전 후보 변경 사항 미리 보기

TIP

merge-request preview는 현재 CLI가 지원하는 리소스 유형에 대한 후보 차이를 스캔합니다. 이는 완전한 리소스 차이 비교가 아닙니다. 최종 병합 전에 중요한 리소스 내용은 클라이언트에서 확인하는 것을 여전히 권장합니다.

AI Branch 병합

AI Branch 변경 사항이 완료되면 해당 변경 사항을 소스 브랜치 또는 다른 대상 브랜치로 다시 병합할 수 있습니다. 보호되지 않은 대상 브랜치의 경우 branch merge를 사용하여 직접 병합하십시오. 보호된 메인 브랜치의 경우 merge-request create를 사용하여 병합 요청을 생성하고 검토 프로세스를 진행하십시오.

명령	설명	예시
`branch merge`	지정된 리소스를 AI Branch에서 직접 병합합니다.	`apidog branch merge --project <projectId> --from <aiBranchName> --to <targetBranchName> --endpoint-ids <ids>`
`merge-request create`	병합 요청을 생성합니다.	`apidog merge-request create --project <projectId> --from <aiBranchName> --to <targetBranchName> --reviewer-ids <userIds> --endpoint-ids <ids>`
`merge-request approve`	병합 요청을 승인합니다.	`apidog merge-request approve <mergeRequestId> --project <projectId> --to <targetBranchName> --file ./approve.json`
`merge-request reject`	병합 요청을 거부합니다.	`apidog merge-request reject <mergeRequestId> --project <projectId> --to <targetBranchName>`

예시: 엔드포인트 변경 사항 직접 병합

예시: 병합 요청 생성

TIP

직접 병합과 병합 요청은 모두 명시적으로 제공된 리소스 목록만 병합합니다. 참조된 리소스 또는 디렉터리 리소스를 자동으로 포함하지 않습니다. 병합 범위를 정의할 때 엔드포인트, 디렉터리, 데이터 모델, 응답 컴포넌트 및 테스트 리소스 간의 종속성을 확인하십시오.

AI Branch 보관 및 삭제

AI Branch가 병합되었거나 더 이상 필요하지 않은 경우, 먼저 보관한 다음 삭제할 수 있습니다. 삭제하기 전에 브랜치의 변경 사항이 병합되었거나 더 이상 필요하지 않은지 확인하십시오.

명령	설명	예시
`branch archive --type ai`	AI Branch를 보관합니다.	`apidog branch archive <aiBranchName> --project <projectId> --type ai`
`branch delete --type ai`	보관된 AI Branch를 삭제합니다.	`apidog branch delete <aiBranchName> --project <projectId> --type ai`

외부 AI 편집 권한

기본적으로 CLI는 AI Branch를 통해 프로젝트 리소스를 쓰는 것을 권장합니다. 이렇게 하면 AI가 생성한 변경 사항이 먼저 격리된 브랜치로 들어가고, 사용자 확인 후에만 병합될 수 있습니다.

외부 AI 또는 CLI 작업이 메인 브랜치, 표준 스프린트 브랜치 또는 일반 브랜치를 직접 편집하도록 하려면 클라이언트에서 해당 권한을 활성화하십시오.

Project Settings - Feature Settings - AI Feature Settings - External AI Edit Permissions

이 스위치들은 프로젝트 브랜치 전반에서 외부 AI, CLI 또는 자동화 호출의 직접 쓰기 범위를 제어합니다. 활성화하기 전에 팀의 협업 규칙과 프로젝트 데이터 보안 요구 사항을 확인하십시오.

권한	설명
메인 브랜치 직접 편집 권한	외부 AI 또는 CLI 작업이 메인 브랜치에 직접 쓸 수 있도록 허용합니다.
표준 스프린트 브랜치 직접 편집 권한	외부 AI 또는 CLI 작업이 표준 스프린트 브랜치에 직접 쓸 수 있도록 허용합니다.
일반 브랜치 직접 편집 권한	외부 AI 또는 CLI 작업이 일반 브랜치에 직접 쓸 수 있도록 허용합니다.
AI Branch 직접 편집 권한	외부 AI 또는 CLI 작업이 AI가 생성하고 유지 관리하는 AI Branch에 쓸 수 있도록 허용합니다. 일반적으로 이 권한은 활성화된 상태로 유지됩니다.

TIP

프로젝트 리소스를 보호하기 위해 외부 AI 또는 CLI 작업이 먼저 AI Branch에 쓰고, 사용자 확인 후에만 병합하도록 하는 것을 권장합니다. 자동화 워크플로가 대상 브랜치를 직접 수정해야 하는 명확한 필요가 있는 경우에만 직접 편집 권한을 활성화하십시오.

모범 사례

작업당 하나의 AI Branch 생성: 각 AI Branch는 사용자 등록 API 완료, 주문 모듈 문서 정리, 결제 테스트 시나리오 생성 등 명확한 작업에 대응해야 합니다.

편집 전에 가져오기: 기존 리소스를 수정할 때는 소스에 대한 혼동을 방지하기 위해 pick-to를 사용하여 먼저 가져온 다음 AI Branch에서 업데이트하십시오.

병합 전에 차이 미리 보기: merge-request preview 또는 클라이언트의 차이 보기 기능을 사용하여 리소스 내용과 종속성을 확인하십시오.

병합 범위 명시적 선택: 병합 명령은 제공된 리소스 목록만 처리합니다. API 디렉터리, 데이터 모델, 응답 컴포넌트 및 테스트 케이스와 같은 관련 리소스는 함께 확인하십시오.

사람의 검토 유지: AI가 생성한 API 정의, 테스트 스크립트 및 데이터 모델은 병합 전에 프로젝트 멤버가 검토해야 합니다.

브랜치 즉시 보관: 병합되었거나 폐기된 AI Branch는 브랜치 목록을 명확하게 유지하기 위해 즉시 보관해야 합니다.

FAQ

AI Branch와 표준 스프린트 브랜치의 차이점은 무엇입니까?

AI Branch는 주로 외부 AI, CLI 작업 또는 자동화 스크립트의 쓰기 결과를 저장하는 데 사용되는 특수 스프린트 브랜치입니다. 소스 브랜치를 기록하고, 병합 전에 사용자가 차이를 확인하도록 권장합니다. 표준 스프린트 브랜치는 일반적으로 팀 멤버 간의 일상적인 협업에 사용됩니다.

AI Branch가 메인 브랜치에 직접 영향을 줍니까?

아니요. AI Branch의 변경 사항은 먼저 해당 AI Branch에 저장됩니다. 관련 리소스는 사용자가 직접 병합을 수행하거나 병합 요청을 생성하고 승인한 후에만 대상 브랜치에 반영됩니다.

CLI가 AI Branch를 건너뛰고 프로젝트 데이터를 직접 편집하려면 어떻게 해야 합니까?

Apidog 프로젝트에서 Project Settings - Feature Settings - AI Feature Settings - External AI Edit Permissions로 이동한 다음, 필요에 따라 메인 브랜치, 표준 스프린트 브랜치 또는 일반 브랜치에 대한 직접 편집 권한을 활성화하십시오. 이러한 권한이 활성화되면 외부 AI 또는 CLI 작업이 해당 브랜치 범위 내에서 직접 쓸 수 있습니다.

AI Branch를 병합할 때 참조된 리소스가 자동으로 포함됩니까?

아니요. branch merge와 merge-request create는 모두 명시적으로 제공된 리소스 목록에 따라 실행됩니다. 엔드포인트가 데이터 모델, 응답 컴포넌트, 디렉터리 또는 테스트 리소스를 참조하는 경우, 병합 전에 해당 리소스 범위를 확인하고 추가하십시오.

변경이 완료된 후 AI Branch를 반드시 삭제해야 합니까?

아니요. 삭제는 필수가 아닙니다. 변경 사항이 병합되었거나 더 이상 필요하지 않음을 확인한 후 브랜치를 보관하고, 기록 브랜치가 장기간 누적되는 것을 방지하기 위해 팀의 규칙에 따라 삭제 여부를 결정하는 것을 권장합니다.

AI Branch가 필요한 이유#

AI Branch란 무엇입니까?#

사용 사례#

기본 워크플로#

AI Branch 생성#

AI Branch에서 리소스 편집#

소스 브랜치에서 리소스 가져오기#

AI Branch 변경 사항 보기#

AI Branch 병합#

AI Branch 보관 및 삭제#

외부 AI 편집 권한#

모범 사례#

FAQ#