Scheduled Tasks (스케줄 작업)

Scheduled Tasks를 사용하면 Claude가 지정한 간격으로 프롬프트를 자동으로 반복 실행합니다. (출처: 공식 문서)

개요

Scheduled Tasks는 배포 상태 폴링, PR 모니터링, 장시간 빌드 감시, 세션 중 리마인더 설정 등에 활용할 수 있는 기능입니다.

중요한 제한 사항: 작업은 **세션 범위(session-scoped)**입니다. Claude Code 프로세스가 실행 중인 동안만 유지되며, 터미널을 종료하면 모든 작업이 사라집니다.

재시작 후에도 지속되는 자동화가 필요하다면 Desktop Scheduled Tasks 또는 GitHub Actions를 사용하세요.

/loop 명령어로 반복 작업 설정

/loop 내장 스킬이 가장 빠른 방법입니다. 간격과 프롬프트를 전달하면 Claude가 백그라운드에서 실행되는 cron 작업을 설정합니다.

/loop 5m 배포가 완료되었는지 확인하고 결과를 알려줘

Claude는 간격을 파싱하여 cron 표현식으로 변환하고, 작업을 등록한 뒤 실행 주기와 작업 ID를 확인해 줍니다.

간격 문법

간격 표기는 유연하게 지정할 수 있습니다. 앞에 붙이거나, 뒤에 붙이거나, 아예 생략할 수 있습니다.

형식	예시	실행 주기
앞에 붙이기	`/loop 30m 빌드 확인`	30분마다
뒤에 붙이기	`/loop 빌드 확인 every 2 hours`	2시간마다
생략	`/loop 빌드 확인`	기본값: 10분마다

지원 단위: s (초), m (분), h (시간), d (일)

주의사항:

초 단위는 분으로 반올림됩니다 (cron의 최소 단위가 1분이기 때문)
7m, 90m처럼 나누어 떨어지지 않는 간격은 가장 가까운 깔끔한 간격으로 반올림됩니다

다른 명령어를 루프로 실행

스케줄 프롬프트 자체가 다른 명령어나 스킬 호출이 될 수 있습니다.

/loop 20m /review-pr 1234

작업이 실행될 때마다 /review-pr 1234를 직접 입력한 것처럼 Claude가 실행합니다.

일회성 리마인더 설정

반복이 아닌 단발성 실행이 필요하면 자연어로 설명하면 됩니다.

오후 3시에 릴리즈 브랜치 푸시하라고 알려줘

45분 후에 통합 테스트가 통과했는지 확인해줘

Claude가 특정 분·시각에 맞는 cron 표현식으로 고정하여 등록합니다.

작업 관리

등록된 작업을 확인하거나 취소하려면 자연어로 요청하세요.

원하는 동작	입력 예시	내부 도구
작업 목록 확인	"지금 스케줄 작업이 뭐가 있어?"	CronList
작업 취소	"배포 확인 작업 취소해줘"	CronDelete

내부 도구 (Tools)

도구	설명
`CronCreate`	새 작업 등록. 5필드 cron 표현식, 실행할 프롬프트, 반복/단발 여부를 받습니다.
`CronList`	등록된 작업 목록을 ID, 스케줄, 프롬프트와 함께 조회합니다.
`CronDelete`	ID로 작업을 취소합니다.

제한: 각 작업은 8자리 ID를 가지며, 세션당 최대 50개의 작업을 등록할 수 있습니다.

실행 방식

실행 타이밍

스케줄러는 매초 실행 예정 작업을 확인하고 낮은 우선순위로 큐에 추가합니다.
응답 중에는 실행되지 않습니다. Claude가 답변하는 도중이 아닌, 턴과 턴 사이에 실행됩니다.
Claude가 바쁜 상태일 때 작업이 도래하면, 현재 턴이 끝날 때까지 대기합니다.
모든 시각은 로컬 타임존 기준입니다 (UTC가 아님).

지터(Jitter)

스케줄 작업은 의도적인 지연이 적용됩니다.

반복 작업: 주기의 최대 10%까지 늦게 실행될 수 있으며, 최대 15분으로 제한됩니다.
일회성 작업: 정각(:00) 또는 반각(:30)으로 설정된 경우 최대 90초 일찍 실행될 수 있습니다.
지터는 작업 ID에서 결정론적으로 계산됩니다.

지터를 피하려면: :00이나 :30이 아닌 분을 선택하세요. 예를 들어 0 9 * * * 대신 3 9 * * *을 사용합니다.

3일 만료

반복 작업은 생성 후 3일이 지나면 자동으로 만료됩니다.
만료되기 전에 마지막으로 한 번 실행된 후 자동 삭제됩니다.
연장하려면 만료 전에 취소하고 다시 등록하거나, Desktop Scheduled Tasks를 사용하세요.

Cron 표현식 참조 (5필드)

분 시 일 월 요일

표현식	실행 주기
`/5 * * *`	5분마다
`0 * * * *`	매 정시
`7 * * * *`	매 시각 7분에
`0 9 * * *`	매일 오전 9시
`0 9 * * 1-5`	평일 오전 9시
`30 14 15 3 *`	3월 15일 오후 2시 30분

요일 숫자: 0 또는 7이 일요일, 6이 토요일

L, W, ?, MON, JAN 등의 확장 구문은 지원되지 않습니다.

스케줄 작업 비활성화

스케줄러 전체를 끄려면 환경 변수를 설정하세요.

export CLAUDE_CODE_DISABLE_CRON=1

제한 사항

제한	설명
실행 조건	Claude Code가 실행 중이고 유휴 상태일 때만 동작
터미널 종료	터미널을 닫으면 모든 작업이 취소됨
미실행 보완 없음	놓친 실행에 대한 catch-up이 없음
재시작 후	재시작 후 작업이 유지되지 않음

활용 예시

배포 모니터링

/loop 3m 프로덕션 배포가 완료되었는지 확인하고, 완료되면 버전 번호도 알려줘

PR 자동 검토

/loop 15m /review-pr 4521

빌드 상태 확인

/loop 5m CI 빌드 상태 확인하고 실패한 테스트가 있으면 알려줘

작업 리마인더

30분 후에 스테이징 서버에서 스모크 테스트 실행했는지 알려줘

일과 종료 체크

오후 6시에 오늘 커밋 안 된 변경사항이 있는지 확인해줘

지속성이 필요한 경우

세션이 닫혀도 유지되는 자동화가 필요하다면:

Desktop Scheduled Tasks: 데스크탑 앱의 스케줄 기능 (터미널 없이 실행, 재시작 후 유지)
GitHub Actions: schedule 트리거를 사용한 CI/CD 자동화 (관련 가이드 참조)

추가 자료

팁: 장시간 빌드나 배포를 기다릴 때 /loop를 사용하면 수동으로 확인하지 않아도 Claude가 주기적으로 상태를 알려줍니다. 터미널을 열어두기만 하면 됩니다.