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

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

Agent SDK를 쓰면 Claude Code를 CLI·Python·TypeScript에서 프로그래밍 방식으로 실행할 수 있어요. 스크립트·CI/CD용 CLI로도, 완전한 프로그래밍 제어용 Python·TypeScript 패키지로도 쓸 수 있죠. 이 문서는 claude -p로 비대화형 실행을 다루며, 기본 사용법부터 구조화 출력·권한 승인·스트리밍까지 살펴봅니다.

출처: 공식문서

본문

Agent SDK는 Claude Code를 움직이는 것과 같은 도구·에이전트 루프·컨텍스트 관리를 줘요. 스크립트·CI/CD용 CLI로, 또는 완전한 프로그래밍 제어용 Python·TypeScript 패키지로 사용할 수 있어요.

비대화형 모드로 Claude Code를 실행하려면 프롬프트와 필요한 CLI 옵션과 함께 -p를 전달하세요.

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

이 페이지는 CLI(claude -p)로 Agent SDK를 쓰는 법을 다뤄요. 구조화 출력·도구 승인 콜백·네이티브 메시지 객체가 있는 Python·TypeScript SDK 패키지는 전체 Agent SDK 문서를 보세요.

기본 사용법

아무 claude 명령에 -p(또는 --print) 플래그를 추가하면 비대화형으로 실행해요. 모든 CLI 옵션이 -p와 결합하는 건 아니에요. Claude Code는 --bg를 거부하고, 작업 설명과 함께 --cloud를 거부하며, 이름을 짓는 충돌 오류를 반환해요. --cloud와 세션 ID·-p는 대신 그 클라우드 세션에 메시지를 큐에 넣고 종료해요. -p와 자주 결합하는 옵션은 다음과 같아요.

이 예제는 코드베이스에 대해 Claude에게 질문하고 응답을 출력해요.

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

Claude Code는 성공 시 코드 0, 실행 실패 시 0이 아닌 코드로 종료하므로 스크립트가 종료 상태로 분기할 수 있어요. 잘못된 플래그를 전달하면 실행 전에 오류를 stderr로 보고해요. 실행 안에서 실패(인증 누락 등)가 일어나면 Claude Code가 실패를 결과로 stdout에 출력해요.

bare 모드로 더 빨리 시작

--bare를 추가하면 훅·스킬·커스텀 커맨드·서브에이전트·플러그인·MCP 서버·자동 메모리·CLAUDE.md의 자동 발견을 건너뛰어 시작 시간을 줄여요. 없으면 claude -p는 작업 디렉터리나 ~/.claude에 구성된 것을 포함해 대화형 세션이 로드하는 것과 같은 컨텍스트를 로드해요.

Bare 모드는 모든 머신에서 같은 결과가 필요한 CI·스크립트에 유용해요. 팀원 ~/.claude의 훅이나 프로젝트 .mcp.json의 MCP 서버는 bare 모드가 절대 읽지 않으므로 실행되지 않아요. --add-dir로 이름을 붙인 디렉터리는 부분 예외예요. bare 모드는 그 .claude/skills/ 폴더의 스킬을 로드하지만 .claude/commands/와 .claude/agents/ 폴더는 여전히 건너뛰어요. 추가 디렉터리의 스킬이 무엇이 로드되는지·되지 않는지 다뤄요.

--bare 없이도 -p 세션은 한 번도 신뢰하지 않은 폴더에서도 프로젝트의 .claude/settings.json 훅을 실행하고 .mcp.json의 서버를 연결해요. -p 세션은 워크스페이스 신뢰 대화상자도 서버별 승인 프롬프트도 보여주지 않아요. 폴더를 신뢰하기 전에 실행되는 것이 -p 아래의 각 저장소 콘텐츠와 그것을 제외하는 법을 다뤄요.

이 예제는 bare 모드에서 일회성 요약 작업을 실행하고 Read 도구를 미리 승인해 권한 프롬프트 없이 완료되게 해요. 실행 전에 ANTHROPIC_API_KEY를 설정하세요. bare 모드가 구독 로그인을 쓰지 않기 때문이에요.

claude --bare -p "Summarize README.md" --allowedTools "Read"

Bare 모드에서 Claude Code는 OAuth 자격 증명이나 시스템 키체인을 절대 읽지 않아요. Anthropic API는 Claude Console에서 만든 키로 환경의 ANTHROPIC_API_KEY를 설정하거나, --settings JSON에 apiKeyHelper를 제공하세요. Amazon Bedrock·Google Cloud's Agent Platform·Microsoft Foundry는 평소처럼 자체 프로바이더 자격 증명을 계속 읽어요.

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는 스크립트·SDK 호출에 권장되는 모드이고, 향후 릴리스에서 -p의 기본이 될 예정이에요.

