헤드리스(프로그래밍) 모드

읽는 시간: 12분 | 난이도: 고급자

Agent SDK를 사용하면 Claude Code를 대화형 세션 없이 프로그래밍 방식으로 실행할 수 있습니다. CI/CD 파이프라인 자동화, 스크립트 통합, 배치 처리 등 다양한 용도에 활용할 수 있습니다.

참고: 이전에는 "헤드리스 모드"라고 불렸습니다. -p 플래그와 모든 CLI 옵션은 동일하게 작동합니다.

기본 사용법

Claude Code를 비대화형으로 실행하려면 -p (또는 --print) 플래그를 사용합니다.

claude -p "auth.py의 버그를 찾아서 수정해줘" --allowedTools "Read,Edit,Bash"

-p 플래그와 함께 모든 CLI 옵션을 사용할 수 있습니다.

--continue: 이전 대화 이어가기
--allowedTools: 도구 자동 승인
--output-format: 구조화된 출력 형식 지정

코드베이스에 대해 질문하고 응답을 출력하는 간단한 예시입니다.

claude -p "auth 모듈은 무엇을 하는가?"

주요 사용 패턴

구조화된 출력 가져오기

--output-format 플래그로 응답 형식을 제어할 수 있습니다.

형식	설명
`text` (기본)	일반 텍스트 출력
`json`	결과, 세션 ID, 메타데이터가 포함된 구조화된 JSON
`stream-json`	실시간 스트리밍을 위한 줄 단위 JSON

프로젝트 요약을 JSON으로 받는 예시입니다. 텍스트 결과는 result 필드에 포함됩니다.

claude -p "이 프로젝트를 요약해줘" --output-format json

특정 스키마에 맞는 출력을 얻으려면 --output-format json과 함께 --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를 활용하면 응답에서 특정 필드를 쉽게 추출할 수 있습니다.

# 텍스트 결과 추출
claude -p "이 프로젝트를 요약해줘" --output-format json | jq -r '.result'

# 구조화된 출력 추출
claude -p "auth.py에서 함수 이름 추출" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}' \
  | jq '.structured_output'

실시간 스트리밍

토큰이 생성되는 대로 받으려면 --output-format stream-json을 --verbose, --include-partial-messages와 함께 사용합니다. 각 줄은 이벤트를 나타내는 JSON 객체입니다.

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

jq를 사용하여 텍스트 델타만 필터링하는 예시입니다. -r 플래그는 따옴표 없는 원시 문자열을, -j 플래그는 토큰이 연속으로 스트리밍되도록 줄바꿈 없이 출력합니다.

claude -p "시를 써줘" \
  --output-format stream-json \
  --verbose \
  --include-partial-messages | \
  jq -rj 'select(.type == "stream_event" and .event.delta.type? == "text_delta") | .event.delta.text'

콜백과 메시지 객체를 사용한 프로그래밍 방식 스트리밍은 Agent SDK 문서를 참조하세요.

도구 자동 승인

--allowedTools를 사용하면 Claude가 특정 도구를 사용할 때 매번 확인을 요청하지 않습니다. 이 예시는 테스트 스위트를 실행하고 실패를 수정하면서 Bash 명령과 파일 읽기/편집을 자동으로 허용합니다.

claude -p "테스트 스위트를 실행하고 실패를 수정해줘" \
  --allowedTools "Bash,Read,Edit"

커밋 생성

스테이징된 변경사항을 검토하고 적절한 커밋 메시지로 커밋을 생성하는 예시입니다.

claude -p "스테이징된 변경사항을 보고 적절한 커밋을 만들어줘" \
  --allowedTools "Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)"

--allowedTools 플래그는 권한 규칙 문법을 사용합니다. 뒤에 *를 붙이면 접두사 매칭이 활성화됩니다. 예를 들어 Bash(git diff *)는 git diff로 시작하는 모든 명령을 허용합니다. * 앞의 공백이 중요합니다. 공백 없이 Bash(git diff*)로 쓰면 git diff-index도 매칭됩니다.

참고: /commit 같은 사용자 호출 스킬과 빌트인 명령은 대화형 모드에서만 사용 가능합니다. -p 모드에서는 수행하려는 작업을 직접 설명하세요.

시스템 프롬프트 커스터마이징

--append-system-prompt를 사용하면 Claude Code의 기본 동작을 유지하면서 지시사항을 추가할 수 있습니다. 이 예시는 PR diff를 Claude에게 파이프로 전달하고 보안 취약점을 검토하도록 지시합니다.

