topic★★★★★난이도 · 약 20분

Headless 모드 — 잠자는 동안 AI 일시키기

claude -p 명령어로 대화 없이 프롬프트를 실행하고, 파이프라인·배치 작업에 활용한다.

#Headless#비대화형#배치#자동화#파이프라인

왜 배우는가

대화형 모드는 사람이 앞에 앉아 있어야 한다. Headless 모드를 쓰면 스크립트 안에서 Claude를 호출할 수 있고, 수십 개 작업을 자동으로 돌릴 수 있다.

Headless 모드(비대화형 모드)는 `claude -p "프롬프트"` 형식으로 터미널에서 한 줄 명령으로 Claude를 실행하는 방식이다. 대화 UI 없이 프롬프트를 보내고 결과만 받아온다. 셸 스크립트, cron job, CI/CD 파이프라인 안에서 Claude를 '함수처럼' 호출할 수 있다.

에이전트 루프 (Headless) — 대화 UI 없이 프롬프트→결과만 주고받는 배치 모드

bash

# 기본 사용법 — 프롬프트를 직접 전달
claude -p "이 프로젝트의 README.md를 한국어로 번역해줘"

# 파이프로 입력 전달
cat error.log | claude -p "이 에러 로그를 분석해서 원인을 알려줘"

# 파일 내용을 컨텍스트로 전달
claude -p "이 코드를 리팩토링해줘" < src/legacy.ts

-p 플래그는 'prompt'의 약자. 표준 입력(stdin)으로도 데이터를 전달할 수 있다.

bash

# JSON 출력 — 다른 프로그램과 연동할 때 유용
claude -p "package.json의 의존성을 분석해줘" --output-format json

# 배치 작업 — 여러 파일을 순차 처리
for file in src/components/*.tsx; do
  claude -p "이 컴포넌트의 접근성(a11y)을 점검해줘" < "$file" \
    >> accessibility-report.md
done

--output-format json을 쓰면 구조화된 JSON으로 결과를 받아 jq 등으로 후처리할 수 있다.

옵션	설명	예시
-p	프롬프트 직접 전달 (비대화형)	`claude -p "요약해줘"`
--output-format	출력 형식 지정	`--output-format json`
--model	사용할 모델 지정	`--model claude-sonnet-4-20250514`
--max-turns	최대 에이전트 턴 수 제한	`--max-turns 5`
--allowedTools	허용할 도구 제한	`--allowedTools "Read,Grep"`

실전 팁: Headless 모드는 GitHub Actions, cron job, 또는 다른 AI 에이전트 프레임워크와 결합했을 때 진가를 발휘한다. 예를 들어 매일 새벽 3시에 `claude -p "어제 머지된 PR들을 요약해줘" --output-format json`을 실행하면, 아침에 출근했을 때 자동 생성된 일일 리포트를 확인할 수 있다.