Claude Code /loop 사용법: 반복 작업 예약·중지와 세션 재개 주의점

Claude Code에서 빌드 로그를 확인한 뒤 몇 분 후에 같은 질문을 다시 입력하는 일이 있습니다. Claude Code /loop는 이런 점검 프롬프트를 반복 실행하도록 예약하는 기능입니다. 로그 읽기, 배포 상태 확인, PR 진행 상황 확인처럼 같은 판단을 주기적으로 반복할 때 유용합니다.[1]

다만 “반복 예약”을 “터미널을 닫아도 영구 실행”으로 받아들이면 곤란합니다. /loop는 실행 중인 Claude Code 세션에 붙는 예약입니다. 이 글에서는 2.1.292의 읽기 전용 로그 점검으로 예약·실행·세션 재개·취소를 확인하고, 고정 간격과 자동 간격의 차이를 구분합니다.

/loop가 필요한 작업

/loop의 장점은 시간을 재는 것보다 같은 확인 요청을 다시 보내지 않아도 된다는 것입니다.

• 빌드 로그에 새로운 오류가 생겼는지 확인

• 배포 완료 여부와 실패 메시지 확인

• PR의 CI 상태와 새 리뷰 댓글 확인

• 오래 걸리는 작업이 끝났는지 확인

반대로 파일을 매분 수정하거나 실패할 때마다 자동으로 재배포하는 작업은 처음 실습에 적합하지 않습니다. 읽기 전용 점검으로 시작하고, 무엇을 읽을지·무엇을 보고할지·무엇을 하지 말아야 할지를 먼저 정합니다. 작업 범위를 나누는 방법은 터미널 반복 작업의 자동화 설계에서 이어서 볼 수 있습니다.

제품 화면이 아닌 개념도입니다. 핵심은 점검 결과를 확인한 뒤 작업을 명시적으로 중지하는 순서입니다. 이미지를 누르면 원본을 볼 수 있습니다.

예약에는 모델 호출과 도구 사용이 따라올 수 있습니다. 1분 간격은 동작을 빠르게 확인하는 실습용으로만 쓰고, 실제 작업에서는 5분·15분 등 필요한 간격으로 늘립니다.

고정 간격과 자동 간격

/loop 뒤에 무엇을 넣는지가 동작을 결정합니다.[1]

자동 간격은 관찰 결과에 따라 다음 대기를 1분에서 1시간 사이로 고릅니다. Monitor 도구가 있는 세션에서는 반복 폴링 대신 백그라운드 스크립트로 출력을 전달하는 방식을 선택할 수도 있습니다.[1]

내용 없는 /loop도 단순 타이머가 아닙니다. 공식 기본 프롬프트는 미완료 작업, 현재 브랜치의 PR, 정리 작업 순으로 살핍니다. 처음에는 기본 동작에 맡기기보다 간격과 읽기 전용 점검 내용을 함께 지정하는 방식이 이해하기 쉽습니다.

간격 표기와 실제 시각

간격에는 s·m·h·d를 씁니다. 각각 초·분·시간·일입니다.

/loop 5m build.log의 ERROR 줄 수와 마지막 오류를 확인해 줘

주의할 점은 세 가지입니다.

1. cron의 해상도는 1분입니다. 30s를 정확한 30초 반복으로 기대하면 안 됩니다.

2. 7m, 90m처럼 깔끔한 cron 간격으로 표현되지 않는 값은 지원 가능한 가까운 간격으로 조정되고, 선택한 값이 안내됩니다.

3. 반복 예약에는 실행 시각 분산인 jitter가 붙습니다. 한 시간보다 짧은 간격은 간격의 절반까지, 긴 간격은 최대 30분까지 예정 시각보다 늦게 실행될 수 있습니다.[1]

또 Claude가 응답 중이면 예약 프롬프트는 현재 턴이 끝날 때까지 기다립니다. 지정 간격은 실시간 시스템의 마감 시각 보장이 아닙니다.

실습 준비

이번 확인은 Linux, Claude Code 2.1.292, 로그인된 대화형 세션에서 진행했습니다. 운영 프로젝트 대신 별도 실습 폴더에 작은 샘플 로그를 두고, 실제 /loop 명령과 CronCreate·CronList·CronDelete의 결과를 확인했습니다. 아래 오류 줄은 실습용 데이터이지 실제 서비스 장애 기록이 아닙니다.

설치·인증이 아직 안 되어 있다면 Claude Code 첫 설치와 실행을 먼저 확인합니다. 이미 쓰고 있다면 셸에서 버전만 확인합니다.

