Ch11. 헤드리스 & CI/CD

claude -p 비대화형 실행과 --bare 경량 모드, JSON·stream-json 출력, 세션 연속성·퍼미션 모드·GitHub Actions로 CI 파이프라인을 구성하는 방법

핵심 요약

claude -p(--print)는 어떤 명령이든 비대화형으로 실행하며, --output-format·--allowedTools·--continue 등 대부분의 CLI 옵션과 조합됩니다.
--bare는 hooks·skills·plugins·MCP·CLAUDE.md 자동 검색을 모두 건너뛰어 머신 간 동일한 결과를 보장하므로 CI·스크립트에 권장됩니다.
--output-format json은 total_cost_usd와 세션 ID를, --json-schema는 검증된 결과를 structured_output 필드에 담습니다.
최신 v2.1.181~v2.1.190 릴리스는 --json-schema 출력 결정성과 비대화형 fallback 안정성을 개선했지만, CI는 여전히 schema validation 실패를 명시적으로 처리해야 합니다.
세션은 --continue로 최근 대화를, --resume <id>로 특정 세션을 이어가며, --session-id로 UUID를 직접 지정할 수 있습니다.
--permission-mode(plan·acceptEdits·dontAsk)로 세션 기준선을 잡고, --dangerously-skip-permissions는 격리된 CI에서만 사용합니다.

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

공식 문서 위치

공식 문서에서 이 주제는 이제 "Run Claude Code programmatically"(프로그래밍 방식 실행)라는 제목으로, CLI(claude -p)·Python·TypeScript를 아우르는 Agent SDK 페이지에 통합되어 있습니다. 이 챕터는 그중 CLI(claude -p) 사용에 집중합니다. 콜백, 도구 승인, 네이티브 메시지 객체가 필요하면 Python/TypeScript SDK 패키지를 참고하세요.

기본 사용법

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

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

-p(--print)를 붙이면 어떤 claude 명령이든 비대화형으로 실행됩니다. --output-format, --allowedTools, --continue 등 거의 모든 CLI 옵션을 -p와 함께 사용할 수 있습니다.

구독 플랜 사용량 변경 예고

공식 문서 기준, 2026년 6월 15일부터 구독 플랜에서의 Agent SDK 및 claude -p 사용량은 대화형 사용 한도와 분리된 별도의 월간 Agent SDK 크레딧에서 차감됩니다.

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

--bare 플래그는 hooks, skills, plugins, MCP 서버, 자동 메모리(auto memory), CLAUDE.md의 자동 검색(auto-discovery)을 모두 건너뛰어 시작 시간을 줄입니다. 이를 쓰지 않으면 claude -p도 대화형 세션과 똑같은 컨텍스트(작업 디렉토리나 ~/.claude에 구성된 모든 항목 포함)를 로드합니다. 그래서 --bare는 모든 머신에서 동일한 결과가 필요한 CI·스크립트에 유용합니다. (v2.1.81)

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

--bare 모드에서 Claude는 기본적으로 Bash, 파일 읽기, 파일 편집 도구에 접근합니다. 필요한 컨텍스트는 다음 플래그로 직접 넘깁니다.

로드할 항목	사용 플래그
시스템 프롬프트 추가	`--append-system-prompt`, `--append-system-prompt-file`
설정	`--settings <file-or-json>`
MCP 서버	`--mcp-config <file-or-json>`
사용자 정의 에이전트	`--agents <json>`
플러그인	`--plugin-dir <path>`, `--plugin-url <url>`

인증 요구사항

--bare 모드는 OAuth와 키체인 읽기도 건너뜁니다. 그래서 Anthropic 인증은 ANTHROPIC_API_KEY 환경변수나 --settings로 넘긴 JSON 안의 apiKeyHelper에서 받아야 합니다. Bedrock·Vertex·Foundry는 각 공급자의 일반 자격증명을 그대로 씁니다. 내부적으로 --bare는 CLAUDE_CODE_SIMPLE 환경변수를 설정하며, 공식 문서는 이 모드를 스크립트·SDK 호출에 권장하고 앞으로 -p의 기본값으로 삼겠다고 밝힙니다.

--safe-mode는 재현 가능한 CI 기본값이라기보다 설정 문제 진단용입니다. --bare와 달리 인증, 모델 선택, 내장 도구, 권한 정책은 살려 두지만 CLAUDE.md, skills, plugins, hooks, MCP 서버, custom commands/agents, output styles, workflows, custom themes, keybindings, status line, file-suggestion commands, LSP 서버, auto-memory는 끕니다. Fable 5 fallback, hook, plugin 문제를 깨끗한 세션과 비교할 때 씁니다.

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

