예약 작업 (scheduled tasks) 은 세션이 열려 있는 동안 같은 프롬프트를 정해진 주기로 자동으로 다시 실행해 주는 Claude Code의 기능입니다. “5분마다 배포 끝났는지 확인해 줘"라고 한 번만 말해 두면, 그 뒤로는 내가 다시 입력하지 않아도 Claude가 알아서 시간마다 들여다보는 셈입니다.

배경 참조

이 문서는 MoAI-ADK가 올라타 있는 플랫폼인 Claude Code 자체를 다루는 배경 자료입니다. MoAI-ADK 안에서 자율 루프를 어떻게 쓰는지는 자율 연속 루프에서 다룹니다.

정보

한 줄 요약: 배포 폴링, PR 돌보기, 정기 점검을 사람이 매번 다시 입력하지 않도록 /loop과 cron 도구에 맡기는, 세션에 묶인 가벼운 자동화입니다.

비유로 이해하기

예약 작업은 Claude에게 알람 시계를 맡겨 두는 것과 비슷합니다. “이 시간마다 이 일을 다시 봐 줘"라고 예약해 두면, Claude가 내가 한가로울 때 (정확히는 Claude의 턴과 턴 사이) 알람을 울려서 그 일을 꺼내 보여 줍니다. 알람은 내 방 (현재 세션) 안에서만 울리므로, 방을 바꾸면 (새 대화를 시작하면) 모두 꺼집니다.

예약 작업은 Claude Code v2.1.72 이상에서 사용할 수 있습니다. claude --version으로 버전을 확인합니다.

예약 작업은 한 프롬프트를 일정 주기로 자동으로 다시 실행하는 장치입니다. 배포가 끝났는지 폴링하거나, PR을 돌보거나, 오래 걸리는 빌드를 다시 들여다보거나, 나중에 할 일을 알려 주는 용도로 씁니다. 핵심은 “사람이 똑같은 말을 반복해서 입력하는 피로"를 기계 쪽으로 옮겨 주는 데 있습니다.

가장 중요한 성질은 세션 범위 (session-scoped) 라는 점입니다. 작업은 현재 대화 안에서만 살아 있고, 새 대화를 시작하면 모두 사라집니다. --resume이나 --continue로 세션을 이어 열면 아직 만료되지 않은 작업은 복원됩니다.

이 기능이 덮는 영역은 세션에 묶인 가벼운 폴링입니다. Claude Code에는 그 밖에도 스케줄링 옵션이 있어서, 어디서 실행되고 머신이 켜져 있어야 하는지가 다릅니다.

이벤트가 발생하는 즉시 반응해야 한다면 폴링 대신 Channels로 CI가 실패를 세션에 직접 밀어 넣게 합니다. 반대로 “어떤 조건이 충족될 때까지 매 턴 계속 일해 줘"라면 주기 실행이 아니라 목표 지향 실행 (/goal)이 맞는 도구입니다 — /loop는 시간이 됐으니 다시 들여다봐라는 시간 주도형, /goal은 조건이 만족될 때까지 멈추지 마라는 조건 주도형 자율 실행입니다.

예약 작업은 세션이 열려 있는 동안 짧게 반복하는 작업에 가장 잘 맞습니다.

패키징된 워크플로를 매 반복마다 다시 실행할 수도 있습니다. 예를 들어 /loop 20m /review-pr 1234처럼 프롬프트 자리에 다른 명령을 넘기면 됩니다.

/loop은 세션을 열어 둔 채 프롬프트를 반복 실행하는 가장 빠른 방법으로, 번들 스킬 (bundled skill) 형태로 제공됩니다. 간격과 프롬프트는 둘 다 선택이며, 무엇을 주느냐에 따라 동작이 달라집니다.

