Claude Code /loop 명령어 완전 가이드: 5분 캐시부터 PR 자동화까지

Anthropic Claude Code 2.x에 내장된 /loop 스케줄러를 활용해 PR 자동 리뷰, 배포 헬스 폴링, 일일 브리핑을 무인화하는 방법. Boris Cherny가 공개한 실전 워크플로우 5개와 비용 폭주를 막는 안전 가드를 함께 정리합니다.

TL;DR

/loop은 Claude Code 세션 안에서 도는 cron 스케줄러입니다.
두 가지 모드: interval (/loop 5m /babysit)과 dynamic (/loop every morning ...).
프롬프트 캐시 TTL이 5분이라 5분 이하 간격이 비용 효율의 분기점입니다.
Boris Cherny 본인이 가장 핵심 기능으로 꼽은 워크플로우는 /loop 5m /babysit입니다.
GitHub Issue #54086에서 보고된 비용 폭주 사고가 있어, 슬래시 커맨드 멱등성 보장이 필수입니다.

1. /loop이란

Claude Code 2.x에 내장된 시스템 스킬입니다. 슬래시 커맨드 또는 자연어 프롬프트를 주기적으로 재실행합니다. 일반 cron과 다른 점은 Claude 세션 안에서 살아 있는 동안만 동작한다는 것입니다. 백그라운드 wakeup으로 노트북이 잠시 잠들어 있어도 깨워서 실행하지만, 최대 3~7일 후 자동 만료됩니다.

비유하자면 보안 카메라입니다. 정해진 간격마다 한 번씩 상황을 살펴보고, 이상이 있으면 알려줍니다. 반대로 단일 작업을 끝까지 자율 반복하는 Ralph Loop은 공사장 인부에 가깝습니다. 망치질을 계속 하다가 집이 완성되면 멈춥니다.

2. 작동 원리

호출 문법

# Interval 모드 — 고정 간격 cron 변환
/loop 5m /babysit
/loop 20m /review-pr 1234
/loop 1h check linter on changed files
/loop 30m check error logs for last 30 minutes

# Dynamic 모드 — Claude가 self-pace 결정
/loop babysit all my PRs. Auto-fix build issues and when comments come in, use a worktree agent
/loop every morning use the Slack MCP to give me a summary of top posts I was tagged in

시간 단위는 s (초), m (분), h (시간), d (일) 네 가지입니다. cron의 최소 granularity는 1분이라 그 이하는 의미가 없습니다.

두 가지 모드

모드	트리거	종료 조건	사용처
Interval	시간 단위 명시	명시적 stop 또는 7일 만료	PR 감시, 배포 폴링, 헬스 체크
Dynamic	자연어 (시간 자동 해석)	Claude가 "완료" 판단 시 자가 종료	일일 브리핑, 조건부 작업

Dynamic 모드는 ScheduleWakeup 도구를 통해 다음 실행 시점의 delaySeconds를 Claude가 직접 계산합니다. "매일 아침"이라고 하면 다음 아침 9시까지 몇 초 남았는지 계산해서 그때 깨어납니다.

캐시 TTL 5분이 만든 분기점 (CRITICAL)

ScheduleWakeup 공식 docs에 명시된 한 줄:

The Anthropic prompt cache has a 5-minute TTL.

이게 모든 비용 설계의 기준점입니다.

5분 이하 간격: cache hit → 토큰 비용 90% 절감
5분 초과 간격: cache miss → 매번 풀 컨텍스트 재처리

그래서 폴링용 /loop은 5분 또는 1분 간격이 정석입니다. 30분, 1시간 간격은 dynamic 모드에서 의미 있는 변화 감지가 필요할 때만 씁니다.

만료 정책 (소스 간 상이)

출처	만료 기간
공식 docs (code.claude.com)	7일
Boris Cherny Threads	"up to 3 days at a time"

초기에는 3일, 이후 확장된 것으로 보입니다. 사용 시 docs 최신본 확인이 안전합니다. 만료 시점은 silent 종료이므로 캘린더에 기록해두세요.

3. Boris Cherny가 공개한 실전 워크플로우 5선

Claude Code 창시자 본인이 자기 일에 쓰는 방식입니다.

사례 1: PR Babysit

/loop 5m /babysit

/babysit는 사용자가 정의한 슬래시 커맨드입니다. 내용은 대략:

내 PR 목록 조회
CI 실패한 PR 찾기
실패 원인 분석 → 수정 커밋 → rebase
새 코멘트 있으면 응답

본인은 차 마시고 있고, Claude가 PR을 돌봅니다. 5분 간격이라 cache hit, 비용 효율도 챙겼습니다.

사례 2: Slack 피드백 → 자동 PR

/loop 30m /slack-feedback

30분마다 Slack 채널을 모니터링하다가 피드백이 누적되면 클러스터링해서 관련 코드 변경 PR을 자동으로 만듭니다. "고객 피드백 → 코드" 파이프라인이 사람 없이 돌아갑니다.

30분 간격이라 cache miss는 감수하지만, 30분마다 PR 한 개씩 만드는 빈도는 합리적입니다.

사례 3: Staging 배포 헬스 폴링

/loop 5m staging 배포가 포트 3000에서 응답하는지 확인하고 HTTP 상태 코드 알려줘

UptimeRobot이나 Datadog 없이 Claude가 직접 헬스 체크를 수행합니다. 5xx 상태 변화 감지 시 알림을 받습니다. 5분 cache hit 구간이라 비용도 가볍습니다.