Windows 환경에서는 PowerShell 도구를 opt-in 프리뷰로 쓸 수 있습니다. 기존 Bash 대신 PowerShell 명령(cmdlet·.NET 통합 등)을 네이티브로 실행하며, /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 등 권한 검사 우회 가능성이 보강되었습니다.

환경변수 출처

CLAUDE_CODE_USE_POWERSHELL_TOOL, CLAUDE_STREAM_IDLE_TIMEOUT_MS 등 이 챕터의 일부 환경변수는 공식 env-vars 레퍼런스에 명시적으로 문서화되어 있지 않고 GitHub changelog에서 확인되는 항목입니다. 운영에 도입하기 전 사용 중인 버전에서 claude --help로 재확인하세요.

입력/출력 형식

형식	용도
`text`	기본 텍스트 출력
`json`	구조화된 결과(결과·세션 ID·메타데이터)
`stream-json`	줄 단위 스트리밍 JSON

# JSON 출력 (.result 필드에 텍스트 결과)
claude -p "분석해줘" --output-format json

# 스트리밍 JSON (스트리밍에는 --verbose --include-partial-messages가 필요)
claude -p "분석해줘" --output-format stream-json --verbose --include-partial-messages

--output-format json을 쓰면 응답 페이로드에 total_cost_usd와 모델별 비용 분석이 들어와서, 사용 대시보드를 보지 않고도 호출당 지출을 추적합니다.

v2.1.111부터는 plugins가 의존성 불일치로 demote된 경우 stream-json의 init 이벤트에 plugin_errors가 포함됩니다. 헤드리스 파이프라인에서 플러그인 상태를 일찍 잡아내기 쉬워지죠. CI에서 플러그인이 로드되지 않으면 실패시키는 게이트로도 쓸 수 있습니다.

stdin 파이프 입력

비대화형 모드는 stdin을 읽으니 다른 CLI 도구처럼 데이터를 파이프할 수 있습니다. cat build-error.txt | claude -p '원인 설명' > out.txt 같은 식이죠. 단, v2.1.128부터 파이프 stdin은 10MB로 제한됩니다. 넘기면 명확한 에러와 함께 0이 아닌 종료 코드로 끝나니, 더 큰 입력은 파일에 쓴 뒤 프롬프트에서 파일 경로를 참조하세요.

스키마 기반 구조화 출력 (`--json-schema`)

특정 스키마를 따르는 출력이 필요하면 --output-format json에 --json-schema(JSON Schema 정의)를 같이 넘깁니다. 그러면 응답 메타데이터(세션 ID·사용량 등)와 함께 검증된 구조화 결과가 structured_output 필드에 담깁니다.

claude -p "auth.py의 주요 함수 이름을 추출해줘" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}' \
  | jq '.structured_output'

최신 v2.1.181~v2.1.190 릴리스에서는 headless structured output의 결정성과 fallback 동작이 개선되었습니다. 그래도 CI에서는 structured_output 존재 여부, JSON Schema 검증 결과, 종료 코드를 모두 확인하고, 실패 시 원본 result와 stderr를 artifact로 남기세요.

재시도 이벤트 (`system/api_retry`)

API 요청이 재시도 가능한 오류로 실패하면 Claude Code는 재시도 직전에 system/api_retry 이벤트를 내보냅니다. attempt, max_retries, retry_delay_ms, error_status, error(예: rate_limit, server_error, authentication_failed) 같은 필드로 재시도 진행 상황을 표시하거나 커스텀 백오프 로직을 짤 수 있습니다.

세션 연속성

가장 간단한 방법은 --continue(-c)로 가장 최근 대화를 이어가는 것입니다.

# 첫 번째 요청
claude -p "이 코드베이스의 성능 이슈를 검토해줘"

# 가장 최근 대화 계속
claude -p "이제 DB 쿼리에 집중해줘" --continue

여러 대화를 동시에 굴린다면 세션 ID를 캡처해 특정 대화를 --resume(-r)으로 재개합니다.

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

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

--session-id로 UUID를 직접 지정할 수도 있습니다(반드시 유효한 UUID여야 함). CI에서 job id, PR id, 재시도 run id를 session id에 묶어야 할 때 유용합니다.

claude -p "릴리스 노트를 점검해줘" \
  --session-id "00000000-0000-4000-8000-000000000123" \
  --output-format json

시스템 프롬프트 확장

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

--append-system-prompt / --append-system-prompt-file: 기본 프롬프트 뒤에 추가합니다.
--system-prompt / --system-prompt-file: 기본 프롬프트를 완전히 대체합니다.

--system-prompt와 --system-prompt-file은 상호 배타적이며, append 계열은 둘 중 하나와 조합할 수 있습니다.

퍼미션 모드

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