종료 시 백그라운드 작업

claude -p 실행 중 Claude가 백그라운드 Bash 작업(개발 서버·워치 빌드 등)을 시작하면, Claude가 최종 결과를 반환하고 stdin이 닫힌 뒤 약 5초 후에 그 셸이 종료돼요. 유예 기간은 결과 직후 끝나는 작업이 출력을 전달하게 해요.

Claude가 백그라운드 서브에이전트나 워크플로우를 시작하면 claude -p는 대신 그 작업이 끝날 때까지 열려 있는데, 그 결과가 최종 출력의 일부이기 때문이에요.

기본적으로 대기는 연속 유휴 대기 10분 후 끝나서, 막힌 서브에이전트·워크플로우가 프로세스를 무기한 붙들 수 없어요. 그 시점 Claude Code는 여전히 도는 것을 멈추고 부분 결과를 버려요. 한도는 CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS로 바꾸거나, 0으로 설정해 상한 없이 기다릴 수 있어요.

claude -p 실행 중 Claude가 Monitor 워치를 시작하면 Claude Code는 워치가 타임아웃되거나 10분 상한이 대기를 끝낼 때까지(둘 중 먼저) 기다려요. 기다리는 동안 Claude는 워치가 보고하는 것에 계속 응답해요. 기본적으로 워치는 Claude가 시작한 5분 후 타임아웃돼요.

SIGTERM으로 실행 중지

kill이나 프로세스 슈퍼바이저로 claude -p 실행에 SIGTERM을 보내면 Claude Code가 코드 143으로 종료해요. 진행 중이던 턴은 미완성으로 두고 결과를 기록하지 않아요. 턴을 끝내려면 프로세스를 멈추기 전에 SIGINT를 보내거나 Agent SDK의 interrupt()를 호출하세요.

SIGTERM에서 Claude Code는 여전히 도는 Bash 명령의 프로세스 트리를 종료해요. 그다음 SessionEnd 훅을 실행하고 종료해요. 종료 중 Claude Code는 새 도구 호출을 시작하지 않고, 새 모델 요청을 보내지 않으며, SessionEnd 외의 훅을 실행하지 않아요. 신호가 도착했을 때 실행이 명령 중간이거나 권한 프롬프트를 기다리고 있으면 Claude Code가 그 단계를 다음과 같이 처리해요.

  • 명령 실행 중: Claude Code가 세션에서 명령을 killed로 기록해요.
  • 권한 프롬프트 답 기다리는 중: 프로세스에 SIGTERM을 보내면 Claude Code가 프롬프트를 무응답으로 둬요. 프로그램이 Agent SDK로 세션을 닫으면 SDK가 신호를 보내기 전에 Claude Code의 입력을 끝내고, Claude Code가 입력이 끝나는 즉시 프롬프트를 취소해요.

세션을 재개하면 Claude Code가 SIGTERM이 미완으로 남긴 턴을 계속해요.

예제

이 예제들은 흔한 CLI 패턴을 강조해요. auth.py·build-error.txt 같은 파일을 이름 짓는 명령은 내 프로젝트의 파일로 대체하세요. CI·스크립트 환경에서는 --bare를 추가해 Claude Code가 호스트의 훅·플러그인·자동 메모리·CLAUDE.md를 로드하지 않고 시작하게 하세요.

Claude로 데이터 파이프

비대화형 모드는 stdin을 읽으므로 다른 명령줄 도구처럼 데이터를 파이프해 넣고 응답을 리다이렉트할 수 있어요.

이 예제는 빌드 로그를 Claude에 파이프하고 설명을 파일에 써요.

cat build-error.txt | claude -p 'concisely explain the root cause of this build error' > output.txt

--output-format json을 쓰면 응답 페이로드가 total_cost_usd와 모델별 비용 분해를 포함하므로, 스크립트 호출자가 사용 대시보드를 조회하지 않고 호출당 지출을 추적할 수 있어요. 두 수치는 클라이언트 측 추정이고 실제 청구서와 다를 수 있어요.

참고: 파이프된 stdin은 10MB로 제한돼요. 상한을 넘으면 Claude Code가 명확한 오류와 0이 아닌 상태로 종료해요. 더 큰 입력은 파일에 쓰고 파이프 대신 프롬프트에서 파일 경로를 참조하세요.

