비대화 모드(-p)로 스크립트에서 실행하기

매일 새벽 회의록을 정리하거나 커밋 전에 오타를 검사하는 일에 사람이 터미널 앞에 앉아 있을 필요는 없습니다. claude -p는 프롬프트를 넘기고 결과만 받아 종료하는 비대화 모드이며, 스크립트·크론·CI에서 Claude Code를 부르는 진입점입니다. 이 코스의 마지막 글로, 우리 초급 과정 7주차의 "반복 업무 무인화"가 바로 이 모드 위에서 돌아갑니다.

핵심 요약

• claude -p "프롬프트"는 응답을 출력하고 종료합니다. 모든 CLI 옵션이 -p와 함께 동작합니다.
• 출력 형식은 text(기본), json, stream-json 세 가지이며 --json-schema로 구조를 강제할 수 있습니다.
• 권한 프롬프트를 받아 줄 사람이 없으므로 --allowedTools나 --permission-mode로 미리 허용 범위를 정합니다.
• stdin으로 데이터를 파이프할 수 있고(10MB 제한), --continue·--resume으로 이전 실행을 이어 갑니다.
• 각 호출은 독립 세션이며 토큰은 대화 모드와 똑같이 소비됩니다.

대화 모드와 무엇이 다른가

대화 모드는 사람이 매 턴 개입하는 루프이고, 비대화 모드는 사람 없이 한 번 돌고 끝나는 루프입니다. 그래서 권한 확인이 나오면 답할 사람이 없어 멈추므로 허용 범위를 미리 정해야 하고, /login처럼 대화창을 여는 명령은 쓸 수 없으며, 결과를 프로그램이 파싱하므로 출력 형식이 중요합니다. 공식 문서는 이 모드를 Agent SDK의 CLI 형태로 설명하며 같은 루프를 Python과 TypeScript 패키지로도 제공합니다.

기본 사용법은 어떻게 되나

claude -p "이 프로젝트의 접수 API가 하는 일을 요약해 줘"

-p는 --print의 축약입니다. 기본으로는 대화형 세션과 같은 컨텍스트(CLAUDE.md, 훅, 스킬, MCP, 자동 메모리)를 로드합니다. 머신마다 같은 결과가 필요한 CI에서는 --bare를 붙여 자동 검색을 건너뛰고 필요한 것만 --settings, --mcp-config 같은 플래그로 넘깁니다. 공식 문서는 --bare를 스크립트의 권장 모드로 안내하며 향후 -p의 기본값이 될 예정이라고 밝힙니다. --bare는 키체인을 읽지 않으므로 인증은 ANTHROPIC_API_KEY나 --settings의 apiKeyHelper로 넘깁니다.

모델 지정 · --model

claude -p "이 diff를 한 줄로 요약해 줘" --model haiku

별칭 sonnet, opus, haiku, fable 또는 전체 모델명을 씁니다. 우리 6주차의 모델 나눠 쓰기를 자동화에 옮기면 요약·분류 배치는 haiku나 sonnet, 코드 수정은 opus입니다. --effort low로 추론 강도를 낮추는 것도 배치 비용을 줄입니다.

확인 없이 쓸 도구 지정 · --allowedTools

claude -p "테스트를 실행하고 실패를 고쳐 줘" \
  --allowedTools "Bash(pnpm test *),Read,Edit"

권한 규칙 구문을 그대로 씁니다. Bash(git diff *)처럼 공백과 *를 붙이면 접두 일치이고, 공백이 없으면 git diff-index까지 잡히므로 주의합니다. 반대로 --disallowedTools "WebSearch"로 도구를 빼거나 --tools "Read,Grep"로 내장 도구 자체를 제한합니다. 우리 7주차의 "운영 DB는 성역"은 --disallowedTools "Bash(psql *)" 같은 거부 규칙으로 구현됩니다.

출력 형식은 어떻게 고르나

claude -p "이 프로젝트를 요약해 줘" --output-format json | jq -r '.result'

특정 구조가 필요하면 --json-schema를 함께 씁니다. 결과는 structured_output 필드에 들어가며, 스키마가 잘못되면 Error: --json-schema is not a valid JSON Schema로 종료합니다.

claude -p "회의록에서 할 일을 뽑아 줘" --output-format json \
  --json-schema '{"type":"object","properties":{"todos":{"type":"array","items":{"type":"string"}}},"required":["todos"]}' \
  | jq '.structured_output'

스트리밍은 --output-format stream-json --verbose --include-partial-messages이며 마지막 줄이 최종 결과와 비용을 담은 result 메시지입니다.

커스텀 커맨드를 스크립트에서 호출하려면