개별 도구를 일일이 나열하는 대신 세션 전체의 기준선을 퍼미션 모드로 잡아도 됩니다.

dontAsk: permissions.allow 규칙이나 읽기 전용 명령 집합에 없는 모든 것을 거부 — 잠긴 CI 실행에 적합합니다.
acceptEdits: 프롬프트 없이 파일 쓰기를 허용하고 mkdir·touch·mv·cp 같은 일반 파일시스템 명령을 자동 승인합니다. 그 외 셸 명령·네트워크 요청은 여전히 --allowedTools 항목이나 permissions.allow 규칙이 있어야 하고, 없으면 실행이 멈춥니다.

claude -p "린트 수정을 적용해줘" --permission-mode acceptEdits

주의

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

샌드박스가 켜진 CI에서는 최신 sandbox.credentials 정책과 destructive-command 자동 승인 보강을 함께 점검하세요. Windows runner는 PowerShell 도구의 sandbox 보강이 적용된 버전인지 claude --version으로 확인한 뒤 Bash 경로와 별도로 smoke test를 두는 편이 안전합니다.

도구 허용/차단

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

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

--allowedTools는 권한 규칙 구문을 따릅니다. 예를 들어 Bash(git diff *)는 git diff로 시작하는 명령을 허용합니다. * 앞의 공백이 중요합니다 — 공백이 없으면 Bash(git diff*)는 git diff-index까지 매칭됩니다.

-p 모드의 슬래시 명령 제한

/code-review 같은 사용자 호출 skill과 기본 제공 명령은 대화형 모드에서만 사용 가능합니다. -p 모드에서는 슬래시 명령 대신 수행할 작업을 자연어로 설명하세요.

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

Self-hosted runner를 쓰는 팀은 v2.1.169의 post-session lifecycle hook으로 세션 종료 후 workspace 삭제 전에 uncommitted work snapshot이나 로그 export를 돌릴 수 있습니다. child process의 SIGTERM->SIGKILL 대기 시간도 설정할 수 있고 기본값은 5초입니다.

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

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

MCP 설정 파일 지정

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

# --mcp-config의 서버만 쓰고 다른 MCP 설정은 무시
claude -p "이슈를 요약해줘" --mcp-config .mcp.json --strict-mcp-config

v2.1.152부터는 claude mcp-clients 계열 CLI로 first-party MCP client 관리를 자동화할 수 있습니다. 팀 bootstrap script에서는 기존 /mcp 대화형 점검과 mcp-clients CLI를 나눠서, CI는 CLI로 검증하고 로컬 문제 해결은 /mcp로 들어가는 식이 안정적입니다.

장시간 MCP 도구 호출이 있는 headless job은 CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT을 명시적으로 설정해 idle timeout을 운영 기준에 맞추세요. 최신 릴리스는 MCP 상태 표시 오탐도 줄였지만, CI에서는 /mcp 화면 대신 exit code와 로그 이벤트를 기준으로 실패를 판단하는 편이 안정적입니다.

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 --bare -p "이 PR을 리뷰해줘" \
            --output-format json \
            --allowedTools "Read,Glob,Grep"

CI에는 --bare 권장

공식 문서는 CI·스크립트 호출에서 로컬에 어쩌다 구성된 항목을 끌어오지 않도록 --bare를 함께 쓰라고 권장합니다. 위 예시처럼 claude --bare -p ...로 호출하면 머신마다 같은 결과가 나옵니다.

Remote Control

로컬 Claude Code 세션을 **다른 기기(폰/태블릿/브라우저)**에서 이어서 쓸 수 있습니다(v2.1.51). 실행은 로컬에 남고, 원격 인터페이스는 그 로컬 세션을 들여다보는 창 역할만 합니다.

사용 가능 플랜

연구 프리뷰이며 Pro, Max, Team, Enterprise 모든 플랜에서 사용 가능합니다. API 키 인증은 지원하지 않으며 claude.ai OAuth 로그인이 필요합니다. Team/Enterprise는 관리자가 먼저 admin settings에서 Remote Control 토글을 켜야 합니다(기본 off).

시작 방법

세 가지 호출 방식이 있습니다.

# 1) 서버 모드 (로컬 대화형 세션 없이 원격 연결만 대기)
claude remote-control --name "My Project"

# 2) 대화형 세션 + Remote Control 동시 활성화
claude --remote-control "My Project"   # 또는 --rc

# 3) 기존 세션에서 활성화 (현재 대화 이력을 그대로 이어감)
/remote-control My Project
# 또는 줄여서
/rc My Project

터미널에 세션 URL과 QR 코드(서버 모드에서 스페이스바로 토글)가 뜹니다. claude.ai/code나 Claude 모바일 앱에서 접속하면 됩니다.

