Claude Code를 프로그래밍 방식으로 실행하기

Agent SDK를 사용하여 CLI, Python 또는 TypeScript에서 Claude Code를 프로그래밍 방식으로 실행하세요.

Agent SDK는 Claude Code를 구동하는 동일한 도구, 에이전트 루프, 컨텍스트 관리 기능을 제공합니다. 스크립트 및 CI/CD용 CLI로 사용하거나, 완전한 프로그래밍 제어를 위해 Python 및 TypeScript 패키지로 사용할 수 있습니다.

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

CLI에서 Claude Code를 프로그래밍 방식으로 실행하려면, -p와 프롬프트 및 CLI 옵션을 함께 전달하세요:

claude -p "Find and fix the bug in auth.py" --allowedTools "Read,Edit,Bash"

이 페이지는 CLI(claude -p)를 통한 Agent SDK 사용법을 다룹니다. 구조화된 출력, 도구 승인 콜백, 네이티브 메시지 객체를 지원하는 Python 및 TypeScript SDK 패키지에 대해서는 Agent SDK 전체 문서를 참조하세요.

기본 사용법

-p(또는 --print) 플래그를 claude 명령에 추가하면 비대화형으로 실행됩니다. 모든 CLI 옵션이 -p와 함께 작동하며, 다음을 포함합니다:

• --continue - 대화 이어가기
• --allowedTools - 도구 자동 승인
• --output-format - 구조화된 출력

이 예시는 Claude에게 코드베이스에 대해 질문하고 응답을 출력합니다:

claude -p "What does the auth module do?"

예시

다음 예시들은 일반적인 CLI 패턴을 보여줍니다.

구조화된 출력 받기

--output-format을 사용하여 응답 반환 방식을 제어합니다:

• text (기본값): 일반 텍스트 출력
• json: 결과, 세션 ID, 메타데이터를 포함한 구조화된 JSON
• stream-json: 실시간 스트리밍을 위한 줄바꿈 구분 JSON

이 예시는 프로젝트 요약을 세션 메타데이터가 포함된 JSON으로 반환하며, 텍스트 결과는 result 필드에 담깁니다:

claude -p "Summarize this project" --output-format json

특정 스키마에 맞는 출력을 받으려면, --output-format json과 --json-schema 및 JSON Schema 정의를 함께 사용하세요. 응답에는 요청에 대한 메타데이터(세션 ID, 사용량 등)가 포함되며, 구조화된 출력은 structured_output 필드에 담깁니다.

이 예시는 함수 이름을 추출하여 문자열 배열로 반환합니다:

claude -p "Extract the main function names from auth.py" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}'

팁: jq와 같은 도구를 사용하여 응답을 파싱하고 특정 필드를 추출할 수 있습니다:

# Extract the text result
claude -p "Summarize this project" --output-format json | jq -r '.result'

# Extract structured output
claude -p "Extract function names from 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 "Explain recursion" --output-format stream-json --verbose --include-partial-messages

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

claude -p "Write a poem" --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가 특정 도구를 확인 없이 사용할 수 있습니다. 이 예시는 테스트 스위트를 실행하고 실패를 수정하며, Claude가 권한 요청 없이 Bash 명령을 실행하고 파일을 읽고 편집할 수 있도록 허용합니다:

claude -p "Run the test suite and fix any failures" \
  --allowedTools "Bash,Read,Edit"

커밋 생성하기

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

claude -p "Look at my staged changes and create an appropriate commit" \
  --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 "You are a security engineer. Review for vulnerabilities." \
  --output-format json

기본 프롬프트를 완전히 대체하는 --system-prompt 등 더 많은 옵션은 시스템 프롬프트 플래그를 참조하세요.

대화 이어가기

--continue를 사용하면 가장 최근 대화를 이어갈 수 있고, --resume에 세션 ID를 지정하면 특정 대화를 이어갈 수 있습니다. 이 예시는 리뷰를 실행한 후 후속 프롬프트를 보냅니다:

# First request
claude -p "Review this codebase for performance issues"

# Continue the most recent conversation
claude -p "Now focus on the database queries" --continue
claude -p "Generate a summary of all issues found" --continue

여러 대화를 동시에 진행하는 경우, 세션 ID를 캡처하여 특정 대화를 재개할 수 있습니다:

session_id=$(claude -p "Start a review" --output-format json | jq -r '.session_id')
claude -p "Continue that review" --resume "$session_id"

다음 단계

• Agent SDK 빠른 시작: Python 또는 TypeScript로 첫 번째 에이전트 만들기
• CLI 레퍼런스: 모든 CLI 플래그 및 옵션
• GitHub Actions: GitHub 워크플로에서 Agent SDK 사용하기
• GitLab CI/CD: GitLab 파이프라인에서 Agent SDK 사용하기