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

비대화 모드는 대화형 인터페이스를 띄우지 않고 -p 옵션으로 프롬프트를 넘겨 결과만 받고 종료하는 Claude Code 실행 방식입니다. UI 없이 처리를 끝내기 때문에 셸 스크립트에서 호출하거나 다른 명령과 파이프로 연결하는 배치 처리와 잘 맞습니다.

핵심 요약

• claude -p "프롬프트" 로 비대화 실행이 가능하고, 결과는 표준 출력으로 나옵니다.
• --output-format 으로 text·json·stream-json 중 출력 형식을 고를 수 있습니다.
• --allowedTools 로 확인 없이 쓸 도구를 미리 승인해 스크립트가 멈추지 않게 합니다.
• 커스텀 커맨드(/xxx)도 -p 로 호출할 수 있습니다.
• 표준 입출력과 파이프로 연동해 로그 분석·테스트 요약·diff 리뷰에 쓸 수 있습니다.

대화 모드와 무엇이 다른가

통상적인 Claude Code는 터미널에서 실시간으로 대화하며 코드를 편집하는 것이 기본입니다. 비대화 모드는 프롬프트를 넘기고 결과를 받는 단순한 흐름으로, 대화 모드에 들어가지 않고 바로 종료합니다.

기본 사용법은 어떻게 되나

-p(또는 --print) 옵션으로 프롬프트를 넘기기만 하면 동작합니다.

claude -p "이 프로젝트의 README.md를 읽고 개요를 설명해줘"

Claude Code는 프롬프트를 처리한 뒤 결과를 표준 출력에 쓰고 종료합니다.

모델 지정 — --model

claude -p "코드를 리뷰해줘" --model opus

지정할 수 있는 모델명은 opus, sonnet 등입니다. 모델별 특성은 모델 고르기를 참고하세요.

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

자동화 스크립트에서는 도구를 쓸 때마다 확인 프롬프트가 뜨면 처리가 멈춥니다. --allowedTools 로 지정한 도구는 확인 없이 실행됩니다.

claude -p "코드를 분석해 문제점을 보고해줘" --allowedTools "Read,Grep,Glob"

이 예는 파일 읽기와 검색만 확인 없이 허용합니다. 주의할 점은 --allowedTools 가 어디까지나 확인 프롬프트를 생략하기 위한 사전 승인이라는 것입니다. 목록에 없는 도구도 설정된 권한 규칙을 따르면 계속 호출될 수 있습니다. 도구 사용 자체를 금지하려면 뒤에서 설명하는 --disallowedTools 를 씁니다. 권한 규칙의 전체 구조는 퍼미션 설정 최적화에서 다룹니다.

출력 형식은 어떻게 고르나

용도에 맞게 --output-format 으로 출력 형식을 선택합니다.

# 텍스트(기본값)
claude -p "버그를 찾아 보고해줘" --output-format text

# JSON
claude -p "코드의 문제점을 분석해줘" --output-format json

JSON 형식의 출력 예는 다음과 같습니다. session_id 를 받아 두면 나중에 --resume 으로 이어갈 수 있습니다.

{
  "type": "result",
  "subtype": "success",
  "result": "분석 결과 텍스트...",
  "session_id": "abc123",
  "total_cost_usd": 0.003
}

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

.claude/commands/ 에 둔 Markdown 파일은 슬래시 커맨드가 됩니다.

.claude/commands/
├── create-review.md     → /create-review
├── generate-docs.md     → /generate-docs
└── analyze-code.md      → /analyze-code

이 커맨드도 -p 로 실행할 수 있습니다. 인수는 커맨드명 뒤에 스페이스로 구분해 넘기고, 커맨드 파일 안에서는 $ARGUMENTS 나 $1, $2 로 참조합니다.

claude -p "/create-review src/main.ts"

커맨드 작성법은 커스텀 커맨드 입문, 인수 처리는 $ARGUMENTS 로 인수 받기, allowed-tools 같은 설정은 커스텀 커맨드 프론트매터를 참고하세요.

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

자동화에서 권한 확인이 방해가 될 때 --dangerously-skip-permissions 를 쓰면 모든 권한 확인을 건너뜁니다.

claude -p "/my-command" --dangerously-skip-permissions

이 옵션은 이름 그대로 위험합니다. 모든 도구 실행이 자동 승인되므로 신뢰할 수 있는 커맨드에서만 사용하세요. 위험한 조작을 피하고 싶다면 --disallowedTools 로 해당 도구나 명령을 명시적으로 거부해 두는 편이 좋습니다.

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

비대화 모드는 표준 입력에서 데이터를 받고 표준 출력으로 결과를 내보내므로 Unix 파이프와 자연스럽게 연결됩니다.

# 파일 내용 분석
cat error.log | claude -p "이 에러 로그의 원인을 분석해줘"

# 명령 출력 분석
npm run test 2>&1 | claude -p "테스트 결과를 요약해줘"

# 커밋 전 변경 내용 리뷰
git diff | claude -p "이 변경 내용을 리뷰해줘"

실무에서는 커밋 전 git diff 리뷰를 셸 함수로 묶어 두면 손이 덜 갑니다. Git 연동의 다른 활용은 Git 조작 자동화를 참고하세요.

그 밖에 알아 둘 옵션

직전 세션을 이어가려면 --continue 를 함께 지정합니다.

claude -p "아까 그 코드에 테스트를 추가해줘" --continue

세션을 다루는 방법 전반은 세션 관리에서 다룹니다.

주의할 점은 무엇인가

각 호출은 독립된 세션이다

비대화 모드의 호출은 기본적으로 서로 독립된 세션으로 취급됩니다. 이전 실행 결과를 이어받으려면 --continue 나 --resume 을 명시해야 합니다.

토큰은 똑같이 소비된다

비대화 모드에서도 통상대로 토큰이 소비됩니다. 대량의 파일을 분석하거나 빈번히 실행한다면 비용을 의식하는 편이 좋습니다. "필요한 파일만 대상으로 한다", "--allowedTools 로 읽기 전용 도구만 확인 없이 허용한다" 같은 방법으로 비용을 억제할 수 있습니다.

정리

• -p 옵션으로 비대화 실행이 가능하며, 결과는 표준 출력으로 나와 스크립트에서 받기 좋습니다.
• --output-format json 으로 세션 ID·비용까지 받아 후속 처리에 쓸 수 있습니다.
• --allowedTools 는 확인 생략용 사전 승인이고, 금지는 --disallowedTools 로 합니다.
• 커스텀 커맨드도 -p 로 호출할 수 있고, 파이프로 로그·테스트·diff 를 넘길 수 있습니다.
• 처음에는 읽기 전용 도구(Read, Grep, Glob)만 허용한 상태에서 시험해 보세요. 자동화를 더 확장하려면 훅(Hooks)도 함께 보면 좋습니다.