[Claude Code #14] claude -p 헤드리스, 파이프에 AI 끼우기

Claude Code를 대화창으로만 쓰고 있다면 절반만 쓰는 겁니다. 터미널 파이프라인에 끼워 넣으면 grep이나 jq 같은 유닉스 도구처럼 쓸 수 있거든요.

관건은 -p(또는 --print) 플래그입니다. 대화형 화면 없이 프롬프트 하나를 처리하고 결과만 출력한 뒤 종료해요.

claude -p "auth 모듈이 뭘 하는지 설명해줘"

Claude Code 13편까지가 세션 안 이야기였다면, 이번엔 세션 밖에서 부리는 법입니다.

파이프로 넣고 파일로 받기

공식 문서 기준으로 -p 모드는 표준 입력을 읽습니다. 데이터를 파이프로 넣고 결과를 리다이렉트하면 여느 CLI 도구와 똑같아요.

cat build-error.txt | claude -p '이 빌드 에러의 근본 원인을 간결히 설명해줘' > output.txt

공식 문서 기준으로 성공하면 종료 코드 0, 실패하면 0이 아닌 코드로 끝나 스크립트 분기도 됩니다. 파이프 입력은 10MB까지라, 더 크면 파일 경로를 프롬프트에 적어 우회해요.

package.json 스크립트에 넣으면 프로젝트 전용 린터도 만들 수 있습니다. diff를 파이프로 넣고 오타만 보고하게 하는 식이죠.

JSON으로 받아서 프로그램이 소비하기

--output-format json을 붙이면 결과가 세션 ID·비용 같은 메타데이터와 함께 구조화돼 나옵니다.

claude -p "이 프로젝트 요약해줘" --output-format json | jq -r '.result'

특정 스키마에 맞는 출력이 필요하면 --output-format json에 --json-schema를 더하세요. 응답의 structured_output 필드에 검증된 구조로 담겨 옵니다.

토큰 단위 실시간 스트리밍에는 --output-format stream-json --verbose --include-partial-messages 조합을 씁니다.

권한은 미리 열어 둬야 합니다

-p 모드에는 승인 버튼을 눌러 줄 사람이 없습니다. 필요한 도구를 미리 허용해 둬야 해요.

claude -p "테스트 돌리고 실패 고쳐줘" --allowedTools "Bash,Read,Edit"

--allowedTools는 권한 규칙 문법을 그대로 씁니다. Bash(git diff *)처럼 좁힐 수 있어요. 별표 앞 공백이 중요합니다. 없으면 git diff-index까지 매칭돼 버려요.

--permission-mode acceptEdits를 주면 파일 쓰기와 mkdir·mv 같은 흔한 파일시스템 명령이 자동 승인됩니다. 그 밖의 셸 명령과 네트워크 요청은 여전히 --allowedTools가 필요해요.

대화 이어가기

한 번의 호출로 끝나지 않는 작업은 세션을 이어 가면 됩니다.

claude -p "이 코드베이스의 성능 문제를 리뷰해줘"
claude -p "이제 DB 쿼리에 집중해줘" --continue

여러 대화를 병행한다면 JSON 출력의 session_id를 받아 두고 --resume으로 특정 대화를 집어 이어 갑니다.

CI에서는 –bare가 정석

스크립트·CI 용도라면 --bare를 함께 쓰는 게 좋습니다. 훅·스킬·플러그인·MCP·CLAUDE.md 자동 로딩을 건너뛰어 시작이 빨라지고, 어느 머신에서든 같은 결과가 나와요.

보안상 이유도 있습니다. -p 세션은 워크스페이스 신뢰 확인 창을 못 띄워서, --bare 없이는 낯선 저장소의 훅과 MCP 서버까지 그대로 실행됩니다. 공식 문서도 스크립트 호출에는 --bare를 권장 모드로 못 박습니다. 향후 -p의 기본값이 될 예정이라고도 하고요.

--bare에서는 구독 로그인 대신 ANTHROPIC_API_KEY 환경 변수를 써야 한다는 점만 기억하세요.

정리

claude -p는 Claude Code를 유닉스 도구로 바꿉니다. 파이프로 넣고, JSON으로 받고, 종료 코드로 분기하세요.

권한은 --allowedTools로 미리 열고, CI에서는 --bare로 결정적이고 안전하게 돌리면 됩니다.

다음 편에서는 대화형 화면으로 돌아와, ! 셸 모드와 Ctrl+O 같은 특수 입력·단축키를 총정리합니다.

출처 및 확인 기준

• Claude Code 공식 문서 — Run Claude Code programmatically (Anthropic, 2026-08-14 확인)

이어서 읽기

Claude Code 시리즈

• 이전 편: [Claude Code #2] /plan 계획 모드, 수정 전에 설계부터 합의하기
• 이전 편: [Claude Code #1] /init, CLAUDE.md 자동 생성으로 시작하기

관련 주제

• [에이전트 설계 #1] 하네스 엔지니어링이란? 프롬프트 다음에 오는 것