Claude Code 스케줄링 완전 분석: /loop, ScheduleWakeup, Routines 활용 사례 11개

Claude Code로 자동화를 깊게 쓰다 보면, 어느 순간 "이 작업을 매일 새벽 2시에 돌리고 싶다", "빌드가 끝날 때까지 폴링하고 싶다", "PR이 열리면 자동으로 검토하게 하고 싶다" 같은 요구가 생깁니다.

이때 Claude Code가 제공하는 스케줄링은 한 가지가 아니에요. 3계층으로 나뉘어 있고, 각 계층의 용도가 완전히 다릅니다.

이 글에서는 공식 docs와 GitHub Issue를 교차검증한 자료를 바탕으로, 3계층의 차이와 실제 활용 사례 11개, 그리고 비용을 폭주시킬 수 있는 함정 3가지를 정리해드립니다.

3계층 스케줄링 아키텍처: 한눈에 보기

세 가지의 본질적 차이는 한 줄로 요약됩니다.

"노트북 닫아도 돌아야 하는가?"

YES이면 Routines, NO이면 /loop이에요. /loop은 다시 고정 cadence(every 1 hour 같은)와 동적(ScheduleWakeup)으로 갈라집니다.

/loop + Cron 도구: 세션 내부 스케줄링

/loop은 Claude Code에 번들로 제공되는 스킬입니다. 가장 빠른 진입점이고, 자연어로 interval을 주면 Claude가 5-field cron 표현식으로 변환해 CronCreate를 호출해요.

/loop every 30 minutes check the build status

이 한 줄이면 끝납니다. Claude가 cron 표현식과 8자리 job ID를 출력해줍니다.

핵심 제약 4가지

공식 docs 기준으로 반드시 알아야 하는 제약입니다.

1. 세션당 50개 task 한도: 누적되면 가벼운 모니터링도 전체 비용이 폭주합니다. CronList로 정기 확인이 필요해요.
2. 8자리 ID 발급: CronDelete에 전달해야 개별 task 제거 가능.
3. 터미널 닫히면 fire 중단: Claude Code가 실행 중이고 idle 상태일 때만 동작합니다.
4. 7일 후 자동 만료: 영구 작업은 routines로 옮겨야 합니다.

Interval 표기법

깔끔하지 않은 step(7m, 90m)은 가장 가까운 valid cron step으로 반올림됩니다. Claude가 어느 값을 골랐는지 알려주니, 의도와 다르면 즉시 수정 가능해요.

지원되지 않는 cron syntax

표준 5-field만 지원합니다. 7-field 확장 syntax는 거부됩니다.

• ❌ L (월말)
• ❌ W (가까운 평일)
• ❌ ? (둘 중 하나 미지정)
• ❌ MON, JAN 같은 alias

요일은 0 또는 7이 일요일, 6이 토요일입니다.

ScheduleWakeup: 동적 페이싱과 5분 캐시 TTL 함정

/loop에서 interval을 생략하면 동적 모드로 진입합니다. Claude가 매 iteration 후 1분~1시간 사이 delay를 자체 결정해요.

/loop check if `npm run build` completed. If done, run tests. If still running, wait.

이렇게 주면 Claude가 ScheduleWakeup(delaySeconds=270, prompt="...", reason="poll build") 같은 형태로 자체 페이싱합니다.

CRITICAL 함정 1: delaySeconds=300 근처는 worst-of-both

이게 가장 중요한 부분이에요. Anthropic 프롬프트 캐시 TTL이 정확히 5분입니다.

300초 근처는 캐시는 만료됐는데(uncached로 전체 컨텍스트 재읽기) 대기는 짧아서 자주 fire되니까 비용이 양쪽으로 새요. 270초 이하든 1200초 이상이든, 한쪽으로 가야 합니다.

CRITICAL 함정 2: 슬래시 커맨드 prompt 재실행

GitHub Issue #54086에 보고된 사례입니다.

