핵심 요약
- claude -p "prompt"는 한 번 실행하고 결과를 출력합니다 — 대화형 세션 없이. 어떤 Unix 도구처럼도 조합됩니다: 파이프로 넣고, 파이프로 뱉고, 스크립트와 CI 단계에 이어 붙입니다.
- --output-format json은 결과와 함께 session_id, 비용, 메타데이터를 돌려줍니다. stream-json은 실시간 소비자를 위해 줄바꿈 구분 이벤트를 내보냅니다. jq로 파싱하고 그 위에 쌓으세요.
- 헤드리스는 기본값으로 편집·파괴 권한이 없습니다. --allowedTools "Bash(git diff *),Edit"로 필요한 것만 정확히 허용하세요 — 권한 규칙 문법, 접두 매칭.
- @claude GitHub Action은 프런트엔드를 얹은 헤드리스 모드입니다: 이슈나 PR에 @claude를 태그하면 코드를 읽고, PR과 커밋을 만들고, 질문에 답하고, 코드를 리뷰합니다 — 당신의 GitHub 러너 위에서.
Building headless automation with Claude Code | Code w/ Claude
채널: Anthropic20:59
Headless mode — official documentation
공식 문서: code.claude.com/docs
Claude Code GitHub Action — official docs
공식 문서: code.claude.com/docs
이 페이지의 플래그, 한계, 동작은 공식 헤드리스 문서와 대조해 검증했습니다. 위의 강연은 Anthropic 자체 워크스루이며 스크린샷의 시각 자료입니다.
스크린샷의 권리는 각 제작자에게 있으며, 해당 타임스탬프로 바로 연결됩니다. 발표자·청중 장면은 사용하지 않았습니다.
Claude Code 헤드리스로 실행하기, 단계별로
파트 1 — 헤드리스 기초
- 1
헤드리스 모드란
헤드리스 모드는 대화형 UI 없는 Claude Code입니다: 같은 에이전트를 프로그램적으로 구동합니다. Anthropic은 이를 에이전트형 애플리케이션의 단순한 빌딩 블록으로 소개합니다 — 스크립트와 파이프라인 안의 Unix 도구처럼, CI 자동화나 원격 환경에, 또는 웹 챗 인터페이스의 엔진으로.
Anthropic의 정의 그대로: SDK는 헤드리스 환경의 Claude Code에 대한 프로그래매틱 접근입니다.2:10부터 시청 - 2
claude -p로 원샷 실행
-p(--print) 플래그는 프롬프트 하나를 실행하고 종료합니다: claude -p "Write me a function that calculates the Fibonacci sequence". 아무것도 열어 두지 않습니다 — 출력은 stdout으로, 스크립트가 확인할 수 있는 종료 코드와 함께 나옵니다. 쓰기 권한은 --allowedTools로 미리 부여하세요.
원샷 요청: claude -p가 피보나치 함수를 만들고 종료 — TUI도, 후속 질문도 없이.3:30부터 시청 - 3
파일을 파이프로 Claude에 바로 넣기
stdin은 아무 CLI 도구와 똑같이 작동합니다: cat app.log | claude -p "summarize the most common error logs". Anthropic 데모에서는 2,000줄의 로그가 들어가 일상어 오류 요약이 나옵니다 — 빌드 실패, 스택 트레이스, 내보내기 파일에도 같은 기술이 통합니다. 파이프 stdin은 10MB까지입니다.
cat과 파이프 기호와 claude -p: 2,000줄의 로그가 세 문장짜리 진단이 됩니다.3:55부터 시청 - 4
읽기 싫은 출력 해독시키기
같은 패턴으로 거친 출력이 답으로 바뀝니다: ifconfig | claude -p "what interfaces do I have configured? don't include lo". 명령이 출력하는 무엇이든 — 네트워크 상태, 컴파일러 에러, terraform 플랜 — 사람용 요약을 위해 Claude에 흘려보낼 수 있습니다.
claude -p로 파이프된 ifconfig: 모든 인터페이스 설명, 루프백은 요청대로 제외.4:15부터 시청 - 5
구조화된 JSON 받기
--output-format json을 붙이면 응답이 파싱 가능한 객체가 됩니다: 결과 텍스트, session_id, 소요 시간, total_cost_usd. 실시간 소비자에게는 --output-format stream-json이 생기는 대로 줄바꿈 구분 이벤트를 내보냅니다 — 마지막 줄이 최종 결과입니다.
JSON 모드: 결과와, 나중에 재개할 수 있는 세션 id, 그리고 이번 실행의 비용이 한 덩어리로.4:35부터 시청
파트 2 — 엔지니어답게 스크립트하기
- 6
도구는 의도적으로 허용하기
헤드리스는 편집·파괴 권한 없이 시작합니다. --allowedTools는 과제에 필요한 것을 미리 승인합니다. 권한 규칙 문법으로: --allowedTools "Bash(npm run build),Bash(npm test:*),Write". MCP 도구도 같은 방식으로 허용 목록에 올릴 수 있습니다 — 일을 끝내는 가장 좁은 집합만 주세요.
SDK 심층: 도구 권한, 구조화 출력 모드, 커스텀 시스템 프롬프트가 한 장의 슬라이드에.11:00부터 시청 - 7
실행을 넘어 컨텍스트 유지하기
JSON 모드는 session_id를 돌려줍니다 — 이를 --resume "$session_id"로 넘기면 나중 실행이나 다른 프로세스에서 같은 대화 상태를 이어갑니다. 이 위에 대화형 제품을 만드는 방법이 바로 이것입니다: 사용자가 말하면, Claude가 답하고, 다음 턴을 위해 세션을 보존합니다.
- 8
권한 확인을 사람 없이 처리하기
Claude가 어떤 도구를 쓸지 예측할 수 없다면, --permission-prompt-tool이 승인 결정을 실행 시점에 MCP 서버로 넘깁니다 — 그 도구가 당신의 서비스(또는 앱을 통한 사용자)에게 각 행동의 허용 여부를 물어줍니다. 모든 것을 미리 나열할 필요가 없습니다.
- 9
CI에서는 --bare로
--bare는 hooks, skills, 커스텀 명령, 서브에이전트, 플러그인, MCP 서버, CLAUDE.md의 자동 탐색을 건너뛰어 최속 기동을 만듭니다 — 스크립트와 CI에 권장되며 -p의 기본값이 될 예정입니다. ANTHROPIC_API_KEY가 필요하고, 컨텍스트는 플래그로 명시적으로 전달합니다.
파트 3 — @claude GitHub Action
- 10
@claude GitHub Action 만나기
GitHub Action은 SDK 위에 프런트엔드를 얹은 헤드리스 모드입니다. 아무 PR이나 이슈에 @claude를 태그하면 코드를 읽고, PR을 만들고, 기존 PR에 커밋을 얹고, 질문에 답하고, 변경을 리뷰합니다 — 기존 GitHub 러너 위에서 돌기 때문에 간병할 인프라도 없습니다.
Action의 계약: @claude를 태그하고 필요한 것을 적으면, 당신의 러너 위에서 저장소를 알아서 다룹니다.17:10부터 시청 - 11
이슈를 Claude에게 할당하기
Anthropic 라이브 데모에서 "@claude please implement this feature and comment on it"이라는 코멘트에 봇이 스코프를 잡은 계획 — 만들 것들의 불릿 목록 — 으로 답한 뒤 브랜치, 커밋, 풀 리퀘스트를 만들어 냈습니다. 전부 Action 로그에서 추적됩니다.
실제 이슈의 @claude 코멘트: Claude는 코드를 만지기 전에 스코프를 잡은 계획으로 답합니다.7:50부터 시청 - 12
내 저장소에 설치하기
결과는 이슈 위의 체크된 구현 요약입니다 — 기능은 추가되고 할 일은 닫힙니다. 거기까지 가려면 저장소에서 Claude Code를 열고 /install-github-action을 실행하세요: 인터랙티브 플로우가 workflow YAML이 담긴 PR을 열고, API 키를 저장소 시크릿으로 설정한 뒤 머지합니다.
완료된 실행: Action이 데모 앱에 추가한 모든 기능이 빼곡히 체크된 구현 요약.13:30부터 시청
헤드리스 vs 대화형 vs SDK vs GitHub Action
같은 에이전트를 구동하는 네 가지 방법 — 묻는 주체가 누구(무엇)인지로 고르세요:
- 1대화형 CLI — TUI 세션: 권한 프롬프트, plan 모드, / 명령. 지금 당장 과제를 몰고 가는 사람에게 최적.
- 2헤드리스 claude -p — 프로그래매틱 원샷: stdin과 stdout, 종료 코드, UI 없음. 스크립트, cron 작업, 다른 도구에서 던지는 빠른 질문에 최적.
- 3Agent SDK — 같은 헤드리스 성능을 타입 있는 라이브러리로: 멀티턴 세션, 커스텀 도구, 스트리밍. Claude를 애플리케이션 안의 컴포넌트로 쓸 때 최적.
- 4@claude GitHub Action — GitHub의 이벤트 모델 위에서 도는 헤드리스: 당신의 러너에서 이슈, PR, 리뷰. 팀 전체가 트리거할 수 있는 저장소 단위 자동화에 최적.
- 5--bare 헤드리스 — CI를 위한 최소 기동: CLAUDE.md, hooks, skills, 플러그인, MCP 자동 탐색 없음. 컨텍스트는 플래그로 명시, 콜드 스타트 최속.
모델 접근과 권한 시스템은 공유됩니다 — 헤드리스에 준 권한 규칙은 어디서나 적용됩니다. 그래서 --allowedTools 규율이 중요합니다.
헤드리스가 말을 안 듣나요? 응급 처치
헤드리스 고유의 다섯 가지 함정과 각각의 해결책:
- 1Claude가 끝나기 전에 스크립트가 빠져나감. 종료 코드를 확인하세요: 0은 성공, 그 외는 실패. SIGTERM은 143으로 빠져나가 턴을 미완으로 남깁니다 — 도중에 멈춰야 한다면 SIGINT나 SDK의 interrupt()로 끝내세요.
- 2파이프 입력이 조용히 잘림. stdin은 10MB까지입니다 — 더 큰 페이로드는 파일에 쓰고 프롬프트에서 그 경로를 참조하세요.
- 3"--bg rejected" 또는 --cloud 에러. 대화형 전용 플래그는 -p에 적용되지 않습니다: --bg는 그대로 거부되고, --cloud는 과제 설명이 아니라 세션 id와 함께 메시지를 큐에 넣어야 합니다.
- 4CI 실행이 CLAUDE.md과 hooks를 무시함. --bare가 제 역할을 하는 것입니다: 자동 탐색을 건너뛰죠. --settings, --mcp-config, --agents, --plugin-dir로 컨텍스트를 명시적으로 전달하세요.
- 5백그라운드 bash 작업이 도중에 죽음. 백그라운드 셸은 결과가 도착한 지 약 5초 뒤 종료됩니다. 서브에이전트와 워크플로는 최대 10분 아이들 한도까지 프로세스를 살려 둡니다. CI에서는 명시적으로 기다리세요.
나머지는 --verbose를 붙여 stream-json 이벤트를 읽으세요 — system/init이 실제로 로드된 모델, 도구, MCP 서버를 이름으로 알려 줍니다.