Ch11. 헤드리스 & CI/CD

헤드리스 모드는 Claude Code를 비대화형으로 실행하는 방식입니다. 스크립트와 CI/CD 파이프라인에 적합합니다.

기본 사용법

# 단순 실행 (-p 플래그)
claude -p "src/utils.ts에서 미사용 함수를 찾아줘"

# 도구 허용과 함께
claude -p "테스트를 실행하고 실패하는 것을 수정해줘" \
  --allowedTools "Read,Edit,Bash"

경량 실행 모드 (`--bare`)

--bare 플래그를 사용하면 hooks, LSP, 플러그인 동기화, 스킬 디렉토리 탐색을 모두 건너뛰고 실행합니다. 스크립트에서 -p 호출 시 최소한의 오버헤드로 실행하고 싶을 때 유용합니다. (v2.1.81)

# 경량 모드로 실행 (ANTHROPIC_API_KEY 또는 --settings의 apiKeyHelper 필요)
claude --bare -p "코드 분석해줘" --allowedTools "Read,Glob,Grep"

인증 요구사항

--bare 모드에서는 ANTHROPIC_API_KEY 환경변수 또는 --settings로 지정한 설정의 apiKeyHelper가 필요합니다.

PowerShell 도구 (프리뷰, v2.1.84+)

Windows 환경에서는 PowerShell 도구를 opt-in 프리뷰로 사용할 수 있습니다. 기존 Bash 대신 PowerShell 명령을 네이티브로 실행하며, /env로 설정한 환경변수도 적용됩니다 (v2.1.88).

{
  "env": {
    "CLAUDE_CODE_USE_POWERSHELL_TOOL": "1"
  }
}

공식 tools reference는 여전히 native Windows preview로 설명합니다.
GitHub changelog v2.1.111 기준으로는 Linux/macOS에서도 pwsh가 PATH에 있으면 같은 환경변수로 opt-in 가능합니다.
다만 Auto 모드와 샌드박스 지원은 아직 제한적이므로 운영 문서에는 preview 취급이 안전합니다.

v2.1.90에서는 trailing & 백그라운드 우회, -ErrorAction Break 디버거 hang, archive extraction TOCTOU 등 권한 검사 우회 가능성이 보강되었습니다.

입력/출력 형식

형식	용도
`text`	기본 텍스트 출력
`json`	구조화된 결과
`stream-json`	스트리밍 JSON

# JSON 출력
claude -p "분석해줘" --output-format json

# 스트리밍 JSON
claude -p "분석해줘" --output-format stream-json

v2.1.111부터는 plugins가 의존성 불일치로 demote된 경우 stream-json의 init 이벤트에 plugin_errors가 포함됩니다. 헤드리스 파이프라인에서 플러그인 상태를 조기에 감지하기 쉬워집니다.

세션 연속성

# 첫 실행 (세션 ID 포함 JSON)
RESULT=$(claude -p "1단계: 분석" --output-format json)
SESSION_ID=$(echo "$RESULT" | jq -r '.session_id')

# 이어서 실행
claude -p "2단계: 수정" --resume "$SESSION_ID"

시스템 프롬프트 확장

claude -p "분석해줘" \
  --append-system-prompt "보안 취약점에 집중하세요"

퍼미션 모드

# Plan 모드 (읽기 전용)
claude --permission-mode plan -p "아키텍처를 분석해줘"

주의

--dangerously-skip-permissions는 격리된 CI 환경에서만 사용하세요. 로컬 환경에서 사용하면 의도치 않은 파일 수정이 발생할 수 있습니다.

도구 허용/차단

# 읽기만 허용
--allowedTools "Read,Glob,Grep"

# 특정 도구 차단
--disallowedTools "Bash"

v2.1.111부터 읽기 전용 Bash 명령 중 ls *.ts 같은 glob 패턴이나 cd <project-dir> && ...로 시작하는 패턴은 권한 프롬프트를 덜 유발합니다. v2.1.113에서는 cd <current-directory> && git ...처럼 cd가 사실상 no-op인 경우도 추가로 정리되었습니다. CI에서 안전한 조회 명령을 자주 쓰는 팀이라면 불필요한 승인 노이즈가 줄어듭니다.

