CI/CD 통합 및 배포 · AI 네이티브 SDLC 플레이북

CI/CD 파이프라인 내부에서 Claude Code를 비대화형으로 실행하고, 장시간 실행되는 에이전트가 안전하게 동작하도록 실행을 샌드박스화하며, MCP 통합을 통해 배포를 노출하고, 에이전트가 실제로 필요해지기 전에 롤백 경로를 미리 연습해 두세요.

무엇이 달라지는가

전통적 방식	AI 네이티브 방식
파이프라인은 결정론적 스크립트를 실행하며, 판단이 필요한 모든 것은 사람을 기다립니다: 예를 들어 불안정한 테스트를 분류하거나, 변경 로그를 작성하거나, 빌드가 왜 깨졌는지 파악하는 일입니다. 배포와 롤백은 사람이 압박 속에서 따르는 런북입니다.	Claude는 판단이 필요한 단계에서 파이프라인 내부에서 비대화형으로 실행되며, 범위가 제한된 자격 증명을 가진 샌드박스 안에서 동작합니다. 배포 도구는 MCP를 통해 에이전트에 노출되므로, 변경 사항을 작성하고 테스트한 워크플로가 그것을 배포하고 롤백할 수도 있으며, 이는 조직이 환경별로 정의한 게이트 안에서 이루어집니다.

전통적 방식

AI 네이티브 방식

파이프라인은 결정론적 스크립트를 실행하며, 판단이 필요한 모든 것은 사람을 기다립니다: 예를 들어 불안정한 테스트를 분류하거나, 변경 로그를 작성하거나, 빌드가 왜 깨졌는지 파악하는 일입니다. 배포와 롤백은 사람이 압박 속에서 따르는 런북입니다.

Claude는 판단이 필요한 단계에서 파이프라인 내부에서 비대화형으로 실행되며, 범위가 제한된 자격 증명을 가진 샌드박스 안에서 동작합니다. 배포 도구는 MCP를 통해 에이전트에 노출되므로, 변경 사항을 작성하고 테스트한 워크플로가 그것을 배포하고 롤백할 수도 있으며, 이는 조직이 환경별로 정의한 게이트 안에서 이루어집니다.

시작하기

전제 조건: PR 리뷰 루프에서의 AI와 승인 게이트로서의 훅. 자동화가 게이트를 통해 무언가를 가속하기 전에 게이트가 먼저 존재해야 하기 때문입니다.
인프라: claude-code-action이 설치된 CI 플랫폼, 또는 claude -p를 호출할 수 있는 모든 러너; API를 통한 모델 접근, 또는 트래픽이 조직의 클라우드 계약 내에 머물러야 하는 경우 Amazon Bedrock, Microsoft Foundry, Vertex AI; 배포 대상을 위한 MCP 서버; 상시 프로덕션 자격 증명이 없는 에이전트 작업용 샌드박스 프로필.

실행 방법

플랫폼 엔지니어는 읽기 전용 판단 단계부터 시작합니다. 파이프라인 작업에서 claude -p를 사용해 실패한 빌드를 분류하거나, 불안정한 테스트를 요약하거나, 변경 로그를 작성합니다.
린트 수정, 생성된 문서 업데이트, @claude 멘션을 통한 리뷰 댓글 처리 같은 작업에 대해 기존 게이트 뒤에 쓰기 단계를 추가합니다. 에이전트가 작성하는 모든 것은 브랜치 보호를 통해 PR로 도착하며, 에이전트는 main에 직접 푸시할 경로가 없습니다.
실행은 샌드박스화됩니다. 에이전트 작업은 네트워크 정책 아래 컨테이너에서 단기 범위 토큰으로 실행되며, 기본적으로 프로덕션 자격 증명을 보유하지 않습니다.
MCP를 통해 배포를 노출합니다. 배포, 상태, 롤백이 환경별로 범위가 지정된 도구가 되므로, 에이전트의 배포 권한은 자격 증명이 있는 셸 스크립트가 아니라 허용 목록이 됩니다.
환경별로 자율성을 단계화합니다. 개발 환경에서는 에이전트가 자유롭게 배포합니다. 프로덕션에서는 에이전트가 릴리스를 준비하고 릴리스 관리자가 이를 승인하며, 훅이 프로덕션 게이트를 강제합니다. 스테이징은 그 중간 어딘가에 위치합니다.
롤백은 파이프라인에서 가장 많이 연습된 경로여야 하며, 에이전트가 실행할 수 있고 스테이징에서 정기적으로 연습되는 단일 명령이어야 합니다. 루프 닫기 플레이(6단계: 유지)는 제어 범위가 벗어났을 때 이 롤백을 호출하므로, 사전에 검증되어 있어야 합니다.

실제 모습

파이프라인 단계:

yaml

- name: Triage failed build
  if: failure()
  run: >
    claude -p "Read the build log at out/build.log. Identify the most
    likely cause, say whether the failure looks flaky or real, and write a
    three-line summary for the PR thread." >> triage.md