서버 모드에서는 추가 플래그를 쓸 수 있습니다.

--spawn <mode>: same-dir(기본), worktree(세션마다 git worktree), session(단일 세션 전용).
--capacity <N>: 동시 세션 최대 수(기본 32).
--sandbox / --no-sandbox: 파일시스템·네트워크 샌드박스(기본 off).
--verbose: 상세 연결·세션 로그.

보안 모델

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

모든 세션에 자동 활성화

/config에서 Enable Remote Control for all sessions를 true로 설정하면 매 대화형 세션마다 자동으로 활성화됩니다. (데스크톱 앱에서는 Settings → Claude Code → Enable remote control by default로도 토글 가능)

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

Remote Control 세션 이름은 이제 기본적으로 호스트명 prefix를 씁니다(예: myhost-graceful-unicorn). 여러 머신을 번갈아 붙는 팀은 --remote-control-session-name-prefix로 머신별 prefix 규칙을 고정하면 구분하기 쉬워집니다. 같은 효과를 환경변수 CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX로도 줄 수 있습니다.

VS Code에서 Remote Control (v2.1.79)

VS Code에서 /remote-control(또는 /rc) 명령으로 현재 세션을 claude.ai/code에 브릿지할 수 있습니다. 별도로 CLI를 실행하지 않고 IDE에서 바로 원격 접속을 설정합니다. (단, VS Code 명령은 이름 인자나 QR 코드를 지원하지 않습니다.)

모바일 푸시 알림 (v2.1.110+)

Remote Control이 켜져 있으면 Claude가 작업이 끝났거나 결정이 필요한 시점에 모바일 푸시 알림을 보낼 수 있습니다. /config에서 Push when Claude decides를 켜고, 프롬프트에 "테스트 끝나면 알려줘"처럼 요청할 수도 있습니다.

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 종료 시 세션이 아카이브되지 않던 문제가 수정되었습니다.

Background Sessions와 Agent View

v2.1.139 이후로는 장기 자동화를 단일 headless 호출만이 아니라 background session으로도 돌릴 수 있습니다. claude agents로 여는 Agent View(연구 프리뷰)는 모든 백그라운드 세션을 한 화면에서 모니터링하고 디스패치하는 인터페이스입니다.

# 셸에서 바로 백그라운드 작업 시작
claude --bg "flaky test 원인을 조사하고 수정 후보를 제안해줘"

# 이름을 붙여 Agent View에서 찾기 쉽게 만들기
claude --bg --name "flaky-test-fix" "investigate SettingsChangeDetector flakes"

# 특정 subagent를 메인 에이전트로 실행
claude --agent code-reviewer --bg "address review comments on PR 1234"

# 모델 호출 없이 shell command만 PTY-backed background job으로 실행
claude --bg --exec 'pnpm test -- --runInBand'

# 목록/attach/log/stop (그 외 respawn, rm 등)
claude agents
claude attach <id>
claude logs <id>
claude stop <id>   # claude kill 도 동일

대화형 세션 안에서는 /bg나 /background로 현재 conversation을 background session으로 넘길 수 있습니다. 이미 응답이 진행 중이면 그 응답은 백그라운드에서 그대로 이어집니다.

셸에서의 세션 관리

각 백그라운드 세션은 8자 short ID(디렉토리: ~/.claude/jobs/<id>/)로 식별합니다. claude agents --json은 실행 중인 세션을 JSON 배열로 내보내 스크립트화에 쓸 수 있고, claude respawn <id>(또는 --all)는 대화 이력을 그대로 둔 채 세션 프로세스를 재시작합니다. claude rm <id>는 목록에서만 빼고 transcript는 로컬에 남아 claude --resume으로 다시 열 수 있습니다.

격리 기준

Background session은 쓰기 전에 .claude/worktrees/ 아래 isolated git worktree로 옮깁니다. 단, 이미 linked worktree 안이거나, git 저장소가 아니거나, 쓰기가 작업 디렉토리 밖인 경우는 건너뜁니다. worktree가 맞지 않는 repo는 worktree.bgIsolation: "none"을 .claude/settings.json에 설정해 워킹 카피를 직접 편집하게 할 수 있고(v2.1.143+), 이때 병렬 쓰기 충돌 책임은 팀 운영 규칙으로 명시하세요.

`/run`·`/verify` 기반 실행 검증

/run, /verify, /run-skill-generator는 테스트 통과만 보는 게 아니라 앱을 실제로 빌드하고 실행하고 관찰하는 검증 흐름입니다. headless CI에서 쓰려면 프로젝트별 skill이 clean environment에서 재현 가능하게 작성돼 있어야 합니다.

/run
/verify
/run-skill-generator