claude --version

실습에 사용한 버전 출력은 다음과 같습니다.

2.1.292 (Claude Code)

기존 설치를 변경하지 않고 같은 패키지 버전으로 실행할 때는 다음처럼 버전을 고정할 수도 있습니다. npm 실행 환경과 기존 인증이 필요합니다.

npx -y @anthropic-ai/claude-code@2.1.292

실습은 예약 → 실행 확인 → 종료·재개 → 최종 취소 순서로 진행합니다. 재개를 확인하기 전에 예약을 삭제하지 않는 것이 중요합니다.

샘플 로그 준비

AI에게 아래처럼 요청하거나 편집기로 직접 파일을 준비합니다. 운영 로그에는 토큰·개인정보가 섞일 수 있으므로 처음에는 샘플 파일을 사용합니다.

실습용 폴더에 build.log 파일을 하나 만들어 줘.
내용은 아래 세 줄만 넣고, 다른 파일은 수정하지 마.

2026-10-07T07:28:00Z INFO build started
2026-10-07T07:28:01Z WARN optional preview skipped
2026-10-07T07:28:02Z ERROR demo build check failed: missing demo artifact

Claude Code는 이 파일이 있는 폴더에서 실행합니다. 읽기 전용 반복 요청이라도 자연어 금지 조건이 권한 통제를 대신하지는 않습니다. 실제 프로젝트에서는 /permissions로 허용 범위도 확인합니다.

Claude Code /loop 예약 방법

Claude Code 입력창에서 다음 명령을 실행합니다. 아래 영문은 실습에서 사용한 요청 그대로이며, 한글로 같은 범위를 지정해도 됩니다.

/loop 1m Read build.log. Report only ERROR count and last ERROR line. Read-only: no edits, shell, network, push or deploy.

뜻은 “1분마다 build.log를 읽고 ERROR 수와 마지막 오류만 알려 달라. 수정·셸·네트워크·푸시·배포는 하지 말라”입니다.

실습에서는 다음 예약 결과가 나왔습니다. 긴 도구 출력은 일부가 생략될 수 있습니다.

CronCreate(*/1 * * * *: Read build.log. Report only ERROR count and last ERROR line…)
Scheduled a3f83ef0 (Every minute)

확인할 것은 작업 ID, 실제 간격, 점검 대상입니다. 이 예제의 a3f83ef0는 실습에서 생성된 ID이며, 독자의 세션에서는 다른 값이 나옵니다. */1 * * * *는 매분 예약을 뜻합니다.

실제 대화형 실행의 터미널 셀 기록을 브라우저에 표시해 캡처한 이미지입니다. OS 터미널 창의 원본 스크린샷은 아닙니다. Scheduled 옆 작업 ID와 Every minute를 확인하세요. 작은 화면에서는 이미지를 눌러 원본을 볼 수 있습니다.

등록 직후의 “First run”에는 ERROR 1건과 샘플 오류 줄이 나왔습니다. 이것은 첫 점검 결과이며, 주기 실행은 아래에서 따로 확인합니다.

예약 목록 확인

같은 입력창에서 요청합니다.

CronList로 현재 예약 목록을 보여 줘. ID와 간격, 점검 내용을 확인하고 새 작업은 만들지 마.

실제 도구 결과에는 다음 값이 포함됐습니다.

a3f83ef0 Every minute (recurring) [session-only]: Read build.log. Report only ERROR count and last ERROR line…

session-only는 세션에 붙는 작업이라는 표기입니다. 일반 세션 재개에서도 절대 복원되지 않는다는 뜻으로 해석하면 안 됩니다. 복원은 아래에서 별도로 확인합니다.

첫 예약 실행 확인

등록 직후 응답이 끝나면 세션을 열어 둔 채 다음 실행을 기다립니다. 화면에 Running scheduled task와 새 로그 점검 결과가 나타나는지 확인합니다. 응답 중에는 예약이 대기할 수 있고 jitter도 있으므로, 정확히 60초 만에 표시되어야 한다고 판단하지 않습니다.

세션 재개까지 확인하려면 아직 CronDelete를 실행하지 않습니다. 예약과 ID를 그대로 둔 채 다음 절의 종료·재개를 진행하고, 마지막에 취소합니다.

세션 종료와 재개

여기서 가장 헷갈리는 것은 “예약이 남는다”와 “그동안 계속 실행된다”의 차이입니다.

• 세션 종료: 프로세스가 끝나면 예약 프롬프트도 실행되지 않음

• 세션 재개: 저장된 대화를 열면서 복원 가능한 예약을 다시 가져옴