Claude Code가 stdin을 읽을 수 없으면(시작한 프로세스가 그 끝을 끊은 경우) stderr에 경고를 출력하고 명령줄의 프롬프트로 계속해요. v2.1.211 이전에는 Windows에서 읽을 수 없는 stdin이 세션을 충돌시키거나 출력 없이 조용히 종료시켰어요.

빌드 스크립트에 Claude 추가

비대화형 호출을 스크립트로 감싸 프로젝트별 린터·리뷰어로 쓸 수 있어요.

이 package.json 스크립트는 main과의 diff를 Claude에 파이프하고 오타를 보고하라고 해요. diff를 파이프하므로 Claude가 읽으려고 Bash 권한이 필요 없고, 이스케이프된 큰따옴표가 스크립트를 Windows에 이식 가능하게 해요.

{
  "scripts": {
    "lint:claude": "git diff main | claude -p \"you are a typo linter. for each typo in this diff, report filename:line on one line and the issue on the next. return nothing else.\""
  }
}

npm run lint:claude로 실행하세요.

구조화 출력 얻기

--output-format으로 응답이 반환되는 방식을 제어해요.

  • text(기본): 일반 텍스트 출력
  • json: result·session ID·metadata가 있는 구조화된 JSON
  • stream-json: 실시간 스트리밍용 줄바꿈 구분 JSON

이 예제는 텍스트 결과를 result 필드에 담아 세션 메타데이터와 함께 JSON으로 프로젝트 요약을 반환해요.

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

특정 스키마에 맞는 출력을 얻으려면 --output-format json을 --json-schema 및 JSON Schema 정의와 함께 쓰세요. 응답은 구조화 출력을 structured_output 필드에 담아 요청 메타데이터(session ID·usage 등)를 포함해요.

이 예제는 함수 이름을 추출해 문자열 배열로 반환해요.

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"]}'

값이 유효한 JSON Schema가 아니면 claude가 Error: --json-schema is not a valid JSON Schema 뒤에 검증기 진단을 붙여 종료해요. Claude Code는 "format": "email"처럼 format 키워드를 쓰는 스키마를 받아들이지만 format을 주석으로 취급하고 강제하지 않아요. v2.1.205 이전에는 Claude Code가 잘못된 스키마를 조용히 무시하고 구조화되지 않은 텍스트를 반환했으며, format을 포함한 아무 스키마나 잘못된 것으로 취급했어요.

팁: jq 같은 도구로 응답을 파싱해 특정 필드를 추출하세요.

# 텍스트 결과 추출
claude -p "Summarize this project" --output-format json | jq -r '.result'

# 구조화 출력 추출
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

스트림의 마지막 줄은 최종 응답 텍스트·비용·세션 메타데이터가 있는 result 메시지예요.

컨슈머가 스트림을 천천히 읽으면 Claude Code가 큐에 남은 출력이 비워질 때까지 기다렸다가 종료하는데, 남은 양에 비례해 대기를 조정하고 최대 30초로 제한해요. v2.1.214 이전에는 종료 대기가 약 2초로 제한되어 큰 응답의 끝이 잘릴 수 있었어요.

다음 예제는 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 문서의 실시간 응답 스트리밍을 보세요.

서브에이전트 메시지 따라가기

서브에이전트의 메시지는 parent_tool_use_id 필드가 서브에이전트를 만든 도구 호출의 ID인 assistant·user 메시지로 스트림에 나타나요. 주 대화의 메시지는 그 필드에 null을 싣고요.

포그라운드에서 도는 서브에이전트의 첫 메시지는 그것을 구동하는 프롬프트를 싣는 user 메시지예요. 그 첫 메시지 뒤 Claude Code는 다음을 내보내요.

  • 기본: 서브에이전트의 tool_use·tool_result 블록.
  • --forward-subagent-text 또는 CLAUDE_CODE_FORWARD_SUBAGENT_TEXT 사용 시: 서브에이전트의 텍스트·생각 블록도 내보내 각 서브에이전트 트랜스크립트를 재구성할 수 있어요. Claude Code v2.1.211 이상이 필요해요.

