Loop Engineering with Claude Code — 헤드리스 모드로 클로드 코드를 인프라로 쓰는 법

한 줄 요약

Claude Code를 프롬프트 주고받는 챗봇이 아니라 cron·CI·Git 훅·파이프라인에 꽂히는 Unix 실행 파일로 쓰는 법을 정리한 글. 헤드리스 모드(-p)와 JSON 구조화 출력을 기반으로 배치 루프·멀티턴 루프·에이전트 파이프라인 3가지 패턴, 그리고 --allowedTools·--max-turns·--max-budget-usd·--bare 가드레일을 실전 예시와 함께 소개한다.

핵심 아이디어

대화형 루프(프롬프트 → 읽기 → 수정 제안 → 승인 → 반복)는 탐색에는 좋지만, 키보드 앞에 아무도 없을 때가 진짜 가치가 나오는 지점이다. 이때 Claude Code는 입력을 받아 작업하고 구조화된 출력을 반환한 뒤 종료하는, 자동화 스택의 실행 노드가 된다. 프롬프트 엔지니어링이 아니라 그 주변의 반복 구조를 설계하는 것(루프 엔지니어링)이 핵심이라는 주장.

헤드리스 모드와 구조화 출력

-p(--print)를 쓰면 대화형 터미널 없이 에이전트 루프 전체를 한 번에 실행하고 종료한다. stdin으로 입력받고 stdout으로 출력하며 exit code로 성공/실패를 알리는, 다른 Unix 프로그램과 동일한 동작 방식이다.
```
claude -p "Find and fix the bug in auth.py" --allowedTools "Read,Edit,Bash"
cat build-error.txt | claude -p "Explain the root cause" > diagnosis.txt
```
--output-format json으로 산문 대신 JSON을 받으면 세션 ID, 실행 세부정보, 토큰 사용량, total_cost_usd 같은 메타데이터까지 함께 온다. 다운스트림 스크립트는 “영어를 이해할” 필요 없이 JSON만 소비하면 된다.

3가지 루프 패턴

패턴	방식	언제 쓰나
배치 루프	작업 목록을 먼저 뽑고(`claude -p ... > list.txt`), 파일 단위로 `for` 루프를 돌며 각각 독립 실행	리포 전체를 한 프롬프트로 고치지 않고 격리된 단위로 쪼갤 때. 클린 컨텍스트, 실패 격리, 병렬화, 재시도, 중단 복구가 모두 쉬워진다
멀티턴 루프	`--output-format json`으로 받은 `session_id`를 `--resume`에 넘겨 이전 발견을 이어간다	아키텍처 리뷰처럼 단계마다 이전 결과가 필요할 때. 세션은 작업 디렉터리에 스코프되므로 매번 같은 위치에서 호출해야 한다
에이전트 파이프라인	Claude 호출을 여러 독립 단계 중 하나로 배치(스캔 → JSON 리포트 → Slack 알림 → 우선순위화 → GitHub 이슈 생성 → 아침 리뷰)	각 단계가 명확한 입출력을 갖고, 한 단계가 바뀌어도 그 단계만 교체할 수 있게 하고 싶을 때. Unix 파이프라인 철학 그대로

가드레일이 지능보다 중요하다

경계 없는 무인 에이전트는 자동화가 아니라 부채라는 전제 아래 4가지 플래그를 핵심 보안 경계로 제시한다.

--allowedTools — 읽기 전용 감사(Read,Glob,Grep)부터 좁게 스코프된 쓰기 권한(Read,Edit,Bash(git commit:*),Bash(npm test))까지, 에이전트가 할 수 있는 일을 명시적으로 제한한다.
--max-turns — 추론 스텝 수 상한. 작업이 삐끗해도 무한 루프에 빠지지 않는다.
--max-budget-usd — 호출당 지출 상한. 파일 1개를 처리하든 1,000개를 처리하든 재무적 하드 리밋을 건다.
--bare — hooks·MCP 서버·플러그인·로컬 CLAUDE.md의 자동 탐색을 끈다. CI 러너가 팀원 로컬 설정에 흔들리지 않고 매번 동일하게 동작하게 만드는, 가장 간과되는 프로덕션 플래그. 인증은 ANTHROPIC_API_KEY로 받는다.

프로덕션 호출 예시:

claude --bare -p "$PROMPT" \
  --allowedTools "Read,Grep,Edit,Bash(npm test)" \
  --max-turns 40 --max-budget-usd 2 \
  --output-format json > result.json 2> claude.err

stdout은 구조화 데이터로, stderr는 로그로, exit code는 제어 흐름으로 다룬다.

스케줄링과 프롬프트 습관

cron/GitHub Actions/공식 Claude Code Action으로 트리거하되, **“파이프라인이 실패했을 때만 호출”**하는 패턴을 추천한다. 성공한 빌드마다 토큰을 쓰지 않고, 실패를 진단·설명·수정 제안까지만 하고 병합 여부는 사람이 결정하는 “human on the loop” 지점.
무인 워크플로우에 맞는 프롬프트 습관 3가지: ① 잘 쓰인 CLAUDE.md로 아키텍처·컨벤션·기대 워크플로우를 온보딩 문서처럼 제공, ② “리포 전체를 고쳐라” 대신 diff 하나·파일 하나·로그 하나 단위로 작게 쪼개기, ③ 변경만 하고 끝내지 말고 테스트 실행·JSON 검증·포맷 확인까지 항상 검증하기.
Bash만으로 한계에 부딪히면(승인 콜백, 네이티브 메시지 객체, 애플리케이션 수준 통합) Agent SDK가 다음 단계다. 도구 스코프, 턴 제한, 예산 상한, 구조화 출력이라는 원칙은 그대로 유지된다.

description	Claude Code를 챗봇이 아니라 cron·CI·파이프라인에 꽂히는 Unix 도구로 쓰는 법 — 헤드리스 모드, 구조화 출력, 배치/멀티턴/파이프라인 3패턴과 가드레일 플래그를 정리한다.
tags	ai-coding, automation, cli, harness

LLM Wiki

탐색기