• 백그라운드 유지: 세션을 종료하지 않고 터미널 밖에서 계속 실행

이번 실습에서는 고정 간격 작업을 만든 상태에서 /exit를 입력하자 다음 종료 선택지가 나타났습니다.

Background work is running
The following will stop when you exit:
scheduled task · Every minute · Read build.log. Report only ERROR count and last …

1. Exit and stop tasks
2. Move to background and exit
3. Stay

이 화면에서 1번으로 세션을 종료한 뒤, 종료 안내에 나온 세션 ID로 다시 열었습니다. 백그라운드 전환을 선택한 실습은 아닙니다.

claude --resume <종료 안내에 나온 세션 ID>

버전을 고정해 실행했다면 재개 명령에도 같은 버전을 씁니다.

npx -y @anthropic-ai/claude-code@2.1.292 --resume <세션 ID>

같은 폴더의 가장 최근 대화를 이어 갈 때는 claude --continue도 사용할 수 있습니다.[1] 대화가 여러 개 있거나 최근 대화를 찾지 못하면 임의의 새 세션을 만들기보다 종료 안내의 정확한 ID를 지정합니다. 이번 환경에서도 자동으로 최근 대화를 찾는 경로 대신 명시적 --resume으로 확인했습니다.

재개 후 확인 순서

예약 복원은 대화에 “예약했다”는 옛 문장이 보이는 것으로 판단하지 않습니다. 재개한 입력창에서 다음처럼 요청합니다.

CronList로 현재 예약을 조회해 줘. 기존 작업 ID가 남아 있는지 확인하고 새 예약은 만들지 마.

1. 재개한 세션에서 CronList 실행

2. 기존 작업 ID와 간격이 목록에 있는지 확인

3. 새 예약 실행 표시와 로그 점검 결과 확인

4. 마지막에 CronDelete 후 CronList로 정리

이번 재개 후 목록에는 새 작업을 만들지 않았는데도 기존 ID a3f83ef0가 그대로 나타났습니다. 이어서 07:34·07:35·07:36에 새로운 예약 실행 표시가 나왔고, 매번 샘플 로그의 ERROR 1건과 마지막 오류 줄을 읽었습니다. 이 버전·환경에서는 목록 복원뿐 아니라 재개 후 주기 실행도 확인한 것입니다. 표시 시각은 실습 환경의 UTC 기준이며 초 단위 정밀도까지 측정한 결과는 아닙니다.

터미널 셀 기록 캡처입니다. 두 개의 Running scheduled task 시각과 그 아래 ERROR count를 비교하세요. 등록 당시의 옛 답변이 아니라 재개 뒤 새로 실행된 결과입니다. 이미지를 누르면 원본을 볼 수 있습니다.

복원 예외

공식 문서의 재개 조건은 다음과 같습니다.[1]

/loop 중지와 취소 확인

재개 후 새 실행까지 확인했다면 이제 실습 예약을 정리합니다. 고정 간격 작업은 자연어로 취소를 요청할 수 있지만, 비슷한 작업이 여러 개라면 ID를 지정하는 편이 분명합니다.[1]

CronDelete로 작업 a3f83ef0을 취소하고, CronList로 남은 예약을 확인해 줘.

실행할 때는 a3f83ef0를 자신의 목록에 나온 ID로 바꿉니다. “중지했습니다”라는 답변보다 도구 결과를 확인합니다.

CronDelete(a3f83ef0)
Cancelled a3f83ef0

CronList
No scheduled jobs

취소 결과와 빈 목록을 함께 확인해야 같은 예약이 남지 않았는지 알 수 있습니다. 다른 예약을 유지하고 있다면 빈 목록이 아니라 해당 ID의 부재를 확인합니다.

터미널 셀 기록 캡처입니다. Cancelled와 No scheduled jobs 두 줄을 함께 확인하세요. 이 실습에서는 1분 이상 기다린 뒤 다시 조회해도 빈 목록이었고, 그 사이 새 예약 실행 표시도 나타나지 않았습니다. 이미지를 누르면 원본을 볼 수 있습니다.

자동 간격 /loop는 다음 실행을 기다리는 동안 Esc로 대기를 취소할 수 있습니다. 하지만 고정 간격 예약이나 자연어로 별도 생성한 예약까지 Esc가 모두 지워 주는 것은 아닙니다. 이번 실습처럼 고정 간격으로 만든 작업은 CronDelete와 CronList로 확인합니다.

실행 한계와 버전 주의점

7일 만료와 누락 실행