이 예시의 나머지 부분은 보험사의 고객 포털로, 배포가 도구로 노출되고 환경마다 하나의 MCP 서버가 있습니다. MCP 도구를 허용하는 규칙은 도구의 인자가 아니라 서버와 도구의 이름을 지정합니다. 따라서 환경별로 별도의 서버를 두는 것이 허용 목록이 스테이징과 프로덕션을 구분할 수 있게 해주는 방법입니다. 서버는 프로젝트의 .mcp.json에 설정됩니다:

json

{
  "mcpServers": {
    "deploy-dev": {
      "type": "http",
      "url": "https://deploy.example.com/mcp/dev",
      "headers": { "Authorization": "Bearer ${DEPLOY_DEV_TOKEN}" }
    },
    "deploy-staging": {
      "type": "http",
      "url": "https://deploy.example.com/mcp/staging",
      "headers": { "Authorization": "Bearer ${DEPLOY_STAGING_TOKEN}" }
    },
    "deploy-prod": {
      "type": "http",
      "url": "https://deploy.example.com/mcp/prod",
      "headers": { "Authorization": "Bearer ${DEPLOY_PROD_TOKEN}" }
    }
  }
}

모든 서버는 동일한 세 가지 도구를 제공합니다:

도구	입력	반환값
`release`	`version`, 그리고 프로덕션에서는 `ticket`	롤아웃이 완료되면 릴리스 ID
`status`	없음	마지막 릴리스 후 5분이 지날 때까지 대기한 다음, 그 시간 동안의 각 엔드포인트의 5xx 비율을 반환
`rollback`	없음	다시 라이브로 전환된 버전

스테이징 작업은 main에 대한 푸시에서 실행되며 스테이징 서버의 세 가지 도구만 사전 승인하고 다른 것은 승인하지 않습니다. 스테이징 토큰만 보유하므로, 다른 두 서버는 유효한 토큰을 받지 못해 작업을 거부합니다. 다음은 스테이징 작업의 파이프라인 단계입니다:

yaml

- name: Release to staging and roll back if it is unhealthy
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
    DEPLOY_STAGING_TOKEN: ${{ secrets.DEPLOY_STAGING_TOKEN }}   # no other environment's token
  run: >
    claude -p "Release version ${{ github.sha }} of the claims portal to staging,
    then call status. If the 5xx rate on any endpoint is over 1%, roll back.
    Finish with three lines for the release notes: what you released, what status
    reported, and whether you rolled back."
    --allowedTools "mcp__deploy-staging__release,mcp__deploy-staging__status,mcp__deploy-staging__rollback"
    --permission-mode dontAsk >> release-notes.md

dontAsk 모드에서는 Claude Code가 원래 프롬프트를 표시했을 호출을 모두 거부하므로, 목록에 없는 배포 도구는 거부되고 작업은 답변을 기다리지 않습니다.

release 도구에 대한 하나의 PreToolUse 훅이 환경별로 결정을 내립니다. 이는 승인 게이트로서의 훅 플레이에 기술되어 있으며, 세 가지 단계를 제공합니다:

환경	허용 목록의 도구	`release`에 일어나는 일	승인자
개발	`release`, `status`, `rollback`	훅이 허용함	없음
스테이징	`release`, `status`, `rollback`	훅이 물어보거나, `main`에서의 파이프라인에서 허용함	엔지니어, 또는 승인된 머지
프로덕션	`status`, `rollback`	훅이 허용하지 않는 한 거부됨	변경 티켓을 통한 릴리스 관리자

프로덕션에서는 dontAsk 모드에서도 PreToolUse 훅이 승인하는 호출은 여전히 실행되므로, release가 허용 목록에서 빠져 있으면 훅의 allow만이 유일한 통과 경로입니다. 따라서 프로덕션은 실패 시 닫히는 방식(fail closed)을 취하는데, 훅이 실행되지 않으면 릴리스가 거부되기 때문입니다. rollback은 사전에 승인된 런북이기 때문에 허용 목록에 남아 있습니다.

러너가 allowManagedHooksOnly가 설정된 관리형 설정을 가지고 있다면 훅은 관리형 설정에 정의되어 있어야 하며, allowManagedMcpServersOnly가 설정되어 있다면 서버는 관리형 허용 목록에 있어야 합니다.

거버넌스 고려 사항

지배 원칙은 에이전트가 프로덕션 게이트까지는 행동할 수 있지만 그것을 통과할 수는 없다는 것입니다. 아래의 통제 장치들이 이 원칙을 강제합니다.

브랜치 보호는 에이전트가 작성하는 모든 것을 PR로 전환하며, main으로의 직접 경로는 없습니다.
프로덕션 배포 훅은 지정된 릴리스 관리자가 승인할 때까지 릴리스를 차단합니다. 각 비대화형 실행은 에이전트 자신의 신원으로 동작하므로, 파이프라인 로그는 에이전트가 한 일과 이를 트리거한 엔지니어가 한 일을 구분합니다.
환경별 권한 단계는 게이트에 도달하기까지 에이전트가 할 수 있는 범위를 설정합니다.

측정 방법

선행 지표: CI/CD 파이프라인 로그에서 가져온, 사람을 호출하지 않고 분류된 파이프라인 실패의 비율.
후행 지표: CI 시스템과 배포 도구가 이미 산출하는 DevOps Research and Assessment(DORA) 지표.

무엇이 달라지는가

시작하기

실행 방법

실제 모습

거버넌스 고려 사항