어느 옵션을 켜면 Claude Code가 모든 중첩 깊이의 서브에이전트에서 메시지를 전달해요. 서브에이전트가 자체 서브에이전트를 만들면 중첩 서브에이전트의 메시지가 그것을 만든 Agent 도구 호출의 ID를 parent_tool_use_id에 싣어, 그 ID를 따라가면 전체 중첩 트리를 재구성할 수 있어요. v2.1.219 이전에는 중첩 서브에이전트의 메시지가 스트림에 나타나지 않았어요.

서브에이전트에서 실행되는 스킬도 같은 방식으로 스트림에 나타나요. 포크된 스킬의 첫 메시지는 실행을 구동하는 스킬 콘텐츠를 싣는 user 메시지예요. 어느 옵션을 켜면 스트림이 포크된 스킬의 텍스트·생각 블록도 싣고요. v2.1.265 이전에는 포크된 스킬의 tool_use·tool_result 블록만 스트림에 나타났어요.

API 재시도 처리

API 요청이 재시도 가능한 오류로 실패하면 Claude Code가 재시도 전에 system/api_retry 이벤트를 내보내요. v2.1.246 이상에서는 401·403이 apiKeyHelper 자격 증명을 거부하면 Claude Code가 처음 두 재시도를 이벤트 없이 조용히 하고, 세 번째 연속 재시도부터 평소처럼 이벤트를 내보내요. 조용한 재시도도 attempt에 계속 세요. 이벤트로 자신의 인터페이스에 재시도 진행 상황을 보여줄 수 있어요.

필드 타입 설명
type "system" 메시지 타입
subtype "api_retry" 이것을 재시도 이벤트로 식별
attempt 정수 현재 시도 번호, 1부터 시작
max_retries 정수 이 실패 원인에 허용된 총 재시도(세션 전체 예산보다 적을 수 있음)
retry_delay_ms 정수 다음 시도까지의 밀리초
error_status 정수 또는 null 실패한 시도의 HTTP 상태 코드. 시도가 API에서 HTTP 응답을 못 받으면 null
no_response 객체, 선택 실패한 시도가 제때 응답 헤더를 못 받았을 때만 존재. waited_ms는 그 시도가 기다린 시간, retry_wait_ms는 재시도가 기다릴 시간. 이 이벤트에서 max_retries는 세션 전체 예산이 아니라 이 원인이 보통 받는 한 번의 재시도를 반영. Claude Code v2.1.261 이상 필요
error 문자열 오류 카테고리: authentication_failed, oauth_org_not_allowed, account_on_hold, billing_error, rate_limit, overloaded, invalid_request, model_not_found, server_error, max_output_tokens, cloud_credential_error, unknown
uuid 문자열 고유 이벤트 식별자
session_id 문자열 이벤트가 속한 세션
세션 메타데이터 읽기

system/init 이벤트가 모델·도구·MCP 서버·로드된 플러그인을 포함한 세션 메타데이터를 보고해요. 시작 이벤트가 선행하지 않으면 스트림의 첫 이벤트예요.

이벤트는 또한 이 Claude Code 버전이 구현하는 프로토콜 동작을 짓는 선택적 capabilities 문자열 배열(interrupt_receipt_v1, interrupt_cancel_queued_v1 등)을 싣고요. 버전 문자열을 비교하는 대신 기능 감지로 확인하고, 인식하지 못하는 값은 무시하세요. 필드는 Claude Code v2.1.205 이상이 필요하고 이전 버전에는 없어요. 기능 목록은 SDKSystemMessage를 보세요.

플러그인·MCP 서버가 로드 안 되면 CI 실패

system/init 이벤트의 플러그인 필드로 로드 안 된 플러그인을 잡아요.

필드 타입 설명
plugins 배열 성공적으로 로드된 플러그인. 각각 name·path
plugin_errors 배열 플러그인 로드 시 오류. 각각 plugin·type·message. 충족되지 않은 의존성 버전과 누락 경로·잘못된 아카이브 같은 --plugin-dir 로드 실패를 포함. 영향받은 플러그인은 강등되어 plugins에 없음. 오류가 없으면 키 생략

MCP 서버 필드도 같은 방식으로 쓰세요. --mcp-config를 -p와 함께 전달하면 Claude Code가 첫 턴 전에 아직 보류 중인 서버를 기다리는데, 최대 MCP_TIMEOUT 시작 타임아웃(기본 30초)까지 기다려요. 캐시된 도구 목록이 있는 원격 서버는 대기를 건너뛰고 system/init에서 pending을 보여주며 첫 도구 호출에 연결돼요. 대기는 Claude Code v2.1.221 이상이 필요해요.