반복 작업은 생성 후 7일이 지나면 마지막으로 한 번 실행하고 삭제됩니다. 방치된 작업을 무한히 돌리지 않기 위한 장치이지 비용 상한은 아닙니다.[1]

Claude가 바쁜 동안 여러 예약 시각이 지나도 놓친 횟수만큼 실행하지 않습니다. 대기 상태가 되면 한 번 실행하므로, 매 회 빠짐없이 기록해야 하는 수집기나 정밀 배치에는 적합하지 않습니다.

7일 만료, 자동 간격 복원 예외, 누락 실행 처리는 공식 문서 기준입니다. 이번 짧은 실습에서 직접 확인한 범위는 고정 간격 예약·재개 후 실행·취소입니다.

2.1.292의 예약 관련 수정

공식 변경 기록에는 /resume·/branch·/clear 이후 만든 저장 예약의 미실행, 작업 파일을 짧은 간격으로 두 번 쓸 때 생성·삭제가 누락되는 문제, 백그라운드 세션의 프로세스 재시작 후 /loop 대기가 사라지는 문제의 수정이 포함됩니다.[2]

백그라운드 프로세스 복구와 일반 대화의 --resume은 다른 경로입니다. 이 수정만으로 자동 간격 루프도 모든 재개에서 복원된다고 해석하면 안 됩니다. 이번 실습 역시 수정된 버그의 모든 경로를 재현한 것은 아닙니다.

다른 폴더로 예약을 옮길 때

기능 플래그 조회가 꺼진 환경에서 세션 간 유지를 요청한 예약은 .claude/scheduled_tasks.json에 저장될 수 있습니다. 이 파일을 다른 폴더나 worktree에 복사하면 목록에 보여도 실행되지 않으므로 새 폴더에서 다시 예약합니다. .claude나 작업 파일이 심볼릭 링크인 경우에도 이 저장 경로는 오류를 반환합니다.[1]

이 제한은 특정 저장 경로의 설명입니다. 모든 /loop가 해당 파일 하나로 관리된다고 가정하지 않습니다.

반복 점검이 실행되지 않을 때

먼저 다음 순서로 확인합니다.

1. Claude Code 세션과 프로세스가 아직 실행 중인가

2. CronList에 대상 ID가 남아 있는가

3. 현재 응답·권한 확인 때문에 예약이 대기 중인가

4. 조정된 간격과 jitter를 감안할 만큼 기다렸는가

5. 다른 폴더나 worktree에서 이전 예약 파일을 가져온 것은 아닌가

6. CLAUDE_CODE_DISABLE_CRON=1로 예약 기능을 끈 것은 아닌가

오류가 발생하면 “다시 예약해 줘”부터 입력하지 않습니다. 기존 작업이 남아 있으면 같은 점검이 중복될 수 있습니다. 먼저 ID와 목록을 읽고, 필요하면 기존 작업을 취소한 뒤 다시 만듭니다. 경로·권한·로그를 나누어 보는 순서는 CLI 자동화 실패 점검에도 정리했습니다.

/loop와 상시 자동화의 선택

지금 열어 둔 작업의 빌드·로그를 잠시 점검하려면 /loop가 간단합니다. 다만 종료·재개·백그라운드 여부를 사람이 관리해야 합니다.

컴퓨터가 꺼져도 돌아가야 한다면 공식 Routines 같은 클라우드 예약을, 로컬 파일을 다루면서 대화창을 계속 열어 두고 싶지 않다면 Desktop scheduled tasks를 검토합니다. 로컬 Desktop 작업도 컴퓨터는 켜져 있어야 합니다. CI에서 반복 실행해야 한다면 GitHub Actions의 schedule 트리거처럼 세션과 독립된 실행 경로가 맞습니다.[1]

이 글의 실습 순서는 예약 → ID·실행 확인 → 세션 종료·재개 → 새 실행 확인 → 최종 취소입니다. 평소 잠깐 점검할 때는 재개 실습을 건너뛰고, 확인이 끝나면 바로 취소해도 됩니다. “밤새 일하는 AI”보다 어떤 세션에서 무엇을 읽고, 언제 멈추며, 재개 뒤 무엇이 다시 실행되는지를 확인하는 편이 안전합니다.

참고 자료

[1] Claude Code 공식 문서: Run prompts on a schedule — 고정·자동 간격, 중지, 재개, jitter, 만료와 제한. 확인일 2026-10-07.
[2] Claude Code v2.1.292 릴리스 및 공식 변경 기록 — 저장 예약과 백그라운드 루프 관련 수정.