Claude Code 헤드리스 모드와 CI/CD 완전정리: 자동화 파이프라인에 AI를 넣는 법

Claude Code 헤드리스 모드와 CI/CD 완전정리: 자동화 파이프라인에 AI를 넣는 법

PR이 올라오면 AI가 자동으로 코드 리뷰, 이슈에 @claude를 멘션하면 자동으로 구현, 매일 아침 코드베이스 보안 점검 — 이 모든 게 Claude Code의 헤드리스 모드와 CI/CD 연동으로 가능합니다. 이 글에서는 비대화형 모드부터 GitHub Actions 연동까지 완전 정리합니다.

Claude Code 헤드리스 모드와 CI/CD 완전정리

---

1. 헤드리스 모드란?

대화 없이 실행하는 Claude Code

헤드리스 모드(-p 플래그)는 Claude Code를 비대화형으로 실행합니다. 프롬프트를 받고, 작업을 수행하고, 결과를 stdout으로 출력한 뒤 종료합니다. 스크립트나 CI/CD 파이프라인에서 사용하기 위한 핵심 기능입니다.

# 기본 사용법
claude -p "src/auth.ts에서 보안 취약점 찾아줘"

# 파이프로 입력
cat error.log | claude -p "이 에러 로그를 요약해줘"

# git diff 분석
git diff HEAD~1 | claude -p "이 변경사항을 리뷰해줘"

대화형 vs 헤드리스

항목	대화형 (기본)	헤드리스 (-p)
UI	터미널 UI	없음 (stdout만)
종료	사용자가 직접	자동 종료
권한 확인	매번 물어봄	플래그로 제어
스크립트 사용	불가	가능
CI/CD	불가	핵심 모드
출력 캡처	어려움	쉬움 (stdout)

헤드리스 모드란?

---

2. 핵심 CLI 플래그

실행 제어

플래그	용도	예시
-p, --print	헤드리스 모드 실행	claude -p "분석해줘"
--output-format	출력 형식 (text/json/stream-json)	claude -p "질문" --output-format json
--max-turns	에이전트 반복 제한	claude -p "질문" --max-turns 5
--model	모델 선택	claude -p --model opus "질문"
--max-budget-usd	비용 상한선	claude -p --max-budget-usd 5.00 "질문"

도구 제어

플래그	용도	예시
--allowedTools	특정 도구 자동 승인	--allowedTools "Read,Edit,Bash"
--disallowedTools	특정 도구 차단	--disallowedTools "Bash(rm *)"
--permission-mode	권한 모드 설정	--permission-mode acceptEdits

시스템 프롬프트

플래그	용도
--append-system-prompt	기본 프롬프트에 추가 (권장)
--system-prompt	기본 프롬프트 완전 교체
--system-prompt-file	파일에서 프롬프트 로드

세션 관리

# 이전 대화 이어가기
claude -p "다음 단계 진행해줘" --continue

# 특정 세션 재개
claude -p "계속해줘" --resume "session-id"

 

핵심 CLI 플래그

---

3. 출력 형식 — text, json, stream-json

text (기본값)

claude -p "이 프로젝트를 요약해줘"
# → 평문 텍스트 출력

json — 구조화된 출력

claude -p "함수 목록 추출해줘" --output-format json

{
  "result": "분석 결과...",
  "session_id": "abc-123",
  "usage": {
    "input_tokens": 1234,
    "output_tokens": 567
  }
}

# jq로 특정 필드만 추출
claude -p "분석해줘" --output-format json | jq -r '.result'

stream-json — 실시간 스트리밍

claude -p "설명해줘" \
  --output-format stream-json \
  --verbose \
  --include-partial-messages

JSON 스키마로 출력 검증

claude -p "auth.py에서 함수명 추출해줘" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}}}'

--json-schema를 사용하면 Claude가 스키마에 맞는 구조화된 데이터를 보장합니다.

출력 형식 — text, json, stream-json

---

4. 파이프라인 활용 예제

Unix 파이프와의 통합

Claude Code는 표준 Unix CLI 도구처럼 파이프에서 동작합니다.

# 파일 분석
cat auth.py | claude -p "보안 취약점 찾아줘"

# git diff 리뷰
git diff HEAD~1 | claude -p "이 변경사항 리뷰해줘"