Claude Code는 시작 시 각 --mcp-config 항목을 검증하고 검증에 실패한 항목(type 없는 url 항목 등)을 건너뛰어요. 실행은 계속되고 깨끗하게 종료되므로, 로드되지 않은 서버를 잡으려면 이 필드들을 확인하세요.

필드 타입 설명
mcp_servers 배열 세션의 MCP 서버. 각각 name·status
mcp_server_errors 배열 구성 검증이 건너뛴 --mcp-config 항목. 각각 name·type·message. type은 unknown_type·url_missing_type·invalid_config·reserved_name 같은 건너뛰기 카테고리. 인식하지 못하는 값은 일반 건너뛰기로 취급. 영향받은 서버는 mcp_servers에 없음. 오류가 없으면 키 생략되므로 CI 게이트가 비어있지 않은 배열에서 실패할 수 있음. Claude Code v2.1.219 이상 필요

터미널에서 명령을 손으로 실행하면 Claude Code도 Warning: 1 MCP server skipped due to invalid config: 같은 시작 경고를 stderr에 출력하고 각 건너뛴 항목의 이유를 붙여요. stderr를 리다이렉트하거나 CI 러너·SDK 호스트 같은 프로그램이 캡처하면 Claude Code는 경고를 출력하지 않고 mcp_server_errors 필드에만 건너뛴 항목을 보고해요. 경고는 Claude Code v2.1.219 이상이 필요해요.

플러그인 설치 추적

CLAUDE_CODE_SYNC_PLUGIN_INSTALL이 설정되면 Claude Code가 첫 턴 전에 마켓플레이스 플러그인이 설치되는 동안 system/plugin_install 이벤트를 내보내요. 자체 UI에 설치 진행 상황을 표시하는 데 써요.

필드 타입 설명
type "system" 메시지 타입
subtype "plugin_install" 이것을 플러그인 설치 이벤트로 식별
status "started", "installed", "failed", "completed" started·completed는 전체 설치를 묶고, installed·failed는 개별 마켓플레이스를 보고
name 문자열, 선택 마켓플레이스 이름. installed·failed에 존재
error 문자열, 선택 실패 메시지. failed에 존재
uuid 문자열 고유 이벤트 식별자
session_id 문자열 이벤트가 속한 세션

도구 자동 승인

--allowedTools로 Claude가 프롬프트 없이 특정 도구를 쓰게 해요. 이 예제는 테스트 스위트를 실행하고 실패를 고치며, 허락 없이 Bash 명령 실행·파일 읽기/편집을 허용해요.

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

개별 도구를 나열하는 대신 세션 전체에 기준을 설정하려면 권한 모드를 전달하세요. -p에서는 내장 시작 권한 모드가 모든 플랜에서 Manual이므로 원하는 권한 모드를 전달하세요.

  • auto: --permission-mode auto를 전달해 분류기가 나 대신 대부분 행동을 검토하게 해요
  • dontAsk: Claude Code가 달리 프롬프트할 모든 호출을 거부해, 잠긴 CI 실행에 유용해요. Manual 모드에서 승인이 필요 없는 행동(작업 디렉터리 파일 읽기, 읽기 전용 명령 세트)과 --allowedTools 항목·permissions.allow 규칙이 덮는 행동은 여전히 실행돼요. AskUserQuestion, 조직이 ask로 설정한 커넥터 도구, requiresUserInteraction으로 표시된 MCP 도구는 allow 규칙이 일치해도 거부돼요
  • acceptEdits: Claude가 프롬프트 없이 파일을 쓰고, Claude Code가 mkdir·touch·mv·cp 같은 흔한 파일시스템 명령을 자동 승인해요. 어떤 모드도 자동 승인하지 않는 행동은 여전히 적용돼요. 읽기 전용 명령 세트 외의 다른 셸 명령·네트워크 요청은 여전히 --allowedTools 항목이나 permissions.allow 규칙이 필요해요. 전체 목록은 acceptEdits가 자동 승인하는 것을 보세요.

이 예제는 acceptEdits를 기준으로 린트 수정을 적용해요.

claude -p "Apply the lint fixes" --permission-mode acceptEdits

무인 실행에서 권한 프롬프트 끄기

아무도 권한 프롬프트에 답할 수 없을 때(예약된 작업 등) --permission-prompts none을 전달하세요. 이 플래그는 권한 호스트가 있을 때 가장 중요해요. canUseTool 콜백이 있는 Agent SDK 앱 또는 --permission-prompt-tool로 전달하는 MCP 도구요. 플래그가 없으면 실행이 그 호스트가 각 권한 요청에 답하기를 기다려요.

