AI 브랜치: AI 에이전트로 프로젝트 변경을 더 안전하게

이 문서는 API 테스트 및 API 수명 주기 관리를 위한 커맨드라인 도구인 Apidog CLI를 Apidog가 어떻게 개발했는지 공유하는 10부작 시리즈입니다. 순서대로 읽으시거나 관심 있는 게시물로 바로 이동하세요:

에이전트가 프로젝트 리소스를 수정할 때, 안전과 검토 가능성이 중요합니다. AI 브랜치는 격리된 편집 환경을 제공하며—변경 사항은 사람의 확인 후에만 대상 브랜치로 들어갑니다.

보안 과제

AI 에이전트가 API 개발 및 테스트에 참여할 때, CLI 명령을 통해 프로젝트 리소스를 생성, 업데이트, 삭제할 수 있습니다.

이러한 권한에는 위험이 따릅니다.

메인 브랜치를 위험에 빠뜨리지 않고 에이전트가 실제 프로젝트에서 작업하게 하려면 어떻게 해야 할까요?

AI 브랜치: 안전 계층

AI 브랜치는 외부 AI 및 CLI 작업을 위해 특별히 설계된 스프린트 브랜치의 특별한 유형입니다.

핵심 개념:

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

AI 브랜치는 AI 에이전트에게 격리된 편집 브랜치를 제공합니다. 변경 사항은 사람이 검토하고 병합할 때까지 AI 브랜치에 남아 있습니다.

에이전트가 CLI를 통해 변경 사항을 만듭니다
        ↓
변경 사항이 AI 브랜치에 저장됩니다 (격리됨)
        ↓
사용자가 차이점을 검토합니다
        ↓
사용자가 리소스 범위를 확인합니다
        ↓
대상 브랜치로 병합합니다 (직접 또는 병합 요청)

승인할 때까지 메인 브랜치는 그대로 유지됩니다.

AI 브랜치가 필요한 이유

AI가 시작하는 편집은 예측할 수 없습니다. Apidog CLI는 엔드포인트, 스키마, 테스트 시나리오, 테스트 스위트 등 광범위한 편집 기능을 제공합니다.

AI 브랜치는 이러한 고위험 AI 시작 편집 작업을 위해 설계되었습니다.

이를 통해 AI 에이전트가 제어된 범위 내에서 프로젝트 리소스를 편집할 수 있습니다:

AI 브랜치란?

AI 브랜치는 특정 특징을 가진 특별한 스프린트 브랜치입니다:

주요 특징

작동 방식

사용자에 의한 일반적인 클라이언트 내 편집은 여전히 프로젝트 멤버 권한 및 브랜치 보호 규칙을 따릅니다.

사용 사례

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

기본 워크플로우

일반적인 AI 브랜치 워크플로우:

┌─────────────────────────────────────────────────────────────────┐
│                     AI 브랜치 워크플로우                           │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  단계 1: AI 브랜치 생성                                            │
│  ┌───────────────────────────────────────────┐                  │
│  │ apidog branch create --type ai             │                  │
│  │ --name "ai/20260312-from-main-feature"     │                  │
│  │ --from main                                │                  │
│  └───────────────────────────────────────────┘                  │
│                    ↓                                             │
│  단계 2: 리소스 가져오기 또는 생성                                   │
│  ┌───────────────────────────────────────────┐                  │
│  │ apidog branch pick-to (기존 가져오기)          │                  │
│  │ 또는                                         │                  │
│  │ apidog endpoint create (새로 생성)           │                  │
│  └───────────────────────────────────────────┘                  │
│                    ↓                                             │
│  단계 3: AI가 리소스를 수정합니다                                  │
│  ┌───────────────────────────────────────────┐                  │
│  │ 에이전트가 CLI를 사용하여 엔드포인트,           │                  │
│  │ 스키마, 테스트 시나리오 등을 업데이트합니다.       │                  │
│  │ (--branch 매개변수는 AI 브랜치를 지정합니다)    │                  │
│  └───────────────────────────────────────────┘                  │
│                    ↓                                             │
│  단계 4: 사용자가 차이점을 검토합니다                              │
│  ┌───────────────────────────────────────────┐                  │
│  │ apidog merge-request preview              │                  │
│  │ 또는                                         │                  │
│  │ Apidog 클라이언트에서 보기                      │                  │
│  └───────────────────────────────────────────┘                  │
│                    ↓                                             │
│  단계 5: 대상 브랜치로 병합합니다                                  │
│  ┌───────────────────────────────────────────┐                  │
│  │ 직접 병합 (보호되지 않은 브랜치)            │                  │
│  │ 또는                                         │                  │
│  │ 병합 요청 (보호된 브랜치)                 │                  │
│  └───────────────────────────────────────────┘                  │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

AI 브랜치 생성

branch create --type ai 사용:

apidog branch create \
  --project 123456 \
  --type ai \
  --name "ai/20260312-from-main-userRegister" \
  --from main

이름 추천: ai/YYYYMMDD-from-sourceBranch-featureOrModule