Linux 샌드박스 보강 (v2.1.92)

Linux 샌드박스는 npm 설치와 네이티브 설치 모두에 apply-seccomp helper를 포함하게 되어, 샌드박스된 명령의 unix socket 차단이 다시 일관되게 동작합니다. CI가 npm 배포본을 쓰는 경우 특히 업그레이드 가치가 큽니다.

MCP 설정 파일 지정

# MCP 설정 파일 지정
claude -p "이슈를 요약해줘" --mcp-config .mcp.json

GitHub Actions 통합 예시

name: Claude Code Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Claude Code
        run: curl -fsSL https://claude.ai/install.sh | bash -s stable
      - name: Review PR
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          gh pr diff ${{ github.event.pull_request.number }} | \
          claude -p "이 PR을 리뷰해줘" \
            --output-format json \
            --allowedTools "Read,Glob,Grep"

Remote Control

로컬 Claude Code 세션을 **다른 기기(폰/태블릿/브라우저)**에서 이어서 사용할 수 있습니다(v2.1.51). 실행은 로컬에서 유지되며, 원격 인터페이스는 로컬 세션의 창 역할만 합니다.

사용 가능 플랜

Pro, Max, Team, Enterprise 모든 플랜에서 사용 가능합니다. Team/Enterprise는 관리자가 먼저 Claude Code를 활성화해야 합니다.

시작 방법

# 새 세션으로 시작
claude remote-control --name "My Project"

# 기존 세션에서 활성화
/remote-control My Project
# 또는 줄여서
/rc My Project

터미널에 세션 URL과 QR 코드(스페이스바 토글)가 표시됩니다. claude.ai/code 또는 Claude 모바일 앱에서 접속합니다.

보안 모델

아웃바운드 HTTPS만 사용 — 인바운드 포트를 열지 않음
모든 트래픽이 TLS로 Anthropic API를 거침
짧은 수명의 범위 한정 자격증명 사용

모든 세션에 자동 활성화

/config에서 Enable Remote Control for all sessions를 true로 설정하면 매 세션마다 자동으로 활성화됩니다.

세션 이름 prefix 커스터마이즈 (v2.1.92)

Remote Control 세션 이름은 이제 기본적으로 호스트명 prefix를 사용합니다(예: myhost-graceful-unicorn). 여러 머신을 번갈아 붙는 팀은 --remote-control-session-name-prefix로 머신별 prefix 규칙을 고정하면 구분이 쉬워집니다.

VS Code에서 Remote Control (v2.1.79)

VS Code에서 /remote-control 명령으로 현재 세션을 claude.ai/code에 브릿지할 수 있습니다. 별도의 CLI 실행 없이 IDE에서 바로 원격 접속을 설정합니다.

Remote Control 안정성 개선 (v2.1.81)

세션 제목이 /rename과 동기화됩니다
/exit 명령이 세션을 안정적으로 아카이빙합니다

Remote Control 운영 보강 (v2.1.113)

/extra-usage가 mobile/web Remote Control 클라이언트에서도 동작합니다.
Remote Control 클라이언트가 @ 파일 자동완성 후보를 질의할 수 있습니다.
Remote Control 세션에서 subagent transcript가 스트리밍되지 않던 문제와 Claude 종료 시 세션이 아카이브되지 않던 문제가 수정되었습니다.

세션 추적 헤더 (v2.1.86)

API 요청에 X-Claude-Code-Session-Id 헤더가 자동 포함됩니다. 세션별 사용량 집계나 모니터링 대시보드 구성에 활용할 수 있습니다.

스트림 유휴 타임아웃 (v2.1.84)

CLAUDE_STREAM_IDLE_TIMEOUT_MS 환경변수로 스트리밍 유휴 타임아웃을 설정합니다(기본 90초). 네트워크가 불안정한 환경에서 타임아웃을 늘릴 수 있습니다.

SDK 계정 정보 환경변수