플래그가 있으면 실행이 호스트를 상담하거나 기다리지 않아요. 프롬프트할 것은 PermissionRequest 훅이 허용하지 않는 한 거부되고, Claude는 아무도 요청을 승인할 수 없으니 재시도하지 말라는 소식을 듣고, 실행은 계속돼요. 호스트가 없는 -p 실행에서 이 요청은 어느 쪽이든 거부되고, 플래그는 Claude에게 재시도하지 말라고도 해요. 권한 규칙·PermissionRequest 훅·설정한 권한 모드가 여전히 각 호출을 먼저 결정하고, Claude Code는 다른 게 해결하지 못한 요청만 거부해요.

이 예제는 auto 모드에서 무인 작업을 실행해요. 분류기가 평소처럼 각 행동을 검토하고, Claude Code가 프롬프트로 폴백했을 것을 거부해요.

claude -p "Update the dependency pins and run the tests" --permission-mode auto --permission-prompts none

--permission-prompts none으로 Claude Code가 사람의 답이 필요한 도구(AskUserQuestion 등)를 제거해 Claude가 그것을 호출할 수 없게 해요. 어떤 Elicitation 훅도 답하지 않는 MCP 유도 요청은 취소돼요.

--output-format stream-json이면 거부가 permission_denied 시스템 메시지로 나타나고, 최종 결과 메시지가 permission_denials에 그것들을 나열해요.

참고: --permission-prompts 플래그는 Claude Code v2.1.259 이상이 필요해요. 이전 버전은 unknown-option 오류로 거부해요.

커밋 만들기

이 예제는 스테이지된 변경을 검토하고 적절한 메시지로 커밋을 만들어요.

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도 일치시킬 수 있거든요.

참고: 사용자가 호출하는 스킬과 커스텀 커맨드는 -p 모드에서 작동해요. 프롬프트 문자열에 /skill-name을 포함하면 Claude Code가 실행 전에 펼쳐요. /login처럼 터미널 인터페이스에서만 실행되는 내장 커맨드는 -p 모드에서 쓸 수 없어요. /model·/effort·/fast·/color·/rename은 값(예: /model sonnet)을 인자로 받아들이고, 인자 없는 /mcp는 서버 상태의 텍스트 요약을 출력해요. 이 형태들은 Claude Code v2.1.205 이상이 필요하고 각 커맨드의 가용성 주석을 따라요. -p 호출에서 설정을 바꾸려면 /config에 key=value를 전달하세요. 예: /config thinking=false.

시스템 프롬프트 사용자화

--append-system-prompt로 Claude Code의 기본 동작을 유지하면서 지시를 추가해요. 이 예제는 PR diff를 Claude에 파이프하고 보안 취약점을 리뷰하라고 지시해요. review.sh 같은 셸 스크립트로 저장하세요.

gh pr diff "$1" | claude -p \
  --append-system-prompt "You are a security engineer. Review for vulnerabilities." \
  --output-format json

스크립트에서 "$1"는 명령줄에 전달한 첫 인자를 뜻해요. bash review.sh 123을 실행하면 셸이 "$1"을 123으로 바꿔 PR 123의 diff를 가져와요. Claude Code가 텍스트를 result 필드에 담아 리뷰를 JSON으로 출력해요.

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

대화 계속

가장 최근 대화를 계속하려면 --continue를, 특정 대화를 계속하려면 세션 ID로 --resume을 쓰세요. Claude Code v2.1.257 이상에서 --continue를 전달하면 Claude Code가 끝난 백그라운드 세션을 열지만, 아직 도는 것은 열지 않아요. 이 예제는 리뷰를 실행한 뒤 후속 프롬프트를 보내요.

# 첫 요청
claude -p "Review this codebase for performance issues"

# 가장 최근 대화 계속
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"

두 명령을 다른 디렉터리에서 실행할 수 있어요. Claude Code가 ID로 세션을 이 머신의 어떤 프로젝트에서도 찾아요. v2.1.223 이전에는 현재 프로젝트 디렉터리와 git 워크트리에서만 ID를 찾았으므로 두 명령을 같은 디렉터리에서 실행해야 했어요.

세션 ID 대신 --resume에 세션의 .jsonl 트랜스크립트 파일의 절대 경로를 전달할 수 있고, Claude Code가 그 파일에 저장된 대화를 계속해요.

더 알아보기