/run: 변경된 앱을 실행하고 UI/API 동작을 확인합니다.
/verify: 변경 의도가 실제 결과로 확인되는지 관찰합니다.
/run-skill-generator: 프로젝트 전용 실행/검증 skill을 생성합니다.

대화형 전용 명령

위 슬래시 명령은 사용자 호출 skill이라 대화형 모드에서만 동작합니다. -p 헤드리스 호출에서는 직접 호출되지 않으니, CI에서는 같은 빌드·실행 단계를 셸 명령으로 풀어 쓰는 편이 안정적입니다.

운영 플래그와 비필수 트래픽 차단

--log-level: CI 디버깅 시 로그 상세도를 명시합니다. (v2.1.134, GitHub changelog 기준 — 현재 CLI 레퍼런스에는 --debug-file과 CLAUDE_CODE_DEBUG_LOG_LEVEL 환경변수가 문서화돼 있으므로 버전에 따라 확인 필요)
autoUpdates, autoUpdatesChannel: 자동 업데이트 정책을 settings에 기록합니다. (v2.1.133)
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1: 비필수 네트워크 트래픽을 줄입니다(DISABLE_AUTOUPDATER·DISABLE_FEEDBACK_COMMAND·DISABLE_ERROR_REPORTING·DISABLE_TELEMETRY 설정과 동등). (v2.1.133)
CLAUDE_CODE_DISABLE_TERMINAL_TITLE=1: 대화 맥락에 따른 터미널 제목 자동 변경을 끕니다. (v2.1.133)

세션 추적 헤더 (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). 여기에 --bare는 자동 검색 단계 자체를 건너뛰어 시작을 한 번 더 줄여 줍니다.

설정 소스 제한

--setting-sources는 로드할 설정 소스를 콤마로 지정합니다(user, project, local). 예를 들어 --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 크론 도구

/loop는 세션 안에서 프롬프트를 반복 실행하는 번들 skill입니다(scheduled tasks, v2.1.72+). 인터벌과 프롬프트는 둘 다 선택이고, /loop 5m check the deploy처럼 인터벌과 프롬프트를 같이 주면 고정 주기로, 프롬프트만 주면 Claude가 매 반복마다 인터벌을 골라 실행합니다. 작업은 세션 범위로 관리되며, 내부적으로 CronCreate·CronList·CronDelete 도구를 씁니다(세션당 최대 50개).

# 크론 작업(스케줄러 전체)을 끄기
export CLAUDE_CODE_DISABLE_CRON=1

CLAUDE_CODE_DISABLE_CRON=1을 설정하면 스케줄러가 꺼져서 /loop와 크론 도구를 쓸 수 없게 되고, 이미 예약된 작업도 더 이상 발화하지 않습니다(v2.1.72). v2.1.113부터는 /loop 대기 중 Esc로 pending wakeup을 취소할 수 있고, wakeup 메시지도 "Claude resuming /loop wakeup" 형태로 더 또렷하게 표시됩니다.

세션을 넘어서는 스케줄링

/loop는 세션 범위라 새 대화를 시작하면 사라집니다(--resume/--continue로 미만료 작업은 복원). 세션과 상관없이 계속 도는 자동화가 필요하면 Routines(Anthropic 클라우드), Desktop scheduled tasks, GitHub Actions schedule 트리거를 쓰세요.

SDK 모델 정보 확장

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

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

Code Review (연구 프리뷰)

멀티에이전트 PR 리뷰 시스템입니다. PR이 열리면 Anthropic 인프라에서 여러 에이전트가 diff와 주변 코드를 병렬로 분석해 인라인 코멘트로 결과를 답니다. 발견 사항은 PR을 승인하지도 차단하지도 않으니 기존 리뷰 워크플로를 그대로 둬도 됩니다.

사용 가능 플랜

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

작동 방식

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

심각도 레벨

마커	심각도	의미
🔴	Important	머지 전 수정해야 할 버그
🟡	Nit	사소한 이슈, 차단하지 않음
🟣	Pre-existing	PR이 도입하지 않은 기존 코드의 버그

머지 게이팅용 기계 판독 출력

Claude Code Review 체크런은 항상 neutral 결론으로 끝나 머지를 막지 않습니다. 직접 게이팅하려면 체크런 Details 마지막 줄의 기계 판독 주석을 gh + jq로 파싱하세요. 심각도별 카운트가 {"normal": 2, "nit": 1, "pre_existing": 0} 형태로 나오며, normal 키가 🔴 Important 개수입니다 (표시 라벨은 "Important", JSON 키는 normal).

CLAUDE.md / REVIEW.md 커스터마이즈

Code Review는 리포지토리의 두 파일을 읽어 무엇을 지적할지 조정합니다.