AI 브랜치에서 리소스 편집

CLI가 프로젝트 리소스를 작성할 때, --branch 매개변수를 사용하여 AI 브랜치에 작성합니다:

권장 워크플로우:

# 1. 스키마 가져오기
apidog cli-schema get endpoint-create

# 2. 작성하기 전에 유효성 검사
apidog cli-schema validate endpoint-create --file ./endpoint.json

# 3. AI 브랜치에 작성 (메인이 아님)
apidog endpoint create \
  --project 123456 \
  --branch "ai/20260312-from-main-userRegister" \
  --file ./endpoint.json

기존 리소스 가져오기

기존 리소스를 수정하려면 먼저 소스 브랜치에서 가져옵니다:

apidog branch pick-to \
  --project 123456 \
  --from main \
  --to "ai/20260312-from-main-userRegister" \
  --endpoint-ids 1001,1002

이렇게 하면 AI가 올바른 기본 버전으로 작업할 수 있습니다.

병합 전 변경 사항 검토

병합하기 전에 차이점을 미리 봅니다:

apidog merge-request preview \
  --project 123456 \
  --from "ai/20260312-from-main-userRegister" \
  --to main

또는 Apidog 클라이언트에서 전체 차이점을 봅니다.

AI 브랜치 병합

검토 후 변경 사항을 병합합니다:

직접 병합 (보호되지 않은 브랜치)

apidog branch merge \
  --project 123456 \
  --from "ai/20260312-from-main-userRegister" \
  --to main \
  --endpoint-ids 1001,1002

병합 요청 (보호된 브랜치)

apidog merge-request create \
  --project 123456 \
  --from "ai/20260312-from-main-userRegister" \
  --to main \
  --reviewer-ids 20001,20002 \
  --endpoint-ids 1001,1002

중요: 병합 명령어는 명시적으로 제공된 리소스 목록만 처리합니다. 병합하기 전에 종속성(디렉토리, 모델, 응답 구성 요소, 테스트)을 확인하세요.

아카이빙 및 삭제

변경 사항이 병합되었거나 더 이상 필요하지 않은 경우:

# 아카이브
apidog branch archive "ai/20260312-from-main-userRegister" \
  --project 123456 --type ai

# 삭제 (아카이빙 후)
apidog branch delete "ai/20260312-from-main-userRegister" \
  --project 123456 --type ai

외부 AI 편집 권한

기본적으로 CLI는 AI 브랜치에 작성합니다. 이렇게 하면 AI가 생성한 변경 사항이 사용자 확인 전까지 격리됩니다.

메인 브랜치의 직접 편집을 활성화하려면:

프로젝트 설정 → 기능 설정 → AI 기능 설정 → 외부 AI 편집 권한

권장 사항: AI 브랜치 격리를 활성화된 상태로 유지하세요. 자동화 워크플로우에 명확히 필요한 경우에만 직접 편집을 활성화하세요.

모범 사례

CLI + SKILL 워크플로우의 AI 브랜치

AI 브랜치는 CLI + SKILL과 자연스럽게 통합됩니다:

모든 작성은 AI 브랜치 → 사람의 검토 → 병합을 거칩니다.

보안 요약

이러한 계층들은 함께 에이전트 주도 프로젝트 변경을 위한 더 안전한 루프를 만듭니다.

다음 단계

AI 브랜치가 안전 계층을 제공함으로써 모든 부분이 제자리에 있습니다:

• 도구 연결을 위한 MCP (1부)
• 워크플로우 실행을 위한 CLI + SKILL (2-5부)
• 유효성 검사 결과 (6부)
• 실용적인 워크플로우 (7부)
• CI/CD 기반 (8부)
• 안전을 위한 AI 브랜치 (9부)

이제 비전을 위한 시간입니다.

10부, Spec-First는 어제였습니다. Skill-First에 오신 것을 환영합니다.에서는 AI 에이전트와 함께 API 개발이 어떻게 진화하는지—그리고 팀이 다음에 무엇을 해야 하는지 설명할 것입니다.

핵심 요점

• AI 브랜치는 AI/CLI 작업을 위한 격리된 편집을 제공합니다
• 변경 사항은 사람의 확인 전까지 메인 브랜치에 영향을 주지 않습니다
• branch create --type ai로 생성하고, --branch 매개변수로 작성합니다
• 편집하기 전에 branch pick-to로 기존 리소스를 가져옵니다
• merge-request preview로 미리 본 다음, 병합하거나 병합 요청을 생성합니다
• 직접 편집 권한은 AI 브랜치를 우회할 수 있으므로—주의하여 사용하세요
• 모범 사례: 작업당 하나의 AI 브랜치, 작성 전 유효성 검사, 병합 전 검토

하나의 워크스페이스에서 API를 설계, 모킹, 테스트, 문서화하려면 Apidog를 다운로드하세요. 커맨드라인 API 테스트, CI 자동화 및 AI 에이전트 워크플로우를 위한 Apidog CLI에 대해 자세히 알아보세요.