"Claude Code SDK 헤드리스 모드 완전 정복: 자동화와 CLI 활용 가이드"

 

코드를 작성하거나 리뷰할 때 매번 대화형 UI를 열고 입력하는 건 번거로울 수 있습니다. 특히 반복적인 자동화 작업이나 대규모 시스템 운영에서는 효율성이 무엇보다 중요하죠.
Claude Code SDK의 헤드리스 모드는 이런 문제를 해결해 줍니다. 대화형 UI 없이 명령줄 스크립트나 자동화 도구를 통해 Claude Code를 직접 실행할 수 있어, 개발 워크플로우와 운영 환경에 유연하게 통합할 수 있습니다.

이번 글에서는 헤드리스 모드의 개념, 주요 특징, CLI 옵션, 실제 활용 예시까지 하나하나 살펴보며, 여러분이 곧바로 활용할 수 있도록 가이드를 제공하겠습니다.

반응형

---

1. 헤드리스 모드란 무엇인가?

헤드리스 모드는 말 그대로 UI 없이 프로그래밍 방식으로 Claude Code를 실행하는 기능입니다.

• 개발자는 claude 명령어를 통해 CLI 환경에서 직접 프롬프트를 실행할 수 있습니다.
• 자동화 스크립트나 CI/CD 파이프라인에 쉽게 통합할 수 있습니다.
• 최종 결과만 출력하거나, JSON 포맷으로 응답을 받아 후처리에 활용할 수 있습니다.

즉, 헤드리스 모드는 "사람이 직접 대화창을 열고 입력하는 방식"에서 벗어나 자동화와 효율성을 극대화하는 접근 방식입니다.

---

2. 기본 사용법

헤드리스 모드의 가장 기본적인 명령은 다음과 같습니다:

claude -p "내 변경사항을 스테이징하고 이에 대한 커밋 세트를 작성해줘" \
  --allowedTools "Bash,Read" \
  --permission-mode acceptEdits \
  --cwd /path/to/project

여기서 핵심은 -p 또는 --print 옵션입니다.

• -p : 비대화형 모드로 실행
• --allowedTools : 사용할 수 있는 도구 지정
• --cwd : 실행할 작업 디렉토리 지정

---

3. 주요 CLI 옵션 정리

Claude Code SDK는 다양한 옵션을 제공하여 상황에 맞는 세밀한 제어가 가능합니다.

플래그	설명	예시
-p, --print	비대화형 모드 실행	claude -p "쿼리"
--output-format	출력 형식 (text, json, stream-json)	claude -p --output-format json
--resume	세션 ID로 대화 재개	claude --resume abc123
--continue	가장 최근 세션 이어가기	claude --continue
--verbose	상세 로그 활성화	claude --verbose
--allowedTools	허용된 도구 지정	claude --allowedTools "Bash,Read"
--disallowedTools	사용 금지 도구 지정	claude --disallowedTools mcp__github
--mcp-config	MCP 서버 설정 불러오기	claude --mcp-config servers.json

---

4. 출력 형식의 유연성

Claude Code는 결과를 단순 텍스트뿐 아니라 JSON, 스트리밍 JSON으로도 출력할 수 있습니다.

예시 - JSON 출력:

claude -p "데이터 레이어는 어떻게 작동하나요?" --output-format json

응답 구조:

{
  "type": "result",
  "subtype": "success",
  "result": "여기에 응답 텍스트...",
  "session_id": "abc123"
}

이 방식을 활용하면 jq 같은 CLI 도구로 결과를 파싱해 자동화 파이프라인에 쉽게 연결할 수 있습니다.

---

5. 실제 활용 예시

(1) SRE 인시던트 대응 자동화

investigate_incident() {
    local incident_description="$1"
    local severity="${2:-medium}"

    claude -p "인시던트: $incident_description (심각도: $severity)" \
      --append-system-prompt "당신은 SRE 전문가입니다. 문제를 진단하고, 영향을 평가하며, 즉각적인 조치 항목을 제공하세요." \
      --output-format json \
      --allowedTools "Bash,Read,WebSearch,mcp__datadog" \
      --mcp-config monitoring-tools.json
}

investigate_incident "결제 API가 500 오류를 반환함" "high"

→ SRE팀은 긴급 상황에서 Claude Code를 통해 자동 분석 + 즉각 조치 가이드를 받을 수 있습니다.

---

(2) 보안 감사 자동화

audit_pr() {
    local pr_number="$1"

    gh pr diff "$pr_number" | claude -p \
      --append-system-prompt "당신은 보안 엔지니어입니다. 이 PR을 취약점, 안전하지 않은 패턴, 규정 준수 문제에 대해 검토하세요." \
      --output-format json \
      --allowedTools "Read,Grep,WebSearch"
}

audit_pr 123 > security-report.json

→ PR 리뷰 단계에서 보안 검토를 자동화하여 개발자의 실수를 사전에 차단할 수 있습니다.

---

(3) 법률 문서 검토 보조

session_id=$(claude -p "법적 검토 세션 시작" --output-format json | jq -r '.session_id')

claude -p --resume "$session_id" "contract.pdf에서 책임 조항을 검토해줘"
claude -p --resume "$session_id" "GDPR 요구사항 준수를 확인해줘"

→ 법률팀은 다중 턴 대화 기반으로 문서 검토를 이어갈 수 있습니다.

---

6. 모범 사례 및 팁

• JSON 출력 활용: 구조화된 데이터로 후처리를 자동화
• 오류 처리: 종료 코드와 stderr를 확인해 우아하게 처리
• 세션 관리: 다중 턴 대화에서는 세션 ID로 컨텍스트 유지
• 타임아웃 고려: 장시간 실행 작업에 제한 시간 설정
• 속도 제한 준수: 여러 요청 시 호출 간 지연 추가

---

728x90

Claude Code SDK의 헤드리스 모드는 단순한 CLI 도구가 아니라,

• 자동화된 개발 워크플로우,
• SRE 운영 효율성 극대화,
• 보안 및 법률 검토 보조

등 다양한 영역에서 AI 기반 자동화 허브로 활용될 수 있습니다.

특히, 개발자가 직접 입력하지 않아도 되는 환경을 구축하면 생산성은 물론, 사람이 놓칠 수 있는 리스크까지 보완할 수 있습니다. 앞으로 DevOps, SecOps, LegalOps 등 운영의 지능화를 원하는 팀이라면 필수적으로 고려해야 할 도구라 할 수 있습니다.

https://docs.anthropic.com/ko/docs/claude-code/sdk/sdk-headless

헤드리스 모드 - Anthropic