헤드리스/SDK 환경에서 계정 정보를 동기적으로 제공할 수 있습니다(v2.1.51).

export CLAUDE_CODE_ACCOUNT_UUID="..."
export CLAUDE_CODE_USER_EMAIL="..."
export CLAUDE_CODE_ORGANIZATION_UUID="..."

성능 최적화

헤드리스 모드(-p) 실행 시 Yoga WASM/UI 임포트를 지연 로딩하여 시작 성능이 개선되었습니다(v2.1.50).

설정 소스 제한

--setting-sources user 플래그로 동적 프로젝트 스킬을 차단하고 사용자 설정만 로드할 수 있습니다(v2.1.69).

claude -p "분석해줘" --setting-sources user

시스템 프롬프트 파일

--append-system-prompt-file과 --system-prompt-file이 인터랙티브 모드에서도 작동합니다(v2.1.69).

# 인터랙티브 모드에서 시스템 프롬프트 파일 사용
claude --append-system-prompt-file ./security-rules.md

크론 스케줄링

/loop 크론 도구

크론 스케줄링 도구로 세션 내 반복 프롬프트를 지원합니다(v2.1.71).

# 크론 작업 즉시 중지
export CLAUDE_CODE_DISABLE_CRON=1

CLAUDE_CODE_DISABLE_CRON 환경변수로 크론 작업을 즉시 중지할 수 있습니다(v2.1.72). v2.1.113부터는 /loop 대기 중 Esc로 pending wakeup을 취소할 수 있고, wakeup 메시지도 "Claude resuming /loop wakeup" 형태로 더 명확하게 표시됩니다.

SDK 모델 정보 확장

SDK 모델 정보에 다음 필드가 추가되었습니다(v2.1.49):

supportsEffort — effort 제어 지원 여부
supportedEffortLevels — 지원하는 effort 레벨 목록
supportsAdaptiveThinking — 적응형 사고 지원 여부

Code Review (연구 프리뷰)

멀티에이전트 PR 리뷰 시스템입니다. PR이 열리면 Anthropic 인프라에서 여러 에이전트가 diff와 주변 코드를 병렬 분석하여 인라인 코멘트로 결과를 게시합니다.

사용 가능 플랜

Team/Enterprise 전용 연구 프리뷰입니다. Zero Data Retention이 활성화된 조직에서는 사용할 수 없습니다.

작동 방식

관리자가 admin settings에서 Code Review를 활성화하고 리포지토리를 선택
PR 열기/푸시/수동 트리거(@claude review 코멘트) 시 리뷰 실행
여러 에이전트가 다른 유형의 이슈를 병렬 분석 → 검증 단계에서 오탐 필터링 → 심각도별 인라인 코멘트 게시
평균 리뷰 시간: ~20분

심각도 레벨

마커	심각도	의미
🔴	Normal	머지 전 수정 필요
🟡	Nit	사소한 이슈, 차단하지 않음
🟣	Pre-existing	PR이 아닌 기존 코드의 버그

REVIEW.md 커스터마이즈

리포지토리 루트에 REVIEW.md를 추가하면 리뷰 전용 규칙을 정의할 수 있습니다. CLAUDE.md와 별개로, 리뷰 시에만 적용됩니다.

# Code Review Guidelines

## Always check
- 새 API 엔드포인트에 통합 테스트가 있는지
- DB 마이그레이션이 후방 호환되는지

## Skip
- src/gen/ 하위 생성된 파일

요금

토큰 사용량 기반 과금이며, 리뷰당 평균 $15~$ 25입니다. 플랜 포함 사용량과 별도로 extra usage로 청구됩니다.

참고 문서

Headless 사용법과 플래그: https://code.claude.com/docs/ko/headless (한국어)
퍼미션 모드 설정: https://code.claude.com/docs/ko/settings (한국어)
MCP 설정 파일(.mcp.json): https://docs.claude.com/ko/docs/claude-code/mcp (한국어)
Remote Control: https://code.claude.com/docs/en/remote-control (영어)
Code Review: https://code.claude.com/docs/en/code-review (영어)