CLAUDE.md: 모든 작업에 쓰이는 공유 프로젝트 지침. 리뷰에서는 프로젝트 컨텍스트로 읽혀서 새로 들어온 위반을 nit 수준으로 표시합니다.
REVIEW.md: 리뷰 전용 지침. 리뷰 파이프라인의 모든 에이전트 시스템 프롬프트에 최우선 블록으로 주입돼서, 무엇을 어떤 심각도로 지적하고 어떻게 보고할지 바꿉니다. (@ import 구문은 확장되지 않으니 규칙을 파일에 직접 작성)

# Review instructions

## What Important means here
프로덕션 동작을 깨거나 데이터를 누출하는 것만 Important로 봅니다.
스타일·네이밍·리팩터링 제안은 최대 Nit입니다.

## Do not report
- CI가 이미 강제하는 것: lint, formatting, type errors
- src/gen/ 하위 생성 파일과 *.lock 파일

## Always check
- 새 API 라우트에 통합 테스트가 있는지
- 로그에 이메일·사용자 ID·요청 본문이 들어가지 않는지

로컬 diff 리뷰

GitHub App 없이 터미널에서 바로 diff를 리뷰하려면 어떤 세션에서든 /code-review 명령을 실행합니다. --comment로 인라인 PR 코멘트를 달거나 --fix로 작업 트리에 수정을 적용할 수 있습니다. (이 명령은 v2.1.147 이전 /simplify였고, v2.1.154부터 /simplify는 버그 탐색 없이 정리만 적용하는 별도 리뷰입니다.)

요금

토큰 사용량 기반 과금이고, 리뷰당 평균 $15~$ 25입니다(PR 크기·복잡도·검증량에 비례). Code Review 사용량은 플랜 기본 사용량에 들어가지 않고 usage credits로 따로 청구됩니다. 월간 지출 한도는 admin settings의 usage에서 설정합니다.

참고 문서

Headless / 프로그래밍 방식 실행: https://code.claude.com/docs/ko/headless (한국어)
CLI 레퍼런스(모든 플래그): https://code.claude.com/docs/ko/cli-reference (한국어)
환경변수 레퍼런스: https://code.claude.com/docs/en/env-vars (영어)
퍼미션 모드 설정: https://code.claude.com/docs/ko/settings (한국어)
MCP 설정 파일(.mcp.json): https://code.claude.com/docs/ko/mcp (한국어)
Agent View / Background Sessions: https://code.claude.com/docs/en/agent-view (영어)
Scheduled Tasks(/loop): https://code.claude.com/docs/en/scheduled-tasks (영어)
Remote Control: https://code.claude.com/docs/en/remote-control (영어)
Code Review: https://code.claude.com/docs/en/code-review (영어)

핵심 요약

claude -p(--print)는 어떤 명령이든 비대화형으로 실행하며, --output-format·--allowedTools·--continue 등 대부분의 CLI 옵션과 조합됩니다.
--bare는 hooks·skills·plugins·MCP·CLAUDE.md 자동 검색을 모두 건너뛰어 머신 간 동일한 결과를 보장하므로 CI·스크립트에 권장됩니다.
--output-format json은 total_cost_usd와 세션 ID를, --json-schema는 검증된 결과를 structured_output 필드에 담습니다.
최신 v2.1.181~v2.1.190 릴리스는 --json-schema 출력 결정성과 비대화형 fallback 안정성을 개선했지만, CI는 여전히 schema validation 실패를 명시적으로 처리해야 합니다.
세션은 --continue로 최근 대화를, --resume <id>로 특정 세션을 이어가며, --session-id로 UUID를 직접 지정할 수 있습니다.
--permission-mode(plan·acceptEdits·dontAsk)로 세션 기준선을 잡고, --dangerously-skip-permissions는 격리된 CI에서만 사용합니다.

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

공식 문서 위치

기본 사용법

# 단순 실행 (-p 또는 --print 플래그)
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 모드에서 Claude는 기본적으로 Bash, 파일 읽기, 파일 편집 도구에 접근합니다. 필요한 컨텍스트는 다음 플래그로 직접 넘깁니다.

로드할 항목	사용 플래그
시스템 프롬프트 추가	`--append-system-prompt`, `--append-system-prompt-file`
설정	`--settings <file-or-json>`
MCP 서버	`--mcp-config <file-or-json>`
사용자 정의 에이전트	`--agents <json>`
플러그인	`--plugin-dir <path>`, `--plugin-url <url>`

