스케줄 (Schedule)
스케줄이란?
스케줄(Schedule)은 Claude Code에서 프롬프트를 주기적으로 자동 실행하는 기능입니다. 배포 상태를 모니터링하거나, PR 머지를 확인하거나, 빌드 결과를 주기적으로 체크하는 등의 반복 작업을 자동화합니다.
스케줄 유형 비교
실행 주기: 최소 1시간
컴퓨터: 불필요
지속성: 영구 유지
무인 자동화, 보안 스캔, 의존성 업데이트
실행 주기: 최소 1분
컴퓨터: 앱 실행 필요
지속성: 재시작 후 유지
로컬 파일 접근, CI 감시, 빌드 확인
실행 주기: 최소 1분
컴퓨터: 세션 열려있어야
지속성: 세션 종료 시 삭제
빠른 폴링, 배포 모니터링, 일회성 작업
세 가지 스케줄 유형
| 유형 | 실행 위치 | 컴퓨터 켜야 하나 | 지속성 | 최소 간격 | 적합한 작업 |
|---|---|---|---|---|---|
| 클라우드 | Anthropic 클라우드 | 아니오 | 영구 | 1시간 | 무인 자동화 |
| 데스크탑 | 내 컴퓨터 | 예 (앱 실행) | 재시작 후에도 유지 | 1분 | 로컬 파일 접근 필요 |
| /loop | 내 컴퓨터 | 예 (세션 열림) | 세션 종료 시 삭제 | 1분 | 빠른 일회성 폴링(Polling) |
스케줄 생성 방법
웹/클라우드에서 생성
claude.ai/code에서 클라우드 스케줄을 생성할 수 있습니다:
- claude.ai/code 접속
- 새 세션 생성 또는 기존 세션 열기
- 자연어로 스케줄 요청:
매일 오전 9시에 main 브랜치의 테스트를 실행하고 결과를 알려줘
클라우드 스케줄은 컴퓨터가 꺼져 있어도 실행됩니다. Git 저장소를 클론하여 클라우드 VM에서 작업합니다.
Desktop 앱에서 생성
Claude Desktop 앱의 Code 세션에서 직접 스케줄을 설정합니다:
- Desktop 앱에서 Code 세션 열기
- 자연어로 스케줄 요청:
30분마다 빌드 상태를 확인해줘
Desktop 스케줄은 사이드바에 표시되며, 각 실행 결과를 세션 내에서 확인할 수 있습니다.
CLI에서 /loop으로 생성
현재 세션에서 프롬프트를 주기적으로 반복 실행합니다. 가장 빠르게 스케줄을 설정하는 방법입니다.
/loop [간격] <프롬프트>
/loop - 빠른 반복 실행
기본 사용법
/loop [간격] <프롬프트>
사용 예시
# 5분마다 배포 상태 확인
/loop 5m 배포가 완료되었는지 확인해줘
# 30분마다 PR 머지 확인
/loop 30m PR이 머지되었는지 확인해줘
# 2시간마다 빌드 실행
/loop every 2 hours 빌드를 실행해줘
# 10분마다 빌드 확인 (뒤에 간격 지정)
/loop 빌드 상태를 확인해줘 every 10 minutes
# 간격 생략 시 기본값 10분
/loop 빌드 상태를 확인해줘
간격 표기법
| 표기 | 의미 | 예시 |
|---|---|---|
s | 초 (분 단위로 반올림) | 30s → 1분 |
m | 분 | 5m → 5분 |
h | 시간 | 2h → 2시간 |
d | 일 | 1d → 24시간 |
간격은 앞(/loop 5m ...)이나 뒤(/loop ... every 5 minutes) 어디에나 넣을 수 있습니다.
/loop 라이프사이클
/loop 5m <프롬프트> 실행
│
▼
┌─── 루프 등록 (세션 내부에 크론 작업 생성) ──┐
│ │
│ ┌──────────────────────────────┐ │
│ │ ⏳ 대기 (5분 타이머) │ │
│ └──────────┬───────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────┐ │
│ │ 🔍 유휴 상태 확인 │ │
│ │ └─ 바쁨 → 유휴 때까지 대기 │ │
│ │ └─ 유휴 → 프롬프트 실행 │ │
│ └──────────┬───────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────┐ │
│ │ 📋 프롬프트 실행 │ │
│ │ └─ 성공 → 결과 표시 │ │
│ │ └─ 실패 → 에러 보고 │ │
│ └──────────┬───────────────────┘ │
│ │ │
│ └──── 다시 대기 (반복) ──────────┘
│ │
│ ⚡ 7일 후 자동 만료 │
│ ⚡ 세션 종료 시 즉시 삭제 │
└──────────────────────────────────────────────┘
다른 스킬과 조합
# 20분마다 디버그 스킬 반복 실행
/loop 20m /debug
# 1시간마다 테스트 실행
/loop 1h npm test를 실행하고 결과를 알려줘
일회성 리마인더
자연어로 한 번만 실행되는 리마인더를 설정할 수 있습니다:
오후 3시에 릴리스 브랜치를 푸시하라고 알려줘
45분 후에 통합 테스트가 통과했는지 확인해줘
Claude가 1회 실행 후 자동 삭제되는 크론(Cron) 작업을 생성합니다.
스케줄 작업 관리
자연어로 관리
# 현재 스케줄 목록 확인
지금 어떤 스케줄 작업이 있어?
# 특정 작업 취소
배포 확인 작업을 취소해줘
도구로 관리
| 도구 | 설명 |
|---|---|
CronCreate | 새 스케줄 작업 생성 (5필드 크론 표현식) |
CronList | 모든 작업 목록과 ID 확인 |
CronDelete | ID로 작업 삭제 |
크론 표현식
표준 5필드 형식을 사용합니다: 분 시 일 월 요일
| 표현식 | 의미 |
|---|---|
*/5 * * * * | 5분마다 |
0 * * * * | 매 정시 |
0 9 * * * | 매일 오전 9시 |
0 9 * * 1-5 | 평일 오전 9시 |
30 14 15 3 * | 3월 15일 오후 2시 30분 |
문법:
- 와일드카드:
*(매번) - 단일 값:
5(5분) - 스텝:
*/15(15분마다) - 범위:
1-5(1~5) - 목록:
1,15,30(1, 15, 30)
동작 특성
시간대
로컬 시간대를 사용합니다 (UTC가 아님). 한국에서 사용하면 KST 기준으로 동작합니다.
# 한국에서 사용하면 KST(UTC+9) 기준
# 크론 표현식 "0 9 * * *"는 한국 시간 오전 9시
현재 시스템 시간대를 확인하려면:
date +%Z # KST가 출력되면 한국 시간대
지터 (Jitter)
반복 작업은 설정된 간격의 최대 10%까지 지연될 수 있습니다 (최대 15분). API 과부하를 방지하기 위한 장치입니다.
지터 계산 예시:
| 설정 간격 | 최대 지터 | 실제 실행 범위 |
|---|---|---|
| 5분 | 30초 (5분 × 10%) | 5분 00초 ~ 5분 30초 |
| 1시간 | 6분 (60분 × 10%) | 1시간 00분 ~ 1시간 06분 |
| 2시간 | 12분 (120분 × 10%) | 2시간 00분 ~ 2시간 12분 |
| 3시간 이상 | 15분 (최대 캡) | 3시간 00분 ~ 3시간 15분 |
같은 작업 ID는 항상 같은 오프셋을 받으므로, 매번 동일한 시간에 실행됩니다.
일회성 작업이 :00이나 :30에 설정된 경우 최대 90초 일찍 실행될 수 있습니다. 같은 작업 ID는 항상 같은 오프셋을 받습니다.
7일 만료
반복 작업은 7일 후 자동 삭제됩니다. 잊혀진 루프가 무한히 실행되는 것을 방지합니다.
유휴 시 실행
스케줄 작업은 Claude가 응답 중이 아닐 때(유휴 상태)에만 실행됩니다. Claude가 바쁠 때 예정된 작업은 유휴 상태가 되면 1회 실행됩니다 (밀린 작업을 반복 실행하지 않음).
비용 영향 분석
스케줄 작업은 각 실행마다 토큰을 소비합니다. 빈번한 스케줄은 비용에 큰 영향을 미칠 수 있습니다.
토큰 사용 추정
| 스케줄 유형 | 실행 빈도 | 일일 실행 횟수 | 예상 토큰/회 | 일일 총 토큰 |
|---|---|---|---|---|
| 상태 확인 (간단) | 5분 | 288회 | ~500 | ~144,000 |
| 테스트 실행 | 1시간 | 24회 | ~5,000 | ~120,000 |
| 코드 분석 | 1일 | 1회 | ~20,000 | ~20,000 |
| 보안 스캔 | 1일 | 1회 | ~50,000 | ~50,000 |
5분 간격의 스케줄은 하루에 288번 실행됩니다. Pro 플랜의 일일 토큰 한도를 빠르게 소진할 수 있으므로, 최소한의 빈도로 설정하세요. 단순 상태 확인은 10~30분, 복잡한 분석은 1시간 이상의 간격을 권장합니다.
비용 최적화 팁
| 방법 | 설명 |
|---|---|
| 간격 늘리기 | 5분 → 30분으로 변경하면 토큰 사용 6배 감소 |
| 조건부 실행 | "변경이 있을 때만" 상세 분석하도록 프롬프트 작성 |
| 간결한 프롬프트 | 필요한 정보만 요청하여 출력 토큰 최소화 |
| 클라우드 스케줄 활용 | 최소 1시간 간격으로 불필요한 실행 방지 |
| 7일 만료 활용 | 임시 모니터링은 /loop으로 자동 정리 |
스케줄링 규모와 모범 사례
스케줄 제한
| 항목 | 제한 |
|---|---|
/loop 작업 (세션당) | 최대 50개 |
| Desktop 스케줄 | 실질적 제한 없음 (시스템 리소스에 따라) |
| 클라우드 스케줄 | 계정 플랜에 따라 제한 |
| 최소 간격 (클라우드) | 1시간 |
| 최소 간격 (/loop, Desktop) | 1분 |
많은 스케줄 운영 시 팁
- 우선순위 지정: 중요한 스케줄은 클라우드로, 임시 모니터링은 /loop으로
- 간격 분산: 여러 스케줄이 같은 시간에 실행되지 않도록 분산 (예:
:00,:15,:30,:45) - 그룹화: 관련 작업을 하나의 프롬프트로 묶어 실행 횟수 줄이기
- 정기 정리:
CronList로 불필요한 스케줄 확인하고 삭제
연계 기능
장점, 단점과 한계점
장점
- 반복 작업 완전 자동화: 배포 상태 확인, CI 감시, 보안 스캔 등 주기적 작업을 사람 개입 없이 자동으로 수행합니다
- 3가지 스케줄 방식 제공: 클라우드(무인 자동화), 데스크탑(로컬 파일 접근), /loop(빠른 일회성 폴링) 중 상황에 맞는 방식을 선택할 수 있습니다
- 웹/Desktop/CLI 모두 설정 가능: claude.ai/code, Desktop 앱, CLI의 /loop 명령 등 어떤 환경에서든 스케줄을 생성하고 관리할 수 있습니다
- 지터(Jitter)로 부하 분산: 설정 간격의 최대 10%까지 실행 시간을 분산하여 API 과부하를 자동으로 방지합니다
단점과 한계점
- 실행 시간 예측 어려움: 지터로 인해 정확한 실행 시점을 보장할 수 없어, 초 단위 정밀 스케줄링이 필요한 작업에는 부적합합니다
- 실패 시 자동 재시도 없음: 스케줄 작업이 실패해도 자동 재시도하지 않고 다음 예정된 실행까지 기다려야 합니다
- 토큰 비용 누적: 5분 간격 스케줄은 하루 288회 실행되며, Pro 플랜의 일일 토큰 한도를 빠르게 소진할 수 있습니다
- 권한 프롬프트에서 멈춤 가능: 승인이 필요한 작업을 만나면 세션이 일시 중단되어 무인 운영이 중단될 수 있습니다
비용을 관리하려면 간격을 최대한 넓게 설정하고(5분 → 30분), "변경이 있을 때만" 상세 분석하도록 프롬프트를 작성하세요. 무인 운영 시에는 필요한 도구를 .claude/settings.json에서 미리 허용하여 권한 프롬프트를 방지할 수 있습니다.
/loop의 제한사항
- Claude Code가 열려 있고 유휴 상태일 때만 실행
- 세션을 종료하면 모든 /loop 작업이 삭제됨
- 세션당 최대 50개 작업
- 놓친 작업은 추후 보충 실행하지 않음
더 안정적인 대안
| 요구사항 | 추천 방식 |
|---|---|
| 컴퓨터 꺼도 실행 | 클라우드 스케줄 작업 |
| 재시작 후에도 유지 | 데스크탑 스케줄 작업 |
| 항상 실행 | 클라우드 세션 |
| CI/CD 연동 | GitHub Actions schedule 트리거 |
에러 처리
스케줄 작업이 실행 중 실패하면:
/loop: 에러를 보고하고 다음 주기에 다시 시도- Desktop 스케줄: 세션이 사이드바에 남아 있어 직접 확인 가능
- 클라우드 스케줄: claude.ai/code에서 실행 결과 확인
실패한 작업은 자동으로 재시도하지 않습니다. 다음 예정된 실행 시 새로운 세션으로 시작됩니다.
스케줄 비활성화
스케줄 기능을 완전히 끄려면:
export CLAUDE_CODE_DISABLE_CRON=1
이 환경변수를 설정하면 크론 도구와 /loop이 모두 비활성화됩니다.
채널과의 차이
| 구분 | 스케줄 | 채널 |
|---|---|---|
| 방식 | 폴링(Poll) — 주기적으로 확인 | 푸시(Push) — 이벤트 발생 시 즉시 |
| 트리거 | 시간 간격 | 외부 메시지 |
| 적합한 용도 | 상태 모니터링, 반복 점검 | 메시지 대응, 알림 반응 |
실전 활용 예시
배포 모니터링
# 배포 시작 후
/loop 5m 배포 상태를 확인하고, 완료되면 알려줘. 에러가 있으면 로그를 분석해줘.
CI 파이프라인(Pipeline) 감시
# PR 올린 후
/loop 10m GitHub Actions CI가 통과했는지 확인해줘. 실패하면 어떤 테스트가 실패했는지 알려줘.
주기적 코드 품질 체크
# 작업 중 주기적으로
/loop 1h 린트 에러가 없는지 확인하고, 있으면 수정해줘.
실전 예시: 일일 보안 취약점 스캔
매일 오전 9시에 프로젝트의 보안 취약점을 자동으로 스캔하고 보고서를 생성하는 스케줄입니다.
클라우드 스케줄로 설정:
매일 오전 9시에 다음 보안 점검을 수행해줘:
1. npm audit 실행하고 critical/high 취약점 확인
2. .env 파일에 하드코딩된 시크릿이 있는지 검사
3. package.json의 의존성 중 알려진 취약점 확인
4. 코드에서 SQL 인젝션, XSS 가능성 스캔
5. 결과를 security-report-{날짜}.md로 저장
6. critical 취약점이 있으면 GitHub 이슈 생성
크론 표현식:
0 9 * * * # 매일 오전 9시 (로컬 시간)
실행 결과 예시:
[2026-04-08 09:00 KST] 보안 스캔 결과:
- npm audit: 2 critical, 1 high, 5 moderate
- Critical: lodash < 4.17.21 (프로토타입 오염)
- Critical: axios < 1.6.0 (SSRF)
- 하드코딩 시크릿: 없음 ✅
- SQL 인젝션 가능성: src/api/users.ts:42 (WARNING)
- GitHub 이슈 #89 생성 완료
실전 예시: 주간 의존성 업데이트 자동화
매주 월요일 오전 10시에 의존성을 자동 업데이트하고 PR을 생성합니다.
클라우드 스케줄로 설정:
매주 월요일 오전 10시에 의존성 업데이트를 수행해줘:
1. git checkout -b deps/weekly-update-{날짜} main
2. npm outdated로 업데이트 가능한 패키지 확인
3. patch/minor 업데이트만 적용 (major는 목록만 보고)
4. npm audit fix로 보안 패치 적용
5. npm test 실행하여 테스트 통과 확인
6. 테스트 통과 시 PR 생성:
- 제목: "deps: 주간 의존성 업데이트 ({날짜})"
- 본문: 업데이트된 패키지 목록과 변경 이유
7. 테스트 실패 시 실패 원인을 분석하고 이슈 생성
크론 표현식:
0 10 * * 1 # 매주 월요일 오전 10시
Python 프로젝트 변형:
매주 월요일 오전 10시에:
1. pip-audit 실행하여 취약점 확인
2. pip list --outdated로 업데이트 가능 패키지 확인
3. requirements.txt의 patch 버전 업데이트
4. pytest 실행하여 테스트 검증
5. 결과를 PR로 생성