사용자가 만든 스킬과 커스텀 커맨드는 -p에서도 동작합니다. 프롬프트 문자열에 /스킬이름을 넣으면 실행 전에 확장됩니다(v2.1.205 이상).

claude -p "/meeting-notes ./recordings/2026-08-27.m4a"

우리 3주차 실습의 녹음 회의록 변환기를 스킬로 만들어 두면 이 한 줄이 새벽 크론 작업이 됩니다. /model, /effort처럼 값을 받는 내장 명령도 인수와 함께 쓸 수 있으며, 비대화 모드에서 바꾼 모델·설정은 그 세션에만 적용됩니다.

권한 확인을 전부 건너뛰기 · --dangerously-skip-permissions

claude -p "린트 수정을 적용해 줘" --dangerously-skip-permissions

--permission-mode bypassPermissions와 같습니다. 공식 문서는 인터넷이 차단된 컨테이너나 VM 같은 격리 환경에서만 쓰라고 경고하며 프롬프트 주입 보호가 없다고 명시합니다. root나 sudo로는 시작이 거부됩니다. 대안으로 --permission-mode acceptEdits는 파일 편집과 mkdir·mv 같은 파일 명령만 자동 승인하고, dontAsk는 permissions.allow에 없는 것을 모두 거부해 잠긴 CI에 맞습니다. 우리 권장 순서는 allow 규칙 → acceptEdits → dontAsk이며 bypass는 격리 환경에서만입니다.

파이프와 조합하면 무엇이 가능한가

비대화 모드는 stdin을 읽고 stdout으로 씁니다. 다른 유닉스 도구처럼 앞뒤에 붙일 수 있습니다.

# 빌드 오류 설명을 파일로
cat build-error.txt | claude -p '이 빌드 오류의 근본 원인만 간단히 설명해 줘' > output.txt

# 커밋 전 오타 검사
git diff main | claude -p "오타 검사기다. 오타마다 파일명:줄 한 줄, 문제 한 줄만 출력해라."

diff를 파이프로 넘기면 Claude가 읽기 위해 Bash 권한이 필요 없다는 점이 요령입니다. 파이프된 stdin은 10MB로 제한되므로 큰 입력은 파일로 쓰고 경로를 프롬프트에 적습니다.

그 밖에 알아 둘 옵션

• --max-turns N: 에이전트 턴 수 상한. 기본은 제한 없음.
• --max-budget-usd: API 지출 상한(인쇄 모드 전용).
• --no-session-persistence: 이번 실행을 디스크에 남기지 않음.
• --fallback-model sonnet,haiku: 기본 모델 과부하 시 순서대로 대체.

주의할 점은 무엇인가

각 호출은 독립된 세션이다

claude -p를 두 번 실행하면 두 번째는 첫 번째를 모릅니다. 이어 가려면 --continue(같은 디렉토리의 최근 세션) 또는 --resume <세션 ID>를 씁니다.

claude -p "성능 문제를 검토해 줘"
claude -p "이번엔 DB 쿼리에 집중해 줘" --continue

sid=$(claude -p "검토 시작" --output-format json | jq -r '.session_id')
claude -p "그 검토를 이어서" --resume "$sid"

--continue는 같은 폴더의 최근 세션을 찾으므로 같은 폴더에서 실행하고, --resume <세션 ID>는 v2.1.223부터 폴더와 무관하게 재개할 수 있습니다. -p로 만든 세션은 /resume 선택기에 나오지 않지만 ID로는 재개됩니다. 실행 중 띄운 백그라운드 셸은 결과 반환 약 5초 뒤 종료됩니다.

토큰은 똑같이 소비된다

비대화라고 싸지 않습니다. 대화 모드와 같은 컨텍스트를 로드하고 요금제 한도(5시간·주간 윈도우)도 똑같이 차감됩니다. 배치 작업은 --bare로 시작 컨텍스트를 줄이고, 가벼운 모델과 낮은 effort를 쓰며, JSON 출력의 total_cost_usd로 호출당 비용을 로그에 남깁니다. 자동 모드에서 분류기가 반복 차단하면 물어볼 사람이 없어 실행이 중단된다는 점도 기억합니다.

정리

• claude -p는 결과만 받고 끝나는 루프이며 모든 CLI 옵션과 함께 씁니다.
• 파싱은 --output-format json과 --json-schema, 권한은 --allowedTools·--permission-mode로 미리 정합니다.
• 스킬은 프롬프트에 /이름으로 넣어 실행하고, 위험 명령은 거부 규칙으로 막습니다.
• 파이프 입력은 10MB까지, 이어 가기는 --continue·--resume.
• CI와 스크립트는 --bare가 권장이며 비용은 대화 모드와 같습니다.

자주 묻는 질문