인증 요구사항

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`	구조화된 결과(결과·세션 ID·메타데이터)
`stream-json`	줄 단위 스트리밍 JSON

# JSON 출력 (.result 필드에 텍스트 결과)
claude -p "분석해줘" --output-format json

# 스트리밍 JSON (스트리밍에는 --verbose --include-partial-messages가 필요)
claude -p "분석해줘" --output-format stream-json --verbose --include-partial-messages

--output-format json을 쓰면 응답 페이로드에 total_cost_usd와 모델별 비용 분석이 들어와서, 사용 대시보드를 보지 않고도 호출당 지출을 추적합니다.

stdin 파이프 입력

스키마 기반 구조화 출력 (`--json-schema`)

claude -p "auth.py의 주요 함수 이름을 추출해줘" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}' \
  | jq '.structured_output'

재시도 이벤트 (`system/api_retry`)

세션 연속성

가장 간단한 방법은 --continue(-c)로 가장 최근 대화를 이어가는 것입니다.

# 첫 번째 요청
claude -p "이 코드베이스의 성능 이슈를 검토해줘"

# 가장 최근 대화 계속
claude -p "이제 DB 쿼리에 집중해줘" --continue

여러 대화를 동시에 굴린다면 세션 ID를 캡처해 특정 대화를 --resume(-r)으로 재개합니다.

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

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

--session-id로 UUID를 직접 지정할 수도 있습니다(반드시 유효한 UUID여야 함). CI에서 job id, PR id, 재시도 run id를 session id에 묶어야 할 때 유용합니다.

claude -p "릴리스 노트를 점검해줘" \
  --session-id "00000000-0000-4000-8000-000000000123" \
  --output-format json

시스템 프롬프트 확장

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

--append-system-prompt / --append-system-prompt-file: 기본 프롬프트 뒤에 추가합니다.
--system-prompt / --system-prompt-file: 기본 프롬프트를 완전히 대체합니다.

--system-prompt와 --system-prompt-file은 상호 배타적이며, append 계열은 둘 중 하나와 조합할 수 있습니다.

퍼미션 모드

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

개별 도구를 일일이 나열하는 대신 세션 전체의 기준선을 퍼미션 모드로 잡아도 됩니다.

dontAsk: permissions.allow 규칙이나 읽기 전용 명령 집합에 없는 모든 것을 거부 — 잠긴 CI 실행에 적합합니다.
acceptEdits: 프롬프트 없이 파일 쓰기를 허용하고 mkdir·touch·mv·cp 같은 일반 파일시스템 명령을 자동 승인합니다. 그 외 셸 명령·네트워크 요청은 여전히 --allowedTools 항목이나 permissions.allow 규칙이 있어야 하고, 없으면 실행이 멈춥니다.

claude -p "린트 수정을 적용해줘" --permission-mode acceptEdits

주의

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

도구 허용/차단

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

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

-p 모드의 슬래시 명령 제한

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

MCP 설정 파일 지정

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

# --mcp-config의 서버만 쓰고 다른 MCP 설정은 무시
claude -p "이슈를 요약해줘" --mcp-config .mcp.json --strict-mcp-config

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 --bare -p "이 PR을 리뷰해줘" \
            --output-format json \
            --allowedTools "Read,Glob,Grep"

CI에는 --bare 권장

Remote Control

사용 가능 플랜

시작 방법

세 가지 호출 방식이 있습니다.

# 1) 서버 모드 (로컬 대화형 세션 없이 원격 연결만 대기)
claude remote-control --name "My Project"

# 2) 대화형 세션 + Remote Control 동시 활성화
claude --remote-control "My Project"   # 또는 --rc

# 3) 기존 세션에서 활성화 (현재 대화 이력을 그대로 이어감)
/remote-control My Project
# 또는 줄여서
/rc My Project

터미널에 세션 URL과 QR 코드(서버 모드에서 스페이스바로 토글)가 뜹니다. claude.ai/code나 Claude 모바일 앱에서 접속하면 됩니다.

서버 모드에서는 추가 플래그를 쓸 수 있습니다.

--spawn <mode>: same-dir(기본), worktree(세션마다 git worktree), session(단일 세션 전용).
--capacity <N>: 동시 세션 최대 수(기본 32).
--sandbox / --no-sandbox: 파일시스템·네트워크 샌드박스(기본 off).
--verbose: 상세 연결·세션 로그.

보안 모델

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

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

Remote Control 운영 보강 (v2.1.113)

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

Background Sessions와 Agent View

# 셸에서 바로 백그라운드 작업 시작
claude --bg "flaky test 원인을 조사하고 수정 후보를 제안해줘"

# 이름을 붙여 Agent View에서 찾기 쉽게 만들기
claude --bg --name "flaky-test-fix" "investigate SettingsChangeDetector flakes"

# 특정 subagent를 메인 에이전트로 실행
claude --agent code-reviewer --bg "address review comments on PR 1234"

# 모델 호출 없이 shell command만 PTY-backed background job으로 실행
claude --bg --exec 'pnpm test -- --runInBand'

# 목록/attach/log/stop (그 외 respawn, rm 등)
claude agents
claude attach <id>
claude logs <id>
claude stop <id>   # claude kill 도 동일

셸에서의 세션 관리

격리 기준

`/run`·`/verify` 기반 실행 검증

/run
/verify
/run-skill-generator

/run: 변경된 앱을 실행하고 UI/API 동작을 확인합니다.
/verify: 변경 의도가 실제 결과로 확인되는지 관찰합니다.
/run-skill-generator: 프로젝트 전용 실행/검증 skill을 생성합니다.

대화형 전용 명령

운영 플래그와 비필수 트래픽 차단

--log-level: CI 디버깅 시 로그 상세도를 명시합니다. (v2.1.134, GitHub changelog 기준 — 현재 CLI 레퍼런스에는 --debug-file과 CLAUDE_CODE_DEBUG_LOG_LEVEL 환경변수가 문서화돼 있으므로 버전에 따라 확인 필요)
autoUpdates, autoUpdatesChannel: 자동 업데이트 정책을 settings에 기록합니다. (v2.1.133)
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1: 비필수 네트워크 트래픽을 줄입니다(DISABLE_AUTOUPDATER·DISABLE_FEEDBACK_COMMAND·DISABLE_ERROR_REPORTING·DISABLE_TELEMETRY 설정과 동등). (v2.1.133)
CLAUDE_CODE_DISABLE_TERMINAL_TITLE=1: 대화 맥락에 따른 터미널 제목 자동 변경을 끕니다. (v2.1.133)

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

성능 최적화

설정 소스 제한

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

시스템 프롬프트 파일

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

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

크론 스케줄링

/loop 크론 도구

# 크론 작업(스케줄러 전체)을 끄기
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를 활성화하고(Claude GitHub App 설치) 리포지토리별 리뷰 동작(PR 생성 시 1회 / 매 푸시 / 수동)을 선택
PR 열기/푸시/수동 트리거(@claude review 또는 @claude review once 코멘트) 시 리뷰 실행
여러 에이전트가 다른 유형의 이슈를 병렬 분석 → 검증 단계에서 오탐 필터링 → 심각도별 인라인 코멘트 게시 + 리뷰 본문 요약
평균 리뷰 시간: ~20분

심각도 레벨

마커	심각도	의미
🔴	Important	머지 전 수정해야 할 버그
🟡	Nit	사소한 이슈, 차단하지 않음
🟣	Pre-existing	PR이 도입하지 않은 기존 코드의 버그

머지 게이팅용 기계 판독 출력

CLAUDE.md / REVIEW.md 커스터마이즈

Code Review는 리포지토리의 두 파일을 읽어 무엇을 지적할지 조정합니다.

CLAUDE.md: 모든 작업에 쓰이는 공유 프로젝트 지침. 리뷰에서는 프로젝트 컨텍스트로 읽혀서 새로 들어온 위반을 nit 수준으로 표시합니다.
REVIEW.md: 리뷰 전용 지침. 리뷰 파이프라인의 모든 에이전트 시스템 프롬프트에 최우선 블록으로 주입돼서, 무엇을 어떤 심각도로 지적하고 어떻게 보고할지 바꿉니다. (@ import 구문은 확장되지 않으니 규칙을 파일에 직접 작성)

# Review instructions

## What Important means here
프로덕션 동작을 깨거나 데이터를 누출하는 것만 Important로 봅니다.
스타일·네이밍·리팩터링 제안은 최대 Nit입니다.

## Do not report
- CI가 이미 강제하는 것: lint, formatting, type errors
- src/gen/ 하위 생성 파일과 *.lock 파일

## Always check
- 새 API 라우트에 통합 테스트가 있는지
- 로그에 이메일·사용자 ID·요청 본문이 들어가지 않는지

Headless / 프로그래밍 방식 실행: https://code.claude.com/docs/ko/headless (한국어)
CLI 레퍼런스(모든 플래그): https://code.claude.com/docs/ko/cli-reference (한국어)
환경변수 레퍼런스: https://code.claude.com/docs/en/env-vars (영어)
퍼미션 모드 설정: https://code.claude.com/docs/ko/settings (한국어)
MCP 설정 파일(.mcp.json): https://code.claude.com/docs/ko/mcp (한국어)
Agent View / Background Sessions: https://code.claude.com/docs/en/agent-view (영어)
Scheduled Tasks(/loop): https://code.claude.com/docs/en/scheduled-tasks (영어)
Remote Control: https://code.claude.com/docs/en/remote-control (영어)
Code Review: https://code.claude.com/docs/en/code-review (영어)

목차

Ch11. 헤드리스 & CI/CD

목차