간격을 주면 Claude가 그 값을 cron 표현식으로 변환해 작업을 등록하고, 주기와 작업 ID를 확인해 줍니다. 간격은 30m처럼 앞에 두거나 every 2 hours처럼 뒤에 둘 수 있습니다. 지원 단위는 s (초), m (분), h (시간), d (일) 입니다. cron은 1분 단위이므로 초 단위는 올림 처리되고, 7m이나 90m처럼 깔끔하게 떨어지지 않는 간격은 가장 가까운 단위로 반올림한 뒤 무엇으로 정했는지 알려 줍니다.

간격을 생략하면 Claude가 고정 cron 대신 매 반복마다 1분에서 1시간 사이의 지연을 동적으로 고릅니다. 빌드가 끝나가거나 PR이 활발하면 짧게, 아무것도 대기 중이 아니면 길게 기다립니다 — “지금 당장 바쁘지 않으면 좀 더 천천히"라는 절약 본능이 코드로 옮겨진 셈입니다.

/loop check whether CI passed and address any review comments

프롬프트를 생략하면 Claude는 내장 유지보수 프롬프트 (maintenance prompt) 를 씁니다. 매 반복마다 다음 순서로 일을 처리합니다.

flowchart TD
    A["bare /loop 실행"] --> B["대화에서
미완 작업 이어서 처리"]
    B --> C["현재 브랜치 PR 돌보기
리뷰 코멘트·실패 CI·머지 충돌"]
    C --> D["할 일이 없으면
버그 헌트·단순화 등 정리"]
    D --> E["push·삭제 같은
비가역 작업은 기록이
이미 승인한 경우만 진행"]

bare /loop은 이 프롬프트를 동적 간격으로 실행하고, /loop 15m처럼 간격을 더하면 고정 주기로 실행합니다.

loop.md 파일을 두면 내장 유지보수 프롬프트를 내 지시문으로 대체합니다. 이 파일은 bare /loop을 위한 단일 기본 프롬프트를 정의하며, 명령줄에 프롬프트를 직접 주면 무시됩니다.

파일은 정해진 구조 없는 일반 Markdown입니다. /loop 프롬프트를 직접 입력하듯 작성합니다.

Check the `release/next` PR. If CI is red, pull the failing job log,
diagnose, and push a minimal fix. If new review comments have arrived,
address each one and resolve the thread. If everything is green and
quiet, say so in one line.

loop.md 수정은 다음 반복부터 반영되므로 루프가 도는 중에도 지시문을 다듬을 수 있습니다. 내용이 25,000바이트를 넘으면 잘립니다.

한 번만 실행할 알림은 /loop 대신 자연어로 설명합니다. Claude는 한 번 실행 후 자기 자신을 삭제하는 단발 작업 (one-shot task) 을 등록하고, 실행 시각을 특정 분·시로 고정해 알려 줍니다.

in 45 minutes, check whether the integration tests passed

작업 조회와 취소도 자연어로 요청하면 됩니다. 내부적으로 Claude는 다음 cron 도구를 사용합니다.

각 작업에는 CronDelete에 넘길 수 있는 8자 ID가 있고, 한 세션은 최대 50개의 작업을 보유할 수 있습니다. 대기 중인 /loop을 멈추려면 Esc를 누릅니다. 자연어로 예약한 작업은 Esc의 영향을 받지 않으며, CronDelete로 직접 지울 때까지 남아 있습니다.

스케줄러는 매초 만기 작업을 확인해 낮은 우선순위로 큐에 넣고, 예약된 프롬프트는 응답 도중이 아니라 턴과 턴 사이에 실행됩니다. 모든 시각은 로컬 타임존으로 해석되므로 0 9 * * *은 UTC가 아니라 Claude Code를 실행 중인 곳의 오전 9시를 뜻합니다.

• 지터 (jitter): 여러 세션이 같은 순간 API를 치지 않도록 작업 ID에서 파생한 결정적 오프셋을 더합니다. 반복 작업은 예약 시각 이후 최대 30분 늦게 발동할 수 있고, 일회성 작업은 최대 90초 일찍 발동할 수 있습니다. 정확한 타이밍이 필요하면 :00이나 :30이 아닌 분을 고릅니다.
• 7일 만료: 반복 작업은 생성 7일 뒤 마지막으로 한 번 발동한 뒤 자동으로 삭제됩니다.
• 누락 따라잡기 없음: Claude가 긴 요청으로 바쁜 동안 예약 시각이 지나면, 유휴 상태가 될 때 한 번만 발동할 뿐 놓친 횟수만큼 따라잡지는 않습니다.

스케줄러 전체를 끄려면 환경 변수 CLAUDE_CODE_DISABLE_CRON=1을 설정합니다. 그러면 cron 도구와 /loop을 사용할 수 없게 되고 이미 예약된 작업도 발동을 멈춥니다.

예약 작업이 “응답 도중이 아니라 턴 사이에” 발동한다는 점은 Claude Code의 백그라운드 실행 (background execution) 모델과 이어집니다. v2.1.198부터 백그라운드가 서브에이전트의 기본값이 된 것과 같은 맥락으로, 예약 작업도 메인 대화가 한가로워야만 (idle) 큐에서 꺼내집니다. Claude가 긴 도구 호출로 바쁘면 예약 시각이 지나도 대기하고, 턴이 끝나 비로소 유휴 상태가 됐을 때 한 번 발동합니다.

이런 성질 때문에 예약 작업은 실시간성이 필요한 트리거로는 부적합합니다. 정확히 그 점을 보완하려고 Channels가 존재합니다 — CI 실패 같은 이벤트를 폴링으로 기다리지 말고 세션에 직접 밀어 넣는 것이죠. 요약하면, “시간마다 들여다보는” 일은 /loop이, “이벤트가 오면 즉시” 반응하는 일은 Channels가 맡습니다.

예약 작업은 세션이 열려 있고 유휴 상태일 때만 발동합니다. 따라서 머신이 꺼져 있거나 세션 없이도 동작해야 하는 무인 자동화에는 적합하지 않습니다. 이런 경우에는 별도의 영속 스케줄링 옵션을 사용합니다.

CI 파이프라인이나 GitHub Actions의 schedule 트리거로 claude -p를 비대화 (headless) 로 호출하면 세션에 묶이지 않는 cron 자동화를 구성할 수 있습니다. 정리하면, 세션 안의 빠른 폴링은 /loop, 로컬 파일·도구 접근이 필요한 무인 작업은 Desktop 예약 작업, 머신과 무관하게 확실히 돌려야 하는 작업은 Routines를 씁니다.

MoAI-ADK 관점에서 예약 작업은 자율 실행 스펙트럼의 한 가지 방식입니다. 같은 “사람이 매번 개입하지 않는다"는 자율성이어도 동작 원리가 다릅니다.

실전에서는 /loop을 SPEC 구현 중인 PR 점검이나 CI 상태 추적에 가볍게 활용하고, 정기 릴리스 추적 같은 무인 작업은 GitHub Actions 쪽 스케줄링으로 분리하는 것이 모범 사례입니다. 한 가지 잊지 말아야 할 것은, 주기 실행은 매 반복이 토큰을 소비한다는 점입니다. 폴링 간격이 곧 비용 다이얼입니다 — 5분마다 돌리는 루프는 1분마다 돌리는 루프의 5분의 1 비용이 듭니다.

• 목표 지향 실행 (/goal) — 시간 주도형 /loop과 짝을 이루는 조건 주도형 자율 실행
• 다이내믹 워크플로우 — 스크립트가 수십~수백 에이전트를 한 번에 조율하는 대규모 오케스트레이션
• 훅 (Hooks)

• Scheduled tasks — Claude Code 공식 문서

팁

고정 주기 /loop은 7일 뒤 자동 만료되므로, 더 오래 돌려야 한다면 만료 전에 다시 등록하거나 처음부터 Routines·Desktop 예약 작업 같은 영속 스케줄링을 선택하는 편이 안전합니다. 그리고 폴링 간격을 정할 때 “이 주기가 정말 필요한가?“를 한 번 더 묻는 습관이 토큰 비용을 크게 줄여 줍니다.