# 에러 로그 분석
cat error.log | claude -p "핵심 에러 요약해줘"

# 빌드 에러 설명
cat build-error.txt | claude -p "원인 설명해줘"

출력 저장

# README 생성
claude -p "이 프로젝트의 README 만들어줘" > README.md

# 리뷰 결과를 JSON으로 저장
git diff | claude -p "버그 찾아줘" --output-format json | jq '.result' > review.md

스크립트 자동화

#!/bin/bash
# auto-review.sh — PR 자동 리뷰 스크립트

PR_NUMBER=$1
REVIEW=$(gh pr diff "$PR_NUMBER" | \
  claude -p "이 PR을 리뷰하고 개선점을 알려줘" \
  --output-format json \
  --max-turns 5 | \
  jq -r '.result')

echo "$REVIEW"

#!/bin/bash
# security-scan.sh — 보안 스캔 스크립트

claude -p "package.json의 보안 취약점 분석하고 해결책 제시해줘" \
  --allowedTools "Read,Bash(npm audit *)" \
  --max-turns 3 \
  --output-format json

파이프라인 활용 예제

---

5. GitHub Actions 연동

공식 액션 설치

# Claude Code 안에서 한 번에 설치
claude
/install-github-app

이 명령으로 Claude GitHub App 설치, API 시크릿 생성, 워크플로우 설정이 자동으로 진행됩니다.

기본 워크플로우

# .github/workflows/claude.yml
name: Claude Code
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]

jobs:
  claude:
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

이 설정만으로 이슈나 PR 코멘트에서 @claude를 멘션하면 Claude가 자동 응답합니다.

PR 자동 리뷰 워크플로우

name: Auto Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: "/review"
          claude_args: "--max-turns 5"

스케줄 기반 자동화

name: Daily Security Scan
on:
  schedule:
    - cron: "0 9 * * *"

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: "보안 취약점 전체 스캔하고 리포트 생성해줘"
          claude_args: "--model opus --max-turns 3"

GitHub Actions 연동

---

6. GitLab CI/CD 연동

기본 설정

stages:
  - ai

claude-review:
  stage: ai
  image: node:24-alpine3.21
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
  before_script:
    - apk add --no-cache git curl bash
    - curl -fsSL https://claude.ai/install.sh | bash
  script:
    - claude -p "이 MR을 리뷰하고 개선점을 제시해줘" \
      --permission-mode acceptEdits \
      --allowedTools "Read,Bash(git diff *)" \
      --max-turns 5
  variables:
    ANTHROPIC_API_KEY: $ANTHROPIC_API_KEY

AWS Bedrock 연동

claude-bedrock:
  stage: ai
  image: node:24-alpine3.21
  before_script:
    - apk add --no-cache bash curl git python3 py3-pip
    - pip install awscli
    - curl -fsSL https://claude.ai/install.sh | bash
  script:
    - claude -p "코드 리뷰해줘" \
      --permission-mode acceptEdits
  variables:
    CLAUDE_CODE_USE_BEDROCK: "1"
    AWS_REGION: "us-west-2"

GitHub Actions 연동

---

7. 클라우드 프로바이더 연동

API 키 vs 클라우드 프로바이더

방식	설정	장점
API 키	ANTHROPIC_API_KEY	간단, 범용
AWS Bedrock	CLAUDE_CODE_USE_BEDROCK=1	AWS 결제 통합, OIDC
Google Vertex	CLAUDE_CODE_USE_VERTEX=1	GCP 결제 통합, WIF

AWS Bedrock (GitHub Actions)

- uses: anthropics/claude-code-action@v1
  with:
    use_bedrock: "true"
    claude_args: '--model us.anthropic.claude-sonnet-4-6'
  env:
    AWS_ROLE_TO_ASSUME: ${{ secrets.AWS_ROLE_TO_ASSUME }}
    AWS_REGION: us-west-2

Google Vertex AI (GitHub Actions)

- uses: anthropics/claude-code-action@v1
  with:
    use_vertex: "true"
    claude_args: '--model claude-sonnet-4@20250514'
  env:
    ANTHROPIC_VERTEX_PROJECT_ID: ${{ secrets.GCP_PROJECT_ID }}
    CLOUD_ML_REGION: us-east5