# ❌ 위험 패턴
ScheduleWakeup(delaySeconds=270, prompt="/refactor:frontend", reason="poll build")

이렇게 슬래시 커맨드를 prompt에 직접 넣으면, wake-up마다 전체 슬래시 커맨드가 다시 실행됩니다. /refactor:frontend의 경우 4개 specialist sub-agent + 1 synthesis sub-agent + vitest/eslint/typecheck/npm-audit 백그라운드까지 통째로 재실행되어, 회당 $1+ 토큰 비용이 폭주할 수 있어요.

안전한 패턴:

# ✅ 안전: 자연어 + 상태 확인 한정
ScheduleWakeup(
  delaySeconds=270,
  prompt="Check if the previous /refactor task completed. Read .claude/state/refactor-status.json. If status='done', summarize. Do NOT re-run /refactor.",
  reason="poll status only"
)

상태 확인은 자연어로, 실행은 명시적 사용자 트리거로만 분리하세요.

Routines: 클라우드 실행과 플랜별 한도

Routines는 2026년 4월 14일 research preview로 출시된 기능입니다. Anthropic-managed 클라우드 인프라에서 실행되니까, 노트북을 닫아도 동작합니다.

저장 단위는 prompt + repos + connectors(MCP 통합)이에요.

3종 트리거

CRITICAL 함정 3: 플랜별 일일 한도

매시간 폴링하는 워크플로우(24/일)를 Pro 플랜으로 돌리면, 6시간 만에 한도가 끝납니다. 매시간 작업은 Max 이상이 필수예요.

GitHub 트리거는 per-routine + per-account hourly cap이 추가로 적용됩니다. 한도 초과 이벤트는 window reset까지 drop되니, CI에서 webhook을 폭주시키는 워크플로우는 신중해야 해요.

실제 활용 사례 11개

공식 사례 (Anthropic 블로그)

Anthropic 공식 블로그 "Introducing routines in Claude Code"에 등장한 4개입니다.

1. 매일 새벽 2시 Linear 최상위 버그 자동 fix + draft PR: Schedule (nightly) 트리거. 아침에 출근하면 PR이 이미 대기.
2. PR opened 시 팀 체크리스트 적용 + 인라인 코멘트: GitHub pull_request.opened 트리거. security/performance 검토 자동화.
3. Python SDK → Go SDK 자동 port: GitHub PR merged 트리거. 변경 사항이 다른 언어 SDK에 자동 반영.
4. 문서 피드백 위젯 → repo 세션 + docs 변경안: API webhook. 사용자가 docs 페이지에 피드백 남기면 자동으로 PR 생성.

커뮤니티 사례 (검증된 source)

5. Daily dev brief: 지원 티켓 + 채팅 transcript 클러스터링 → top 5 이슈 짧은 brief. Schedule daily.
6. 주간 retro: merged PR 스캔, 변경 API 참조 docs flag, 업데이트 PR open. Schedule weekly.
7. 야간 backlog grooming: 이슈 라벨 + owner assign + Slack 요약. Schedule weeknight.
8. CI 빌드 폴링: 외부 잡 ETA 대기. /loop 동적 모드.
9. PR 리뷰 큐 polling: 리뷰 큐 모니터링. /loop 동적 모드.
10. Morning briefing (9 AM) + 주간 요약: 평일 오전 9시 dev brief. Routines schedule.
11. AI 뉴스 큐레이션 일일 다이제스트: Routines + connector(Slack/Notion).

11개 모두 공식 docs 또는 Builder.io, DEV Community, DevOps.com 같은 검증된 기술 매체에서 확인된 사례입니다.

한국 환경 적용: KST cron과 영업일 표현식

KST timezone 처리

• /loop, /schedule (CLI): 로컬 timezone 자동. Asia/Seoul 환경이면 KST 그대로 동작.
• Routines (web): "로컬 시각" 입력 → 자동 변환. 실제 인프라 위치 무관.
• 수동 cron 작성 시: routines 일부 환경은 UTC default이라 변환 필요. KST 9시 = UTC 0시.