gh pr diff "$1" | claude -p \
  --append-system-prompt "당신은 보안 엔지니어입니다. 취약점을 검토하세요." \
  --output-format json

기본 프롬프트를 완전히 교체하려면 --system-prompt를 사용합니다. 더 많은 옵션은 시스템 프롬프트 플래그를 참조하세요.

대화 이어가기

--continue로 가장 최근 대화를 이어가거나, --resume과 세션 ID로 특정 대화를 이어갈 수 있습니다.

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

# 가장 최근 대화 이어가기
claude -p "이제 데이터베이스 쿼리에 집중해줘" --continue
claude -p "발견된 모든 문제를 요약해줘" --continue

여러 대화를 실행 중이라면 세션 ID를 캡처하여 특정 대화를 재개할 수 있습니다.

session_id=$(claude -p "리뷰 시작" --output-format json | jq -r '.session_id')
claude -p "그 리뷰 계속해줘" --resume "$session_id"

실전 자동화 예시

CI/CD 파이프라인 통합

GitHub Actions에서 코드 리뷰를 자동화하는 예시입니다.

name: AI Code Review
on: [pull_request]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run Claude Code Review
        run: |
          gh pr diff ${{ github.event.number }} | \
          claude -p \
            --append-system-prompt "코드 품질, 버그, 보안 취약점을 검토하세요." \
            --output-format json | \
          jq -r '.result' > review.md
      - name: Post Review Comment
        run: gh pr comment ${{ github.event.number }} --body-file review.md

배치 파일 처리

여러 파일을 자동으로 문서화하는 스크립트입니다.

#!/bin/bash
# 모든 Python 파일에 독스트링 추가

for file in src/**/*.py; do
  echo "Processing $file..."
  claude -p "다음 파일에 누락된 독스트링을 추가해줘: $file" \
    --allowedTools "Read,Edit" \
    --output-format json | jq -r '.result'
done

구조화된 데이터 추출

코드베이스에서 API 엔드포인트 목록을 추출하는 예시입니다.

claude -p "이 프로젝트의 모든 API 엔드포인트를 찾아줘" \
  --output-format json \
  --json-schema '{
    "type": "object",
    "properties": {
      "endpoints": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "method": {"type": "string"},
            "path": {"type": "string"},
            "description": {"type": "string"}
          }
        }
      }
    }
  }' | jq '.structured_output.endpoints'

Python/TypeScript SDK 사용

CLI 외에도 Python과 TypeScript 패키지를 통해 완전한 프로그래밍 방식 제어가 가능합니다.

Python SDK

구조화된 출력, 도구 승인 콜백, 네이티브 메시지 객체를 지원합니다.

from anthropic.agents import ClaudeCode

async def analyze_codebase():
    agent = ClaudeCode()

    result = await agent.run(
        prompt="이 코드베이스의 아키텍처를 분석해줘",
        allowed_tools=["Read", "Bash(find *)", "Bash(grep *)"],
        output_format="json"
    )

    print(result.text)
    print(f"Session ID: {result.session_id}")

TypeScript SDK

타입 안전한 API로 Claude Code를 통합하는 예시입니다.

import { ClaudeCode } from '@anthropic-ai/agent-sdk';

async function runCodeReview(prDiff: string): Promise<string> {
  const agent = new ClaudeCode();

  const result = await agent.run({
    prompt: prDiff,
    systemPrompt: "당신은 시니어 개발자입니다. 코드를 리뷰하세요.",
    allowedTools: ['Read'],
    outputFormat: 'json'
  });

  return result.result;
}

`-p` 모드의 제한 사항

대화형 모드와 달리 -p 모드에서는 다음 기능이 제한됩니다.

/commit, /review 등 사용자 호출 스킬 사용 불가
빌트인 명령어(/help, /config 등) 사용 불가
대화 중 파일 편집 승인 프롬프트 표시 안 됨 (사전에 --allowedTools로 설정 필요)

이러한 제한을 우회하려면 작업을 자연어로 직접 설명하거나, 필요한 도구를 --allowedTools로 미리 지정하세요.

다음 단계

Agent SDK 빠른 시작 - Python 또는 TypeScript로 첫 번째 에이전트 구축
CLI 레퍼런스 - 모든 CLI 플래그와 옵션 탐색
GitHub Actions 가이드 - GitHub 워크플로우에서 Agent SDK 사용
GitLab CI/CD 가이드 - GitLab 파이프라인에서 Agent SDK 사용
권한 관리 - 도구 권한 세밀하게 제어하기