헤드리스 모드는 Claude Code를 비대화형으로 실행하는 방식입니다. 스크립트와 CI/CD 파이프라인에 적합합니다.

기본 사용법

# 단순 실행 (-p 플래그)
claude -p "src/utils.ts에서 미사용 함수를 찾아줘"

# 도구 허용과 함께
claude -p "테스트를 실행하고 실패하는 것을 수정해줘" \
  --allowedTools "Read,Edit,Bash"

경량 실행 모드 (`--bare`)

# 경량 모드로 실행 (ANTHROPIC_API_KEY 또는 --settings의 apiKeyHelper 필요)
claude --bare -p "코드 분석해줘" --allowedTools "Read,Glob,Grep"

인증 요구사항

--bare 모드에서는 ANTHROPIC_API_KEY 환경변수 또는 --settings로 지정한 설정의 apiKeyHelper가 필요합니다.

PowerShell 도구 (프리뷰, v2.1.84+)

{
  "env": {
    "CLAUDE_CODE_USE_POWERSHELL_TOOL": "1"
  }
}

공식 tools reference는 여전히 native Windows preview로 설명합니다.
GitHub changelog v2.1.111 기준으로는 Linux/macOS에서도 pwsh가 PATH에 있으면 같은 환경변수로 opt-in 가능합니다.
다만 Auto 모드와 샌드박스 지원은 아직 제한적이므로 운영 문서에는 preview 취급이 안전합니다.

v2.1.90에서는 trailing & 백그라운드 우회, -ErrorAction Break 디버거 hang, archive extraction TOCTOU 등 권한 검사 우회 가능성이 보강되었습니다.

입력/출력 형식

형식	용도
`text`	기본 텍스트 출력
`json`	구조화된 결과
`stream-json`	스트리밍 JSON

# JSON 출력
claude -p "분석해줘" --output-format json

# 스트리밍 JSON
claude -p "분석해줘" --output-format stream-json

세션 연속성

# 첫 실행 (세션 ID 포함 JSON)
RESULT=$(claude -p "1단계: 분석" --output-format json)
SESSION_ID=$(echo "$RESULT" | jq -r '.session_id')

# 이어서 실행
claude -p "2단계: 수정" --resume "$SESSION_ID"

시스템 프롬프트 확장

claude -p "분석해줘" \
  --append-system-prompt "보안 취약점에 집중하세요"

퍼미션 모드

# Plan 모드 (읽기 전용)
claude --permission-mode plan -p "아키텍처를 분석해줘"

주의

--dangerously-skip-permissions는 격리된 CI 환경에서만 사용하세요. 로컬 환경에서 사용하면 의도치 않은 파일 수정이 발생할 수 있습니다.

도구 허용/차단

# 읽기만 허용
--allowedTools "Read,Glob,Grep"

# 특정 도구 차단
--disallowedTools "Bash"

Linux 샌드박스 보강 (v2.1.92)

MCP 설정 파일 지정

# MCP 설정 파일 지정
claude -p "이슈를 요약해줘" --mcp-config .mcp.json

GitHub Actions 통합 예시

name: Claude Code Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Claude Code
        run: curl -fsSL https://claude.ai/install.sh | bash -s stable
      - name: Review PR
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          gh pr diff ${{ github.event.pull_request.number }} | \
          claude -p "이 PR을 리뷰해줘" \
            --output-format json \
            --allowedTools "Read,Glob,Grep"

Remote Control

사용 가능 플랜

Pro, Max, Team, Enterprise 모든 플랜에서 사용 가능합니다. Team/Enterprise는 관리자가 먼저 Claude Code를 활성화해야 합니다.

시작 방법

# 새 세션으로 시작
claude remote-control --name "My Project"

# 기존 세션에서 활성화
/remote-control My Project
# 또는 줄여서
/rc My Project

터미널에 세션 URL과 QR 코드(스페이스바 토글)가 표시됩니다. claude.ai/code 또는 Claude 모바일 앱에서 접속합니다.

보안 모델

아웃바운드 HTTPS만 사용 — 인바운드 포트를 열지 않음
모든 트래픽이 TLS로 Anthropic API를 거침
짧은 수명의 범위 한정 자격증명 사용