사례 4: 일일 아침 브리핑 (Dynamic 모드)

/loop every morning use the Slack MCP to give me a summary of top posts I was tagged in

Interval을 명시하지 않은 dynamic 모드입니다. Claude가 "매일 아침"을 해석해서 ScheduleWakeup의 delaySeconds를 다음 아침 시각까지 자동 계산합니다.

사례 5: 다중 PR + worktree 에이전트

/loop babysit all my PRs. Auto-fix build issues and when comments come in, use a worktree agent to fix them

여러 PR을 worktree로 분리하여 각각 sub-agent(Task tool)에 위임합니다. Claude는 오케스트레이터 역할만 하고, 실제 코드 수정은 worktree 안의 sub-agent가 합니다. 본인은 코딩만 하고, 리뷰 사이클은 Claude가 돌립니다.

4. /loop vs Ralph Loop vs cron vs GitHub Actions

항목	`/loop`	`/ralph-loop`	cron/launchd	GitHub Actions
출처	Claude Code 2.x	커뮤니티 (Geoffrey Huntley)	OS 영구 스케줄러	CI/CD
스코프	세션 + 백그라운드 wakeup	세션 내 단일 task	시스템 영구	이벤트 트리거
종료	7일 만료 또는 명시 stop	작업 완료 또는 max iter	명시적 unload	작업 종료 시
베스트 핏	주기적 폴링/감시	단일 복잡 작업 자율 반복	OS 레벨 영구 백업/배치	PR/이슈 자동화
비용	cache hit 5분 이하 시 저렴	토큰 누적 가능	무료	runner 분당 과금

핵심 명제 (paddo.dev): Ralph iterates toward completion on a single task, while /loop polls on a schedule. One is a construction crew, the other is a security camera.

5. 알려진 함정 — Issue #54086 비용 폭주 사고

GitHub Issue #54086에서 보고된 사고입니다. 사용자가 멀티 에이전트 audit 슬래시 커맨드를 /loop에 걸어둔 채 잤더니, 작업이 이미 완료된 상태에서도 ScheduleWakeup이 동일 슬래시 커맨드를 통째로 재진입해서 멀티 에이전트 호출이 중복 청구되었습니다.

근본 원인은 /loop의 자체 dedup 가드가 없다는 것입니다. 사용자가 슬래시 커맨드 안에서 멱등 키를 직접 구현해야 합니다.

멱등성 보장 패턴

# 좋은 예시 — 작업 완료 여부를 파일/DB로 확인 후 진행
/loop 5m check if today's report exists in ./reports/$(date +%Y-%m-%d).md, if not generate

# 나쁜 예시 — 무조건 멀티 에이전트 실행
/loop 5m /full-codebase-audit

비슷한 재진입 버그가 Issue #51304에도 보고되어 있습니다. 완료 신호 처리 로직이 아직 완벽하지 않다는 의미입니다.

6. 안티패턴

부적절한 사용	대신 사용할 것
1회성 작업에 `/loop`	일반 프롬프트
단일 복잡 작업을 끝까지 자율 반복	Ralph Loop / `/ralph-loop`
파일 변경 이벤트 트리거	Hook (PostToolUse / Stop)
비싼 멀티 에이전트 슬래시 커맨드 무한 재실행	interval 제한 + 멱등 가드
세션 종료 후에도 영구 실행 가정	launchd / cron / GitHub Actions
Claude Code 외부 정기 작업	Claude Cowork Scheduled Tasks

7. FAQ

Q1. /loop이 동작하려면 항상 Claude Code 세션이 열려 있어야 하나요? A. 네. 세션 스코프입니다. 노트북 sleep 들어가면 wakeup이 보장되지 않습니다. 영구 동작이 필요하면 launchd나 GitHub Actions를 쓰세요.

Q2. 만료 시점에 알림이 오나요? A. 현재로선 silent 종료입니다. 캘린더에 만료 시점을 기록하는 것이 안전합니다.

Q3. Dynamic 모드는 어떻게 종료되나요? A. Claude가 "작업이 완료되었다"고 판단하면 ScheduleWakeup을 더 이상 예약하지 않고 자가 종료합니다. 종료 조건이 모호한 자연어 프롬프트는 무한 반복 위험이 있습니다.

Q4. 비용은 얼마나 드나요? A. 5분 이하 간격이면 cache hit으로 토큰 비용이 크게 절감됩니다. 하지만 슬래시 커맨드 자체가 멀티 에이전트를 호출하면 그 비용은 별도로 누적됩니다. Issue #54086이 그 사례입니다.

Q5. 일시 중단은 어떻게 하나요? A. 다음 iteration 대기 중에 Esc를 누르면 pending wakeup이 클리어됩니다.

8. 결론

/loop은 내가 다른 일을 하는 동안 Claude가 백그라운드에서 폴링/감시하길 원할 때 쓰는 도구입니다. PR 감시, 배포 헬스 체크, 일일 리포트가 베스트 핏입니다.

세 가지만 기억하세요.

5분 이하 간격 (cache TTL)
슬래시 커맨드 멱등성 (Issue #54086 방지)
만료 캘린더 기록 (3-7일 silent 종료)

Boris Cherny 본인이 가장 많이 쓴다고 공언한 명령어인데, 정작 대부분의 사용자는 모릅니다. 오늘부터 PR 하나에 /loop 5m /babysit 걸어보세요.

참고문헌

Claude Code 실전 자동화 콘텐츠는 퀀텀점프클럽에서 더 받아보실 수 있습니다.

claude-code-loop-command-blog