한국 영업일 cron 예시

0 9 * * 1-5    # 평일 오전 9시 (월~금)
0 18 * * 1-5   # 평일 오후 6시 퇴근 리포트
0 10 * * 1     # 매주 월요일 오전 10시 (주간 회고)
0 9 1 * *      # 매월 1일 오전 9시 (월간 리포트)
*/30 9-18 * * 1-5  # 평일 영업시간 30분 간격 폴링

⚠ 다시 강조: 7-field syntax(L, W, ?, MON/JAN alias)는 미지원입니다.

선택 가이드: /loop vs Routines

질문: 노트북 닫아도 동작해야 하나?
├── YES → Routines (클라우드, 일일 한도, 1시간 최소 간격)
└── NO  → /loop (세션 내부, 50개 한도, 7일 만료)
         │
         ├── 고정 cadence (매일 9시 등)
         │   → /loop "every 1 hour" 같은 interval 표기
         │
         └── 외부 조건 대기 (빌드/PR/API ETA)
             → /loop (interval 생략) → ScheduleWakeup 동적 모드

한 줄 결정 트리

• 매일 아침 dev brief가 안 와요 → Routines로 옮기세요 (노트북 닫혀도 도는 작업).
• 빌드 ETA 폴링 중이세요 → /loop 동적 모드가 맞아요 (세션 열린 동안만).
• ScheduleWakeup prompt에 슬래시 커맨드 넣지 마세요 → $1+ 비용 폭주합니다.
• delaySeconds=300 근처는 피하세요 → 270 이하 또는 1200 이상으로.
• 매시간 폴링은 Pro 플랜으론 안 됩니다 → Max(15/일) 이상 또는 launchd 같은 OS 레벨로.

비용 폭주 방지 체크리스트

세션과 비용을 안전하게 운영하려면 5개를 정기 점검하세요.

1. /loop task 50개 한도: CronList로 매주 1회 정리.
2. routines 일일 한도: 한도 초과 시 다음날까지 실행 불가. Max 이상 플랜으로 매시간 폴링 운영.
3. GitHub 트리거 hourly cap: webhook 폭주 시 drop. CI 워크플로우에서 webhook 발사 신중.
4. ScheduleWakeup re-fire: 슬래시 커맨드 prompt 절대 금지.
5. 7일 자동 만료: /loop은 자동 정리되니, 영구 작업은 routines로 마이그레이션.

결론: 3계층을 헷갈리면 자동화가 안 됩니다

Claude Code 스케줄링의 본질은 단순합니다.

• /loop: 세션 안에서 50개까지, 7일 만료. 빌드 폴링 같은 단기 작업.
• ScheduleWakeup: /loop 동적 모드. 5분 캐시 TTL 충돌 주의, 슬래시 커맨드 금지.
• Routines: 클라우드 실행, 노트북 닫혀도 동작. 플랜별 일일 한도, 최소 1시간 간격.

매일 아침 9시 리포트가 안 오나요? 거의 확실히 /loop을 routines로 옮기지 않았기 때문입니다. ScheduleWakeup으로 매번 토큰이 폭주하나요? prompt에 슬래시 커맨드를 넣었기 때문입니다.

세 가지를 구분하고 함정 3개만 피하면, Claude Code 자동화는 새로운 차원으로 갑니다.

출처

• Run prompts on a schedule — Claude Code Docs
• Automate work with routines — Claude Code Docs
• Prompt caching — Claude API Docs
• Trigger a routine via API — Claude API Docs
• GitHub Issue #54086 — ScheduleWakeup re-fires slash commands
• GitHub Issue #51304 — ScheduleWakeup with a slash-command prompt re-enters that slash command
• Introducing routines in Claude Code | Claude Blog
• Lessons from building Claude Code: Prompt caching is everything | Claude Blog