쉽게 배우는 Claude Code ⑫ claude -p (헤드리스 모드) — 스크립트·자동화에서 Claude 쓰기

지금까지 우리는 Claude Code를 켜 놓고 마주 앉아 대화하듯 써 왔습니다. 그런데 가끔은 사람이 화면 앞에 앉아 있을 수 없는 상황이 있습니다. 예를 들어 CI 파이프라인이 한밤중에 돌아갈 때, 혹은 로그 파일이 쌓일 때마다 자동으로 요약을 받아 보고 싶을 때처럼요.

이럴 때 쓰는 게 claude -p, 헤드리스(headless) 모드입니다. 대화 화면을 띄우지 않고, 질문을 한 번 처리한 다음 결과만 출력하고 바로 종료합니다. 이번 편에서 그 사용법을 쉽게 정리해 보겠습니다.

---

한 줄로

claude -p "..."는 대화형 화면 없이, 질문을 한 번 처리하고 결과를 출력한 뒤 끝내는 비대화형(헤드리스) 모드입니다.

-p는 --print의 줄임말입니다. 셸 파이프(|)와 궁합이 좋아서, 스크립트·CI·자동화에 잘 맞습니다.

---

언제 쓰나

핵심은 “사람이 앉아서 대화하는 게 아니라, 명령 한 번 → 결과 받기를 자동화할 때”입니다. 몇 가지 예를 보겠습니다.

★ 예제 1 — 로그 파일을 파이프로 넘겨 원인 요약 받기

에러 로그를 그냥 사람이 읽으면 시간이 오래 걸리죠. 파일 내용을 파이프로 넘기면 한 줄 명령으로 원인 요약을 받을 수 있습니다.

cat error.log | claude -p "이 에러 원인 요약해줘"

여기에 슬랙으로 올리는 명령까지 붙이면, 로그가 생길 때마다 요약을 자동으로 채널에 올리는 스크립트가 됩니다.

★ 예제 2 — CI에서 변경된 파일 요약 자동 생성

PR이 올라올 때마다 변경 내용을 사람이 매번 정리하긴 번거롭습니다. CI 단계에서 변경 파일 목록(diff)을 넘겨 요약을 자동으로 만들어 둘 수 있습니다.

git diff --name-only main | claude -p "이번 변경에서 바뀐 파일들의 핵심을 요약해줘"

CI는 사람이 지켜보지 않는 환경이라, 화면을 띄우지 않는 헤드리스 모드가 딱 맞습니다.

★ 예제 3 — 여러 파일에 같은 작업을 반복문으로 적용

같은 종류의 변환을 파일 여러 개에 똑같이 적용해야 할 때, 셸 반복문과 함께 쓰면 편합니다.

for f in src/*.md; do
  cat "$f" | claude -p "이 문서의 첫 문단을 한 문장 요약으로 바꿔줘"
done

파일마다 사람이 일일이 명령을 입력하지 않아도, 한 번에 죽 돌릴 수 있습니다.

---

어떻게

기본형은 아주 단순합니다. 질문을 따옴표로 감싸 넘기면 됩니다.

claude -p "이 프로젝트의 README를 세 줄로 요약해줘"

표준 입력(stdin)으로 내용을 함께 넘기고 싶으면 파이프를 씁니다.

cat report.txt | claude -p "핵심만 불릿 3개로 정리해줘"

출력 형식 지정 — --output-format

스크립트에서 결과를 프로그램으로 다루려면, 출력 형식을 지정하는 게 좋습니다.

cat error.log | claude -p "원인을 요약해줘" --output-format json

값	설명	언제
text	사람이 읽기 좋은 일반 텍스트 (기본)	그냥 결과만 보면 될 때
json	기계가 파싱하기 좋은 JSON	결과를 프로그램에서 다룰 때
stream-json	이벤트를 JSON으로 스트리밍	진행 과정을 실시간으로 받아야 할 때

json으로 받으면 jq 같은 도구로 필요한 값만 뽑아 쓰기 좋습니다. 길게 도는 작업의 진행 상황을 실시간으로 보고 싶다면 stream-json을 쓰면 됩니다.

---

팁 & 함정

• 호출 사이에 맥락이 누적되지 않습니다. -p 모드는 호출 사이에 프롬프트 캐시가 유지되지 않아, 대화형처럼 앞 대화가 이어지지 않습니다. 매 호출이 독립적이라고 생각하면 됩니다. “방금 보여준 코드 말이야…” 같은 식으로 이어 말하면 통하지 않습니다.
• 맥락을 이어가야 한다면 대화형 모드를 쓰거나, --continue와 조합해서 이전 대화를 이어가도록 하세요.
• 자동화에는 json / stream-json을 권합니다. 사람 눈으로 읽을 게 아니라 프로그램이 결과를 다룰 거라면, 텍스트보다 구조화된 출력이 훨씬 안전합니다.
• 질문은 따옴표로 명확히 감싸세요. 셸에서 공백이나 특수문자 때문에 명령이 엉키는 일을 줄일 수 있습니다.

---

한 장 정리

항목	내용
무엇	대화 화면 없이 한 번 처리하고 끝내는 비대화형(헤드리스) 모드
명령	claude -p "..." (= claude --print)
기본 사용	cat error.log | claude -p "이 에러 원인 요약해줘"
출력 형식	--output-format <text|json|stream-json>
언제	명령 한 번 → 결과 받기를 자동화할 때 (스크립트·CI)
주의	호출마다 맥락 독립적. 이어가려면 --continue

다음 편: /mcp — 외부 도구(GitHub·DB 등) 연결하기.