IT / AI
Claude Code /loop, 공식 수치 5가지 직접 확인했습니다
반복 작업을 자동화한다는 말은 맞습니다. 그런데 막상 써보면 “이게 다야?” 싶은 순간이 꽤 빨리 옵니다. 터미널 하나 닫았을 뿐인데 50개 예약이 모두 사라지는 구조, 공식 문서에 그대로 나와 있습니다.
/loop가 뭔지, 어떻게 쓰는 건지
Claude Code /loop는 2026년 3월 7일, v2.1.71에서 처음 탑재된 반복 실행 명령어입니다. (출처: Claude Code 공식 문서 — 예약 작업, 2026.03) CLI 세션이 열려 있는 동안, 지정한 간격마다 Claude가 스스로 정해진 작업을 실행합니다. 코드를 직접 짜서 cron을 설정할 필요 없이, 자연어 한 줄로 Claude가 알아서 타이머를 만들어 줍니다.
기본 문법은 간단합니다. /loop [간격] [작업 내용] 형태입니다. 간격을 생략하면 기본값은 10분으로 설정됩니다.
예시 명령어
/loop 5m check if the deployment finished and tell me what happened
/loop 30m 모든 open PR의 CI 상태를 확인하고 실패 항목을 알려줘
/loop 2h src/ 디렉토리 보안 취약점을 스캔해서 발견되면 PR 생성해줘
간격 단위는 s(초), m(분), h(시간), d(일)을 지원합니다. “7분”처럼 cron에서 어색한 값도 Claude가 자동으로 적절한 cron 표현식으로 바꿔줍니다. — 별도 cron 문법을 몰라도 됩니다.
공식 수치로 본 5가지 핵심 스펙
Claude Code 공식 문서 Scheduled Tasks 페이지에 /loop의 스펙이 표로 정리되어 있습니다. (출처: code.claude.com/docs/ko/scheduled-tasks) 아래 다섯 수치는 직접 확인한 내용입니다.
| 항목 | 공식 수치 | 의미 |
|---|---|---|
| 최소 실행 간격 | 1분 | 1분보다 짧게는 설정 불가 |
| 기본 실행 간격 | 10분 | 간격 생략 시 자동 적용 |
| 세션당 최대 cron 수 | 50개 | 동시에 만들 수 있는 작업 상한 |
| 자동 만료 기간 | 3일 | 3일 초과 시 자동 삭제 |
| 타이밍 오차 | ±10% | 정각 기준 최대 15분 흔들림 가능 |
타이밍 오차 ±10%가 체감상 생각보다 큽니다. 공식 문서에 “`:00`에 예약하면 `:06`에 실행될 수 있다”라고 나옵니다. 실시간 알림이 핵심인 작업에는 간격을 조금 여유있게 잡을 필요가 있습니다.
세션 닫으면 전부 사라집니다 — 공식 확인
“/loop를 설정해두면 백그라운드에서 알아서 돌겠지”라고 기대하기 쉽습니다. 실제로는 다릅니다. 공식 문서에 중단 조건이 명확하게 나와 있습니다. 터미널 종료, 세션 로그아웃, SSH 연결 끊김 — 이 세 가지 중 하나만 발생해도 해당 세션에서 만든 모든 /loop 작업이 사라집니다.
⚠️ 공식 문서 확인 사항
“Persistent across restarts: No (session-scoped)”
— Claude Code 공식 문서, Scheduled Tasks 비교표, 2026.03
이 제약은 Cloud 스케줄이나 Desktop 스케줄 방식과 가장 크게 차별되는 지점입니다. 즉, /loop는 “지금 이 세션 안에서만 사는 타이머”입니다. 개발자 커뮤니티에서 이 제약을 보완하는 별도 도구(Cronde 등)가 나온 것도 이 이유 때문입니다. — 세션이 닫히면 놓친 작업 재실행도 없습니다. (출처: Reddit r/ClaudeAI, Cronde 프로젝트, 2026.03.11)
💡 공식 문서와 실제 커뮤니티 반응을 같이 놓고 보니 이런 차이가 보였습니다
공식 문서는 “세션 범위”라고 짧게 언급합니다. 실제 커뮤니티에서는 “CI/CD 파이프라인에 쓰려고 했는데 터미널 닫는 순간 날아갔다”는 사례가 여럿 보입니다. 공식 비교표에서 /loop의 “Requires open session: Yes”를 확인한 뒤 사용 목적을 먼저 정하는 게 순서입니다.
Cloud 스케줄과 /loop는 아예 다른 도구입니다
Claude Code에서 반복 작업을 예약하는 방법은 세 가지입니다. /loop만 알고 있으면 나머지 두 가지에서 얻을 수 있는 이점을 놓칩니다. 공식 문서의 비교표를 직접 정리했습니다. (출처: code.claude.com/docs/ko/web-scheduled-tasks)
| 항목 | Cloud 스케줄 | Desktop 스케줄 | /loop (CLI) |
|---|---|---|---|
| 실행 위치 | Anthropic 클라우드 | 내 머신 | 내 머신 |
| 머신 켜야 함 | ❌ 불필요 | ✅ 필요 | ✅ 필요 |
| 세션 열어야 함 | ❌ 불필요 | ❌ 불필요 | ✅ 필수 |
| 재시작 후 유지 | ✅ 유지 | ✅ 유지 | ❌ 사라짐 |
| 로컬 파일 접근 | ❌ 불가 | ✅ 가능 | ✅ 가능 |
| 최소 간격 | 1시간 | 1분 | 1분 |
Cloud 스케줄은 머신을 켜둘 필요가 없는 대신 로컬 파일에 접근하지 못합니다. — PR 생성, 코드 리뷰 요약처럼 GitHub과만 연동하는 작업에 적합합니다. /loop는 로컬 파일을 직접 건드릴 수 있는 대신 세션이 살아있어야 합니다. 코드 품질 스캔이나 로컬 빌드 모니터링처럼 내 컴퓨터 파일 시스템을 직접 다루는 작업에 맞습니다.
비용을 생각하면 간격 설정이 전부입니다
/loop 실행 한 번 = Claude API 요청 한 번입니다. 작업 복잡도에 따라 소모 토큰이 크게 달라집니다. 실측 추정치를 참고하면 간격 전략을 잡는 데 도움이 됩니다.
💡 토큰 소모 패턴을 가격과 같이 놓고 보니 간격이 전략이 됐습니다
공식 문서 외에 실사용 커뮤니티 자료를 교차 분석한 결과입니다. 작업 유형별 추정 토큰 소모량과 적정 간격을 정리했습니다.
| 작업 유형 | 1회 추정 토큰 | 권장 간격 | 이유 |
|---|---|---|---|
| 서비스 상태 체크 | 약 500~1,000 | 5분 | 가볍고 긴급도 높음 |
| CI 상태 + PR 확인 | 약 1,000~3,000 | 10~15분 | 중간 무게, 실시간성 보통 |
| 보안 취약점 스캔 | 약 5,000~10,000 | 2시간 이상 | 무겁고 긴급도 낮음 |
| 일일 보고서 생성 | 약 3,000~8,000 | 24시간 | 주기 길수록 낭비 없음 |
토큰 추정치는 apiyi.com 실사용 분석 자료를 참고한 추정입니다. 실제 소모량은 프로젝트 규모에 따라 달라집니다. 무거운 작업을 5분 간격으로 돌리면 API 비용이 생각보다 빠르게 쌓입니다. — 가볍게 자주, 무겁게 드물게가 기본 원칙입니다.
Max 또는 Pro 플랜 구독자는 /loop 자체 사용에 제한이 없지만, 구독 사용량 한도와 별개로 반복 실행에서 생기는 토큰 소모를 추적할 필요가 있습니다. Claude Code는 기본적으로 30일이 지난 세션을 자동 삭제합니다. — 비용 추적이 필요하다면 cleanupPeriodDays 설정을 꺼야 합니다. (출처: Claude Code 공식 커뮤니티 게시물, 2026.01)
실전 프롬프트 패턴 — 바로 붙여넣기용
/loop 프롬프트를 잘 쓰려면 네 가지를 포함하는 게 좋습니다. 간격 + 작업 범위 + 알림 조건 + 행동 방안입니다. 아래는 바로 붙여넣어 쓸 수 있도록 정리한 패턴입니다.
📌 PR 순찰 — 가장 자주 쓰는 패턴
/loop 10m 모든 open PR의 CI 상태를 확인해줘. 새로 실패한 항목이 있을 때만 어떤 PR인지, 실패 원인이 무엇인지 알려줘
“있을 때만 알려줘” 조건을 넣으면 10분마다 불필요한 출력이 쌓이지 않습니다.
📌 배포 후 회귀 테스트 — 자동 종료 조건 포함
/loop 2m npm test -- --testPathPattern="critical"을 실행하고 결과를 확인해. 테스트 실패 시 즉시 알려주고, 3회 연속 통과하면 중지해
“3회 통과 시 중단” 조건을 달면 불필요한 반복 소모를 줄일 수 있습니다.
📌 로컬 서비스 헬스체크 — 가장 가벼운 패턴
/loop 5m curl localhost:3000/health, 200 외의 상태 코드나 타임아웃이 발생하면 즉시 에러 로그를 알려줘
간단한 curl 결과만 확인하므로 1회 실행 토큰 소모가 500 이하로 줄어듭니다.
💡 /loop와 Hooks를 연결하면 제어 범위가 달라집니다
/loop 단독으로는 결과를 터미널에 출력하는 수준에 그칩니다. 그런데 v2.1.78에서 추가된 PostToolUse Hook, StopFailure Hook과 조합하면 외부 알림 파일 기록, 특정 조건에서 자동 중단 같은 동작까지 연결할 수 있습니다. /loop가 시작점이고, Hook이 그 다음 레이어입니다.
Q&A 5가지
마치며
Claude Code /loop는 분명히 유용합니다. 코드 한 줄 없이 자연어 한 줄로 반복 작업을 예약할 수 있고, 로컬 파일에 직접 접근할 수 있다는 점은 다른 Cloud 방식이 줄 수 없는 강점입니다. 그런데 솔직히 말하면, 처음엔 기대했던 것과 달랐습니다. “알아서 돌아가는 자율 AI”처럼 홍보되지만, 실제로는 터미널 하나 닫는 순간 리셋되는 구조입니다.
이 점이 나쁘다는 게 아닙니다. /loop의 강점은 세션 안에서의 유연함에 있습니다. 개발 중에 배포 모니터링, PR 순찰, 로컬 빌드 체크처럼 “지금 이 세션에서만 필요한 자동화”에는 가장 빠르고 간편한 선택입니다. 24시간 지속 작업이 필요하다면 Cloud 스케줄이나 Desktop 스케줄 쪽이 맞습니다. 세 가지를 모두 알아야 상황에 맞는 도구를 고를 수 있습니다.
공식 문서의 비교표를 한 번이라도 보고 시작하면 시행착오를 줄일 수 있습니다. 링크는 아래 참고 자료에 있습니다.
본 포스팅 참고 자료
- Claude Code 공식 문서 — 예약 작업 (code.claude.com)
- Claude Code 공식 문서 — Cloud 스케줄 작업 (code.claude.com)
- Google for Developers 위클리 업데이트 2026년 3월 1주차
- Reddit r/ClaudeAI — Cronde 프로젝트 소개, 2026.03.11
- dev.to — Claude Code 2026년 3월 업데이트 총정리, 2026.03.21
본 포스팅 작성 이후 서비스 정책·UI·기능이 변경될 수 있습니다. Claude Code는 지속적으로 업데이트되며, 버전별로 동작이 달라질 수 있습니다. 최신 정보는 Claude Code 공식 문서에서 확인하세요.
댓글 남기기