# claude -p로 스크립트 돌리기
id: claude-code-headless · 종류: 워크플로 · 상태: 검수 대기 (사람 확인 전) · 주제: 개발
주소: https://opencurrent.ai/w/claude-code-headless
기준일: 2026-11-21 (여기서 고친 날)
도구: Claude Code
걸리는 시간: 약 15분
평가 점수: 32/100 (확인 없음 · 검수 대기)

claude -p 헤드리스 모드로 Claude Code를 스크립트·CI·빌드 명령 안에서 돌려, 대화창을 열지 않고도 리뷰·요약·수정 같은 일을 자동으로 맡길 수 있습니다.

설명: -p로 한 번 실행하고 결과를 text나 json으로 받습니다. 사람이 승인할 수 없는 실행이므로 --allowedTools와 --permission-mode로 할 수 있는 일을 정하고, --max-turns·--max-budget-usd로 한도를 둡니다. 명령과 설정 이름은 2026년 11월 21일에 Claude Code 공식 문서로 확인했습니다.

준비물: Claude Code 설치와 로그인

단계:
1. [명령 실행 · Claude Code] 한 번 실행 — -p 뒤에 요청을 줍니다. 파이프로 받은 내용도 함께 넘길 수 있고, 최대 10MB까지입니다.
   프롬프트:
   > cat build-error.txt | claude -p '이 빌드 오류의 원인을 짧게 설명해 줘' > why.txt
   기대 결과: why.txt의 설명
   확인 방법: 명령의 종료 코드가 0인지 확인(echo $?)
2. [명령 실행 · Claude Code] 할 수 있는 도구 정하기 — -p 실행은 아무것도 정하지 않으면 승인이 필요한 동작이 거절됩니다. 필요한 도구만 --allowedTools로 열어 줍니다.
   프롬프트:
   > claude -p "테스트를 돌리고 실패를 고쳐 줘" --allowedTools "Bash(npm test *),Read,Edit"
   기대 결과: 테스트를 고친 변경
   확인 방법: git diff로 고친 내용 확인
3. [명령 실행 · Claude Code] JSON으로 받기 — --output-format json이면 결과(result)와 세션 id가 함께 옵니다. jq로 결과만 꺼내 다음 명령에 넘깁니다.
   프롬프트:
   > claude -p "이 프로젝트를 세 줄로 요약해 줘" --output-format json | jq -r '.result'
   기대 결과: 요약 세 줄
   확인 방법: 출력이 JSON이 아니라 요약 글인지 확인
4. [명령 실행 · Claude Code] 한도 두기 — 자동 실행이 끝없이 돌지 않게 턴 수와 금액 한도를 줍니다.
   프롬프트:
   > claude -p --max-turns 5 --max-budget-usd 2.00 "README의 오래된 설치 안내를 고쳐 줘"
   기대 결과: 한도 안에서 끝난 실행
   확인 방법: 실행이 한도에 닿으면 멈추는지 확인
5. [명령 실행 · Claude Code] 이어서 실행 — 앞 실행의 세션 id로 이어 갑니다. 같은 폴더의 가장 최근 대화는 --continue로 이어집니다.
   프롬프트:
   > sid=$(claude -p "리뷰를 시작해 줘" --output-format json | jq -r '.session_id')
   > claude -p "이어서 보안 문제만 다시 봐 줘" --resume "$sid"
   기대 결과: 앞 대화를 이은 결과
   확인 방법: 두 번째 답이 첫 리뷰 내용을 이어받는지 확인

주의:
- --dangerously-skip-permissions(bypassPermissions)는 격리된 컨테이너·VM에서만
- 스크립트용으로는 --bare를 권장(훅·스킬·플러그인·MCP·CLAUDE.md를 건너뜀). 대신 ANTHROPIC_API_KEY 필요
- CI에서 API 키로 돌리면 실행마다 요금 발생

출처:
- Claude Code 문서: 프로그램으로 실행하기 https://code.claude.com/docs/en/headless
- Claude Code 문서: CLI 레퍼런스 https://code.claude.com/docs/en/cli-reference