19. 헤드리스 실행과 CI

헤드리스 실행이란

3장에서 본 claude -p는 TTY(대화형 터미널) 없이 한 번 실행하고 종료하는 모드입니다. 이게 모든 자동화의 토대입니다.

# 한 번 실행하고 결과 출력 후 종료
claude -p "이 디렉터리의 TODO를 전부 찾아 목록으로"

# 파일 내용을 파이프로 전달
cat error.log | claude -p "이 에러 로그를 분석해줘"

비유하자면, 대화형 모드가 "옆에 앉아 같이 일하는 동료"라면, 헤드리스는 "작업 지시서를 받아 혼자 처리하고 결과만 제출하는 일꾼" 입니다. 사람이 지켜보지 않으니, 무엇을 할 수 있는지(권한)를 미리 못박아야 합니다.

CI: GitHub Actions에 넣기

헤드리스 CLI를 GitHub Action 안에서 돌리면, PR마다 자동으로 린트·테스트·diff 요약·코드 리뷰를 할 수 있습니다. TTY 없이 원샷 프로세스로 도니까요.

flowchart LR
    PR[Pull Request 생성/갱신]:::user --> GA[GitHub Action 트리거]:::tool
    GA --> CC[claude -p 실행<br/>리뷰·테스트·요약]:::agent
    CC --> Comment[PR에 결과 코멘트]:::result

    classDef user fill:#FFE082,stroke:#F9A825,color:#000
    classDef tool fill:#90CAF9,stroke:#1E88E5,color:#000
    classDef agent fill:#80DEEA,stroke:#00ACC1,color:#000
    classDef result fill:#A5D6A7,stroke:#43A047,color:#000

활용 패턴:

• PR마다 코드 리뷰·이슈 트리아지 (GitHub Actions 또는 GitLab CI/CD)
• 야간 작업: 같은 명령을 매일 밤 스케줄 실행
• pre-commit 훅: 커밋 전 검사

인증·권한: 비대화형의 핵심 주의점

사람이 없으니 두 가지를 미리 정해야 합니다.

1) 인증 — 브라우저 로그인이 불가능하므로 ANTHROPIC_API_KEY 환경변수를 씁니다(2장). 엔터프라이즈는 Bedrock·Vertex·Foundry 경로도 가능합니다.

2) 권한 — --allowedTools가 권한 규칙 문법을 지원해, 기대하는 동작만 정확히 허용할 수 있습니다. 범용 셸을 통째로 허용하는 것보다 훨씬 건강한 패턴입니다.

claude -p "테스트 실행하고 실패하면 요약" \
  --allowedTools "Bash(npm test)" "Read"

⚠️ 비대화형에서 권한이 막히면 물어볼 사람이 없습니다. auto 모드든 일반이든, 반복 차단 시 세션이 중단됩니다(8장). 그래서 CI에서는 필요한 도구를 미리 정확히 허용하는 게 중요합니다. 격리된 러너라면 bypassPermissions를 쓰기도 하지만, 반드시 일회용·격리 환경에서만(23장).

스케줄 실행: 네 가지 선택지

"반복해서 돌리고 싶다"는 요구에 Claude Code는 네 가지 길을 줍니다. 어디서 도느냐가 선택 기준입니다.

flowchart TB
    Q{작업이 무엇에 의존?}:::agent
    Q -->|내 머신·로컬 파일| Desk[데스크톱 스케줄 작업<br/>머신에서 실행]:::tool
    Q -->|머신 꺼져도 계속| Routines[Routines<br/>Anthropic 클라우드]:::result
    Q -->|열린 세션이면 충분| Loop[/loop<br/>세션 내 반복]:::tool
    Q -->|repo CI·감사 로그| Actions[GitHub Actions<br/>repo 네이티브 CI]:::tool

    classDef agent fill:#80DEEA,stroke:#00ACC1,color:#000
    classDef tool fill:#90CAF9,stroke:#1E88E5,color:#000
    classDef result fill:#A5D6A7,stroke:#43A047,color:#000

• /loop 예시: 매일 오전 9시, 최근 24시간 git log를 프로젝트별로 요약해 ~/Desktop/daily-recap.md에 저장

⚠️ 과금 주의: Agent SDK 크레딧 풀

중요한 변화: 2026년 6월, Anthropic은 비대화형 사용(claude -p/--print, Agent SDK, GitHub Actions)을 별도의 월간 Agent SDK 크레딧 풀로 분리했습니다(구독 사용자 기준). 즉 헤드리스·자동화 실행은 일반 대화형과 다른 풀에서 차감될 수 있습니다.

이 장에서 배운 것

• 헤드리스 claude -p는 TTY 없이 원샷 실행하는 모드로, 모든 자동화의 토대다. 파이프 입력도 된다.
• CI에서는 GitHub Actions 안에서 claude -p로 PR 리뷰·테스트·요약을 자동화한다.
• 비대화형은 API 키 인증 + --allowedTools로 정확한 권한을 미리 정해야 한다(막히면 물어볼 사람이 없으니).
• 스케줄 실행은 /loop(세션)·데스크톱(머신)·Routines(클라우드)·GitHub Actions(CI) 중 의존 대상에 맞게 고른다.
• 비대화형 사용은 별도 Agent SDK 크레딧 풀로 과금될 수 있으니 공식 문서로 확인한다.

✍️ 확인 문제

1. 헤드리스(-p) 모드에서 권한을 미리 정확히 허용해야 하는 이유는 무엇인가요?
2. "머신이 꺼져 있어도 계속 돌아야 하는 반복 작업"에는 네 선택지 중 무엇이 맞나요? 로컬 파일이 필요하면요?
3. /loop가 외부 cron으로 claude -p를 감싸는 것보다 나은 점은 무엇인가요?

다음 장: 20. 원격 제어와 자동화 루프 — 폰에서 조종하고, 밤새 스스로 돌게 하기.