세션 제목이 /rename과 동기화됩니다
/exit 명령이 세션을 안정적으로 아카이빙합니다

Remote Control 운영 보강 (v2.1.113)

/extra-usage가 mobile/web Remote Control 클라이언트에서도 동작합니다.
Remote Control 클라이언트가 @ 파일 자동완성 후보를 질의할 수 있습니다.
Remote Control 세션에서 subagent transcript가 스트리밍되지 않던 문제와 Claude 종료 시 세션이 아카이브되지 않던 문제가 수정되었습니다.

export CLAUDE_CODE_ACCOUNT_UUID="..."
export CLAUDE_CODE_USER_EMAIL="..."
export CLAUDE_CODE_ORGANIZATION_UUID="..."

성능 최적화

헤드리스 모드(-p) 실행 시 Yoga WASM/UI 임포트를 지연 로딩하여 시작 성능이 개선되었습니다(v2.1.50).

설정 소스 제한

--setting-sources user 플래그로 동적 프로젝트 스킬을 차단하고 사용자 설정만 로드할 수 있습니다(v2.1.69).

claude -p "분석해줘" --setting-sources user

시스템 프롬프트 파일

--append-system-prompt-file과 --system-prompt-file이 인터랙티브 모드에서도 작동합니다(v2.1.69).

# 인터랙티브 모드에서 시스템 프롬프트 파일 사용
claude --append-system-prompt-file ./security-rules.md

크론 스케줄링

/loop 크론 도구

크론 스케줄링 도구로 세션 내 반복 프롬프트를 지원합니다(v2.1.71).

# 크론 작업 즉시 중지
export CLAUDE_CODE_DISABLE_CRON=1

SDK 모델 정보 확장

SDK 모델 정보에 다음 필드가 추가되었습니다(v2.1.49):

supportsEffort — effort 제어 지원 여부
supportedEffortLevels — 지원하는 effort 레벨 목록
supportsAdaptiveThinking — 적응형 사고 지원 여부

Code Review (연구 프리뷰)

사용 가능 플랜

Team/Enterprise 전용 연구 프리뷰입니다. Zero Data Retention이 활성화된 조직에서는 사용할 수 없습니다.

작동 방식

관리자가 admin settings에서 Code Review를 활성화하고 리포지토리를 선택
PR 열기/푸시/수동 트리거(@claude review 코멘트) 시 리뷰 실행
여러 에이전트가 다른 유형의 이슈를 병렬 분석 → 검증 단계에서 오탐 필터링 → 심각도별 인라인 코멘트 게시
평균 리뷰 시간: ~20분

심각도 레벨

마커	심각도	의미
🔴	Normal	머지 전 수정 필요
🟡	Nit	사소한 이슈, 차단하지 않음
🟣	Pre-existing	PR이 아닌 기존 코드의 버그

REVIEW.md 커스터마이즈

리포지토리 루트에 REVIEW.md를 추가하면 리뷰 전용 규칙을 정의할 수 있습니다. CLAUDE.md와 별개로, 리뷰 시에만 적용됩니다.

# Code Review Guidelines

## Always check
- 새 API 엔드포인트에 통합 테스트가 있는지
- DB 마이그레이션이 후방 호환되는지

## Skip
- src/gen/ 하위 생성된 파일

요금

토큰 사용량 기반 과금이며, 리뷰당 평균 $15~$ 25입니다. 플랜 포함 사용량과 별도로 extra usage로 청구됩니다.

참고 문서

Headless 사용법과 플래그: https://code.claude.com/docs/ko/headless (한국어)
퍼미션 모드 설정: https://code.claude.com/docs/ko/settings (한국어)
MCP 설정 파일(.mcp.json): https://docs.claude.com/ko/docs/claude-code/mcp (한국어)
Remote Control: https://code.claude.com/docs/en/remote-control (영어)
Code Review: https://code.claude.com/docs/en/code-review (영어)

Ch11. 헤드리스 & CI/CD

목차

Ch11. 헤드리스 & CI/CD

목차