헤드리스 모드와 Agent SDK
스크립트와 CI/CD pipeline 에서 자동으로 Claude 실행
⏱ 예상 ~6분
01 · 읽기
지금까지 Claude Code로 한 모든 건 인터랙티브해요 — 여러분이 타자치고, Claude가 응답하고, 여러분이 승인해요. 그런데 Claude를 자동으로 돌려야 한다면? 모든 pull request 를 review 하는 CI/CD pipeline 에서? 매일 밤 lint 에러를 고치는 스크립트에서?
헤드리스 모드 (claude -p) 는 인터랙티브 터미널 없이 Claude를 실행해요. prompt 를 주면, Claude가 일하고, 결과를 돌려줘요. 타자 없고, 승인 다이얼로그 없고 — 그냥 입력과 출력.
이게 팀이 Claude를 자동화된 워크플로로 통합하는 방법이에요: code review bot, test fixer, 문서 생성기 등등.
💡 상상해 봐요인터랙티브 Claude 는 책상에서 동료와 대화하는 것 같아요. 헤드리스 Claude 는 그들에게 작업을 email 로 보내는 것 같아요 — 요청을 보내고, 그들이 일하고, 결과가 돌아와요. 왔다 갔다 없어요.
핵심 정리
- claude -p 는 비인터랙티브로 Claude를 실행 (헤드리스 모드)
- 스크립트, CI/CD pipeline, 자동화에 좋아요
- 승인 대화 없어요 — 허용된 도구를 미리 지정해요
- 출력은 텍스트, JSON, 또는 스트리밍 JSON 일 수 있어요
02 · 코드 예제
아래는 흔한 헤드리스 모드 패턴이에요. -p 플래그가 비인터랙티브로 만들어요.
기본 헤드리스 사용법
# Simple query
claude -p "Find all TODO comments in this project"
# With allowed tools (auto-approved, no prompts)
claude -p "Run tests and fix failures" \
--allowedTools "Bash(npm test*),Read,Edit"
# Structured JSON output
claude -p "List all API endpoints" \
--output-format json
-p 플래그 ('print' 줄임말) 는 Claude를 비인터랙티브로 실행해요. --allowedTools 는 특정 도구를 사전 승인해서 Claude가 permission prompt 없이 작업할 수 있게 해요. --output-format json 은 평문이 아닌 구조화된 데이터를 반환해요 — 다른 프로그램이 결과를 parse 해야 할 때 유용해요.
03 · 코드 예제
아래는 팀이 CI/CD pipeline 에서 헤드리스 모드를 어떻게 쓰는지예요 — 모든 pull request 마다 실행되는 자동 code reviewer.
GitHub Actions — 자동 code review
# .github/workflows/claude-review.yml
name: Claude Code Review
on: [pull_request]
jobs:
review:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Review PR
run: |
claude -p "Review the changes in this PR. \
Focus on bugs, security, and performance." \
--allowedTools "Read,Grep,Glob" \
--output-format text
이 GitHub Action 은 모든 pull request 에서 Claude를 헤드리스 모드로 실행해요. read-only 도구 (Read, Grep, Glob) 만 허용해서, Claude가 코드를 분석할 수 있지만 아무것도 바꿀 수 없어요. Review 출력은 CI 로그에 나타나서 팀이 읽어요.
04 · 읽기
더 복잡한 자동화에는 Anthropic 이 Agent SDK 를 제공해요 — Claude가 지원하는 도구로 production agent 를 만드는 Python 과 TypeScript 라이브러리예요.
Agent SDK 는 모든 것의 프로그래밍 가능한 통제를 줘요: 어떤 도구를 쓸지, 결과를 어떻게 처리할지, session 관리 (대화 이어가기), 심지어 MCP 서버 연결까지. 가장 정교한 Claude Code 통합을 뒷받침해요.
CLI (claude -p) 는 간단한 자동화에 좋아요. Agent SDK 는 전체 프로그래밍 통제가 필요할 때 써요 — 커스텀 에러 처리, 결과 스트리밍, 여러 Claude 호출 체인, 또는 Claude 능력 위에 제품 만들기.
핵심 정리
- Agent SDK: production agent 를 위한 Python 과 TypeScript 라이브러리
- 도구, session, 결과의 전체 프로그래밍 통제
- CLI (claude -p): 간단한 자동화와 스크립트
- Agent SDK: 복잡한 애플리케이션과 production 시스템
- Session 관리: 프로그래밍으로 대화 캡처와 이어가기
05 · 코드 예제
아래는 TypeScript 에서 간단한 Agent SDK 예시예요. 프로그래밍으로 버그를 찾고 고쳐요.
Agent SDK — bug fixer
import { query } from '@anthropic-ai/claude-agent-sdk';
for await (const msg of query({
prompt: "Find and fix the failing test in auth.test.ts",
options: {
allowedTools: ["Read", "Edit", "Bash"],
}
})) {
if (msg.result) {
console.log('Fix applied:', msg.result);
}
}
Agent SDK 는 스트리밍 인터페이스를 줘요 — Claude가 일하는 동안 메시지를 순회해요. allowedTools 배열이 Claude가 할 수 있는 걸 통제해요. Claude가 끝나면 result 메시지에 한 일의 요약이 있어요. 이게 파일을 읽고, 편집하고, 명령을 실행하는 자동 agent 를 만드는 방법이에요.
06 · 퀴즈
어떤 플래그가 Claude Code를 인터랙티브 터미널 없이 비인터랙티브로 실행할까요?
- claude --headless
- claude --auto
- claude -p
- claude --batch
07 · 빈칸 채우기
사용자 상호작용 없이 CI/CD pipeline 에서 Claude를 실행하려면 claude _____ "여러분의 prompt" 를 써요.
08 · 짝짓기
각 자동화 방법을 가장 잘 맞는 용도와 짝지어요.
(이 섹션은 인터랙티브해요 — JavaScript를 켜 주세요.)
⚠ 전체 인터랙티브 경험에는 JavaScript가 필요해요. JavaScript를 켜고 새로 고침해 주세요.
※ 이 사이트는 독립 운영되는 교육 프로젝트로, Anthropic의 공식 제품이 아니에요. Claude™ 는 Anthropic, PBC 의 상표예요.