Claude Code를 「부품」으로 사용하기 | claude -p 명령어 사용법과 5가지 유스케이스

claude -p는 Claude Code의 **비대화형 원샷 실행 모드 (non-interactive one-shot execution mode)**입니다.

일반적인 claude 명령어와 무엇이 다른지 한마디로 말하자면 "Claude를 툴체인 (toolchain)의 부품으로 사용할 수 있다"는 점입니다.

이 기사에서는 claude -p의 기초부터 CI/CD로의 통합까지, 실제 유스케이스를 곁들여 해설합니다. git diff | claude -p "리뷰해줘"로 바로 시도해 볼 수 있습니다.

• claude -p는 프롬프트 (prompt)를 전달하고 결과를 반환하기만 하는 1회 완결 모드
• git diff | claude -p "리뷰해줘"가 가장 심플한 사용법
• CI/CD나 쉘 스크립트 (shell script)에 통합하기에 최적
• --allowedTools로 권한을 제한하는 것이 안전한 사용법
• 인터랙티브 (interactive)한 리뷰에는 /code-review가 더 편리

2026/6/15~ claude -p는 구독 범위와는 별개의 크레딧제로 이행

claude -p "질문이나 태스크"

-p는 --print의 약자로, 프롬프트를 전달하여 응답을 출력하고 즉시 종료합니다.

구분	일반 모드	-p 모드
대화성	여러 턴의 대화	1회 실행 후 종료
용도	개발 중 탐색·수정	스크립트·자동화
적합한 상황	시행착오·심층 탐구	반복·타 도구 연동

**"Claude를 부품으로 사용할 수 있다"**는 점이 핵심입니다.

# 다른 명령어와 파이프 (pipe)로 연결
git diff | claude -p "이 diff를 리뷰해줘"
tail -f app.log | claude -p "에러 원인을 알려줘"
...

일반적인 claude는 인터랙티브하게 사용하는 것. claude -p는 자동화를 위한 도구입니다.

# 차이점(diff)을 리뷰하게 함
git diff | claude -p "이 diff의 보안 문제를 지적해줘"
# 스테이지(stage)된 변경 사항에서 커밋 메시지(commit message)를 생성
...

git diff | claude -p는 가장 심플하고 효과적인 패턴입니다. 우선 이것부터 시도해 보세요.

# 에러 로그 진단
tail -100 app.log | claude -p "에러 원인을 알려줘" > analysis.txt
# 코드 설명
...

파일 전체를 전달하여 Claude에게 해석하게 할 수 있습니다.

# 테스트 실패 시 수정안 제시
TEST_OUTPUT=$(npm test 2>&1 || true)
echo "$TEST_OUTPUT" | claude -p "테스트 실패 원인과 수정안을 알려줘"
...

정형화된 작업의 자동화에 적합합니다.

# PR(Pull Request) 자동 리뷰
- name: 코드 리뷰
run: |
  gh pr diff ${{ github.event.pull_request.number }} | \
  ...

PR이 생성될 때마다 자동으로 리뷰 코멘트를 게시하는 메커니즘을 만들 수 있습니다.

# 구조화된 데이터 추출
cat report.txt | \
claude -p "문제점을 추출해줘" --output-format json | \
jq -r '.result'

옵션	설명
--output-format text	텍스트 (기본값)
--output-format json	구조화된 출력, 후속 처리에 최적
--output-format stream-json	실시간 스트리밍 (--verbose와 병용)

claude -p는 기본적으로도 권한 확인이 있습니다. 다만 비대화 모드이므로, 확인 창이 뜨면 **처리가 블록 (block)**됩니다.

# 사용할 도구를 명시적으로 지정 → 해당 도구는 확인 없이 실행
claude -p "차이점을 리뷰해줘" \
--allowedTools "Bash(git *),Read"

# 편집 계열은 자동 허용
claude -p "태스크" --permission-mode acceptEdits
# 모두 자동 허용
...

--dangerously-skip-permissions

--dangerously-skip-permissions는 이름 그대로 위험하므로, 신뢰할 수 있는 스크립트 내부에서만 사용하십시오.

claude --bare \
-p "タスク内容" \
--output-format json \
...

플래그	목적
--bare	고속 실행 (컨텍스트 로딩 스킵)
--output-format json	후속 처리에서 분석하기 용이함
--max-turns	폭주 방지
--allowedTools	권한을 최소한으로 제한
--max-budget-usd	비용 상한 설정

claude -p를 사용하기 전에 알아두어야 할 중요한 변경 사항이 있습니다.

2026년 6월 15일부터, claude -p와 같은 자동화·에이전트(Agent) 계열 이용은 구독(Subscription) 범위와 별개의 크레딧(Credit)제로 분리됩니다.

이용 방법	6/15 이후 처리
claude.ai 채팅	기존과 동일하게 구독 범위
터미널·IDE의 일반적인 Claude Code	기존과 동일하게 구독 범위
claude -p (비대화형 모드)	별도 크레딧 범위
Agent SDK / GitHub Actions	별도 크레딧 범위

플랜	월액	월간 크레딧
Pro	$20	$20 상당
...

• 크레딧은 월말 리셋 (이월 불가)
• 팀 멤버와 공유·풀링 불가 (개인 단위)
• 크레딧을 모두 사용하면 다음 과금 주기까지 자동화 기능이 정지

Pro 플랜에서 claude -p를 사용하는 경우, 월 $20 상당의 토큰 소비가 상한선이 됩니다. 단순한 git diff 리뷰나 로그 분석 정도라면 충분하지만, 대규모 파일 분석이나 CI/CD에서 빈번하게 실행하는 경우에는 주의가 필요합니다.

"claude -p로 코드 리뷰를 할 수 있다면, /code-review 명령어는 필요 없는 거 아닌가?"라고 생각할 수도 있습니다. 용도가 다릅니다.

상황	사용하는 것
수동으로 코드 리뷰를 하고 싶을 때	/code-review
...

인터랙티브(Interactive)한 리뷰라면 /code-review가 훨씬 편리합니다.

claude -p는 어디까지나 "자동화를 위한 도구"로서 구분하여 사용합시다.

• claude -p는 "Claude를 커맨드라인 도구(CLI Tool)로 사용하기" 위한 플래그
• git diff | claude -p로 시작하는 것이 가장 단순함
• CI/CD에 통합할 경우 --allowedTools로 권한을 제한하는 것이 안전함
• 인터랙티브한 리뷰에는 /code-review가 더 적합함
• --output-format json과 jq의 조합으로 유연한 후속 처리 가능

2026/6/15~ 자동화 이용은 별도 크레딧 범위로 이행 (Pro = $20/월이 상한)

Claude Code를 "대화 상대"로서뿐만 아니라 "자동화의 부품"으로서 사용할 수 있다면, 일상의 반복 작업이 단번에 편해집니다.