클라우드 프로바이더 연동

---

8. 비용 관리와 보안

비용 최적화 전략

전략	방법	효과
턴 제한	--max-turns 3~5	불필요한 반복 방지
예산 상한	--max-budget-usd 10.00	비용 폭주 방지
모델 선택	Sonnet 사용 (Opus보다 저렴)	비용 절감
구체적 프롬프트	명확한 지시	토큰 절약
도구 제한	--allowedTools	불필요한 실행 방지

API 키 보안

# ✅ 올바른 방법: 환경 변수/시크릿 사용
export ANTHROPIC_API_KEY="sk-..."

# ✅ GitHub Actions 시크릿
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

# ❌ 잘못된 방법: 코드에 직접 입력
# 절대 하지 마세요!

권한 격리

# 읽기 전용 리뷰 (안전)
claude -p "PR 리뷰해줘" \
  --allowedTools "Read,Bash(git diff *)" \
  --disallowedTools "Bash(rm *),Bash(git push *)"

# 편집 허용 (주의)
claude -p "린트 에러 고쳐줘" \
  --permission-mode acceptEdits \
  --allowedTools "Read,Edit,Bash(npm run lint *)"

비용 관리와 보안

---

9. 실전 CI/CD 레시피

레시피 1: PR 자동 리뷰 + 코멘트

name: PR Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            이 PR의 변경사항을 리뷰해줘:
            - 버그 가능성
            - 성능 이슈
            - 보안 취약점
            - 코드 스타일
          claude_args: "--max-turns 5 --model sonnet"

레시피 2: 이슈 → 자동 구현

name: Auto Implement
on:
  issue_comment:
    types: [created]

jobs:
  implement:
    if: contains(github.event.comment.body, '@claude')
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

레시피 3: 매일 보안 스캔

#!/bin/bash
# daily-scan.sh
RESULT=$(claude -p "전체 코드베이스 보안 스캔 실행. 취약점을 심각도별로 정리해줘" \
  --output-format json \
  --max-turns 10 \
  --max-budget-usd 5.00 | jq -r '.result')

# Slack 알림 전송
curl -X POST "$SLACK_WEBHOOK" \
  -H 'Content-type: application/json' \
  -d "{\"text\": \"보안 스캔 결과:\\n$RESULT\"}"

레시피 4: 테스트 자동 생성

# 변경된 파일에 대한 테스트 자동 생성
git diff --name-only HEAD~1 | while read file; do
  claude -p "이 파일의 테스트를 생성해줘: $file" \
    --allowedTools "Read,Write" \
    --max-turns 3
done

실전 CI/CD 레시피

---

10. 자주 묻는 질문 (FAQ)

Q: 헤드리스 모드에서 권한 확인이 뜨면 어떻게 하나요?
A: --allowedTools로 필요한 도구를 미리 승인하거나, --permission-mode acceptEdits로 편집을 자동 승인하세요. CI/CD에서는 필수입니다.

Q: GitHub Actions에서 비용이 얼마나 드나요?
A: GitHub Actions 자체 비용 + Claude API 비용이 발생합니다. --max-turns와 --max-budget-usd로 비용을 제어하세요.

Q: 대용량 파일을 파이프로 넣으면?
A: 매우 큰 파일은 잘릴 수 있습니다. 파일을 직접 참조하는 것이 더 안정적입니다: claude -p "src/big-file.ts를 분석해줘"

Q: 여러 PR을 동시에 리뷰할 수 있나요?
A: 네, GitHub Actions 워크플로우가 PR마다 독립적으로 실행됩니다. 동시에 여러 PR을 처리할 수 있습니다.

Q: 오프라인에서도 헤드리스 모드가 작동하나요?
A: 아닙니다. Claude Code는 Claude API에 접속해야 하므로 인터넷 연결이 필수입니다.

Q: 자체 호스팅 러너에서도 사용 가능한가요?
A: 네, Node.js가 설치된 러너라면 curl -fsSL https://claude.ai/install.sh | bash로 설치 후 사용할 수 있습니다.

---

 

면책 조항: 이 글은 정보 제공 목적으로 작성되었습니다. Claude Code의 기능과 요금은 Anthropic의 정책에 따라 변경될 수 있으며, 최신 정보는 공식 문서를 확인해 주세요.