Claude Code 루틴: 클라우드에서 일정에 맞춰 코딩 에이전트를 실행하세요

세 부분은 각각 역할이 있습니다:

• 프롬프트. 가장 중요한 요소입니다. 루틴은 매 단계마다 승인 없이 실행되므로, 프롬프트에 작업 전체와 완료 기준이 담겨야 합니다.
• 저장소. Claude는 매 실행 시작 시 이를 클론하고 그 안에서 작업을 수행합니다.
• 커넥터. 계정에 연결된 claude.ai 통합 도구들(예: Slack, Linear)로, 루틴은 실행 중 이들로부터 읽고 이들에게 쓸 수 있습니다. 예를 들어, 지원 티어링 루틴은 Slack 채널을 읽고 Linear에 이슈를 생성할 수 있습니다.

루틴용 커넥터는 claude.ai 플랫폼에서 추가합니다. MCP 서버도 마찬가지입니다. 로컬 설정은 그대로 이전되지 않습니다.

루틴은 세 가지 방식으로 트리거됩니다. 일정, API 호출, GitHub 이벤트입니다. 하나의 루틴에 세 가지를 모두 결합할 수 있습니다.

루틴과 /loop 비교

두 명령은 해결하는 문제가 달라서 /loop와 /schedule는 차이가 있습니다.

/loop 작업은 현재 세션에 상주합니다. 로컬에서 Claude Code가 실행 중이고 유휴일 때만 트리거되며, 터미널을 닫으면 중지됩니다. 지금 지켜보는 빌드를 폴링하는 데 적합합니다.

/loop 및 기타 중요한 명령에 대한 자세한 내용은 Claude Code 터미널 튜토리얼을 참고하세요.

루틴은 클라우드에서 실행되며 어떤 세션과도 독립적으로 지속됩니다:

또 다른 세 번째 로컬 옵션도 있습니다. 데스크톱 예약 작업은 로컬 파일과 도구가 필요한 작업을 위해 사용자의 컴퓨터에서 실행됩니다. 머신이 깨어 있을 때만 실행되지만, Claude 앱을 열어둘 필요는 없습니다.

이번에 만들 루틴

개념은 잡았습니다. 이제 루틴이 작업할 대상을 준비해야 합니다. 이 튜토리얼을 위해 우리는 pr-review-demo를 만들었습니다. 오픈된 풀 리퀘스트 하나가 있는 작은 Python 프로젝트입니다.

여기에는 쇼핑 카트를 처리하는 cartlib 패키지가 있으며, 가격을 정수 센트로 저장하고, 멤버·대량 할인 적용, 주별 판매세를 더해 최종 청구액을 계산합니다. 메인 브랜치의 패키지는 올바르게 동작합니다.

열려 있는 풀 리퀘스트는 무료 배송 쿠폰을 추가하지만, 의도적으로 심어둔 실제 버그가 포함되어 있습니다. 파일 간 단위 불일치로, 단일 파일만 보면 보이지 않고 두 파일을 가로질러 값을 추적해야 드러납니다. 튜토리얼 전반에 걸쳐 루틴이 처리할 실제 과제가 됩니다.

따라 하시려면 저장소를 포크하세요. 일회성 예제이며, 여기서 배운 패턴은 루틴을 지정하는 어떤 저장소에도 그대로 적용됩니다.

진행 전 필요 사항

웹에서 Claude Code가 활성화된 Pro, Max, Team, Enterprise 요금제의 claude.ai 계정이 필요합니다. 루틴은 claude.ai/code/routines에 있습니다.

/schedule 명령은 Anthropic API 키나 Bedrock, Vertex, Foundry 인증이 아닌, claude.ai 구독 로그인으로 인증합니다. 최신 CLI도 필요하므로, 오래됐다면 claude update를 실행하세요.

GitHub 관련 사전 준비도 두 가지가 있습니다. 먼저, /web-setup은 예약 루틴에 필요한 클론 권한을 부여합니다. 다음으로, 별도 설치하는 Claude GitHub 앱은 이후에 다룰 GitHub 트리거를 활성화합니다.

/schedule로 Claude Code 루틴 만들기

대상 저장소를 정했으면 CLI에서 루틴을 만듭니다. 어떤 세션에서든 /schedule을 실행하세요. 설명을 바로 전달할 수 있습니다:

/schedule daily PR review at 9 am

그러면 Claude가 웹 양식과 동일한 항목들—이름, 프롬프트, 저장소, 환경, 커넥터, 일정—을 순서대로 물어봅니다. 로컬 시간대에서 일정을 확인하고 자동으로 변환하므로, 9am을 직접 크론 표현식으로 쓰지 않아도 됩니다.

계정에 아직 GitHub 연결이 없다면, Claude가 /web-setup 실행을 안내합니다. 이를 실행한 뒤, /schedule을 다시 실행해 이어서 진행하세요.

사람 없이도 동작하는 프롬프트 작성하기

루틴의 성공 여부는 프롬프트에 달려 있습니다.

일반 세션은 대화이므로 진행 중에 Claude를 교정할 수 있습니다. 루틴에는 교정해 줄 사람이 없습니다. 차갑게 시작해 끝까지 달리고, 확인 질문을 할 수 없습니다. 프롬프트에 작업, 저장소, 그리고 완료가 어떤 모습인지까지 명시해야 합니다.

다음 두 가지를 비교해 보세요. 첫 번째는 빠진 내용이 너무 많습니다:

Review the open PR.

저장소나 리뷰 기준을 명시하지 않았고, 코멘트를 남길 위치도 없으며, 완료 정의도 없습니다. 콜드 런은 그 빈틈을 채울 수 없습니다. 두 번째 프롬프트는 모든 점을 충족합니다:

Review the open pull request in pr-review-demo. The cartlib package works entirely in integer cents. Read the checkout flow and the values it pulls from config.py, and check that every amount stays in cents end to end. If any value is mixed in using the wrong unit, leave an inline comment on that line explaining the error and its effect on the customer's total. Then, post a summary comment stating whether the PR is safe to merge.

이 프롬프트는 저장소를 지목하고, 코드가 반드시 지켜야 할 불변 조건(모든 금액은 센트)을 명시합니다. 중요한 두 파일을 짚고, 완료를 인라인 코멘트와 머지 판정으로 정의합니다. 이렇게 하면 루틴이 스스로 달성할 수 있는 목표가 생깁니다. /schedule가 에이전트의 작업을 묻는 단계에서 붙여넣으세요.

모든 커넥터는 기본으로 포함되므로, 새 루틴은 계정에 연결된 모든 리소스에 접근할 수 있습니다. 지금은 괜찮지만, 이후 섹션에서 범위를 좁힙니다.

흐름을 마치면, Claude가 루틴을 저장하고 저장소, 일정, 모델, 다음 실행 시간을 포함해 활성화되었음을 확인해 줍니다.

루틴은 목록에도 표시됩니다 claude.ai/code/routines. 상세 페이지를 열어 모든 정보를 한눈에 확인하세요. 상태, 저장소, 일정, 커넥터, 전체 프롬프트, 그리고 지금 실행 버튼이 포함됩니다.

기다리지 않고 바로 실행하려면 지금 실행을 클릭하세요.

실행 기록 읽기

실행은 기본 브랜치에서 새로 클론한 저장소로부터 시작합니다. 커밋한 내용은 모두 포함되며, 로컬 머신에서만 설정한 항목은 포함되지 않습니다. 즉, 루틴은 동료가 보는 것과 같은 상태의 저장소를 보게 됩니다.

완료되면 실행 목록에 녹색 상태가 표시됩니다. 녹색은 세션이 인프라 오류 없이 실행되고 종료되었음을 의미합니다. 그러나 프롬프트의 작업이 성공했음을 뜻하지는 않습니다. 녹색 체크 뒤에 숨은 세 가지 실패 유형은 전사에서만 드러납니다:

• 환경에서 차단된 네트워크 요청.
• 루틴이 기대했지만 도달하지 못한 커넥터 도구.
• 작업 수준 실패. 실행은 정상 종료됐지만 잘못된 동작을 한 경우.

따라서 실행을 열어 확인하세요. 아무 실행이나 클릭하면 전체 세션 형태로 열리며, Claude가 한 작업을 살펴보고, 변경 사항을 검토하고, 풀 리퀘스트를 열거나 대화를 이어갈 수 있습니다.

데모 저장소에서는 전사에 버그 포착 내용이 보입니다. Claude는 checkout.py를 읽고 쿠폰이 500이 아니라 5로 설정된 것을 찾습니다. 이는 5달러를 5센트로 적용해 주문당 4.95달러를 과금한다고 설명하고, 한 줄 수정안을 제시합니다. 그런 다음 GitHub 커넥터를 통해 PR에 리뷰를 게시합니다.

CLI에서 Claude Code 루틴 관리하기

루틴을 만든 뒤에는 같은 명령으로 관리합니다. /schedule list로 전체 목록을 보고, /schedule update로 변경하고, /schedule run으로 즉시 실행합니다.

일정 프리셋은 시간별, 매일, 평일, 주간입니다. 2시간마다나 매월 1일처럼 사용자 정의 간격이 필요하면, 먼저 가장 가까운 프리셋을 고른 뒤 /schedule update를 실행해 크론 표현식을 직접 설정하세요. 최소 간격은 1시간이며, 더 빠른 주기는 거부됩니다.

루틴은 계정의 일일 실행 한도에도 포함되며, 리서치 프리뷰 동안은 GitHub 이벤트에 시간당 제한이 있습니다. 한도를 초과한 이벤트는 대기열에 쌓이지 않고 폐기됩니다. 현재 수치는 요금제별로 다르며 에서 확인할 수 있습니다 claude.ai/code/routines.

CLI는 예약 루틴만 생성합니다. GitHub 또는 API 트리거를 추가하려면 웹 앱에서 루틴을 편집하세요.

GitHub와 HTTP로 Claude Code 루틴 트리거하기

일정은 시계에 따라 루틴을 트리거합니다. 두 가지 다른 트리거는 GitHub 또는 자체 시스템이 같은 루틴을 실행하게 해줍니다. PR 리뷰 루틴을 야간에 실행하고, 새 PR마다 반응하며, 배포 스크립트에서 동시에 시작할 수 있습니다.

두 트리거 모두 에서 루틴을 편집해 추가합니다 claude.ai/code/routines.

GitHub 트리거로 PR에 반응하기

GitHub 트리거는 구독하려는 저장소에 Claude GitHub 앱이 설치되어 있어야 합니다. 앱이 없으면 트리거 설정 중 설치 안내가 나타납니다. 앞서 언급한 /web-setup은 클론 권한만 부여합니다. 앱 설치나 웹훅 전달은 하지 않으므로, 이 단계까지 커버하지 않습니다.

앱을 설치한 뒤 트리거를 추가하고 이벤트를 선택하세요. 이벤트는 풀 리퀘스트와 릴리스 두 범주로 나뉘며, 그 안에서 특정 액션을 고릅니다. PR opened, PR merged, Release published 같은 일반 옵션은 프리셋으로 제공되며, 나머지는 사용자 지정으로 선택 가능합니다.

그리고 필터로 범위를 좁히세요. 풀 리퀘스트의 경우 작성자, 제목, 본문, 베이스 브랜치, 헤드 브랜치, 라벨, 초안 여부, 머지 여부로 필터링할 수 있습니다. 모든 조건이 일치해야 루틴이 트리거됩니다.

matches regex 연산자는 부분 문자열이 아니라 필드 전체를 검사합니다. hotfix가 포함된 어떤 제목이든 매칭하려면 .*hotfix.*로 작성하세요. 단순히 hotfix라고만 쓰면 제목이 정확히 그 문자열일 때만 매칭됩니다.

GitHub 트리거가 새 풀 리퀘스트에 반응하도록 설정되어 있으며, 메인 브랜치와 특정 작성자로 필터링됨.

데모 저장소에서는 이벤트를 PR 오픈으로 설정하고 필터는 비워 두세요. 그러면 터미널 앞에 아무도 없어도 새 PR마다 앞서 작성한 리뷰가 실행됩니다. 쿠폰의 단위를 파일 전반에서 추적하고, 버그 라인에 인라인 코멘트를 남기며, 머지 판정을 게시합니다. 

일치하는 각 이벤트는 독립적인 세션을 시작하므로, 연달아 두 개의 PR이 열리면 두 건의 독립 실행이 생성됩니다.

HTTP로 루틴 트리거하기

API 트리거를 사용하면 자체 도구에서 루틴을 실행할 수 있습니다. 트리거 선택기에서 API를 선택하고 토큰 생성을 클릭하세요. 토큰은 한 번만 표시되며 이후에는 확인할 수 없으므로, 즉시 알림 도구의 비밀 저장소에 보관하세요.

그다음 토큰과 text 본문을 포함해 루틴의 fire 엔드포인트에 POST하세요:

curl -X POST https://api.anthropic.com/v1/claude_code/routines/$ROUTINE_ID/fire \
  -H "Authorization: Bearer $ROUTINE_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: experimental-cc-routine-2026-04-01" \
  -H "Content-Type: application/json" \
  -d '{"text": "Sentry alert SEN-4521 fired in prod. Stack trace attached."}'

text 값은 리터럴 문자열로 전달되며 파싱되지 않으므로, JSON이 아닌 평문으로 작성하세요. 구조화된 입력도 원문 텍스트로 전달되며, 루틴은 이를 그대로 읽습니다. 

anthropic-beta 헤더는 필수이며, API는 실험적입니다. CI에 연결하기 전에 API 레퍼런스를 확인하세요. 이후에는 모니터링 도구가 경보 시 이 엔드포인트를 호출해 루틴이 자체적으로 드래프트 수정 PR을 열게 할 수 있습니다.

Claude Code 루틴의 접근 범위 지정

루틴은 독립적으로 실행되므로, 실제 저장소에 적용하기 전에는 접근 범위를 제한하세요. 문서는 이를 네 가지 제어 장치로 설명합니다:

• GitHub 신원과 커넥터를 통해 루틴이 어떤 신원으로 동작하는지.
• 푸시할 수 있는 브랜치는 어디까지인지.
• 사용 가능한 커넥터는 무엇인지.
• 환경에서 네트워크로 접근 가능한 호스트는 어디인지.

루틴이 실제로 필요한 만큼만 범위를 지정하세요.

루틴 신원

신원이 먼저입니다. 이는 공유 저장소에서 동료가 가장 먼저 알아차리는 부분이기 때문입니다. 루틴이 GitHub 신원이나 커넥터를 통해 수행한 모든 작업은 당신의 이름으로 표시됩니다. 

커밋과 PR에는 당신의 GitHub 유저가 표시되고, Slack 메시지와 Linear 티켓에는 연결된 계정이 사용됩니다.  동료는 커밋과 PR에서 당신의 이름을 보게 되므로, 루틴이 만들었음을 알 수 있도록 브랜치와 제목에 신호를 담아주세요.

루틴이 푸시할 수 있는 브랜치

브랜치가 다음입니다. 실행은 권한 프롬프트 없이 진행되는 완전한 클라우드 세션이므로, 파일 편집이나 PR 생성을 앞두고 멈춰 묻지 않습니다. 

가드레일은 푸시 가능한 브랜치입니다. 기본적으로 Claude는 claude/ 접두사가 붙은 브랜치에만 푸시하여, main 같은 보호되었거나 장기 유지되는 브랜치를 피합니다. 

저장소별 설정인 무제한 브랜치 푸시 허용을 켜면 이 제한이 해제됩니다. 필요한 저장소에만 신중하게 활성화하세요.

루틴이 사용할 수 있는 커넥터

커넥터는 네 가지 중 가장 위험도가 높습니다. claude.ai의 모든 커넥터가 기본 포함되며, 포함된 커넥터의 모든 도구(쓰기 포함)를 실행 중에 추가 확인 없이 사용할 수 있습니다. 

따라서 루틴에 필요한 항목만 남기세요. PR 리뷰 루틴은 GitHub만 있으면 충분합니다. 이메일이나 캘린더 커넥터처럼 쓰임새가 없는 접근은 불필요하며, PR에 숨겨진 프롬프트 인젝션이 그 접근 권한을 악용할 수 있습니다.

네트워크 접근

네트워크 접근은 마지막 제어 장치입니다. 기본 환경(Default)은 신뢰된 네트워크 접근을 사용하며, 패키지 레지스트리, 클라우드 제공업체 API, 컨테이너 레지스트리, 일반 개발 도메인으로 구성된 기본 허용 목록에 접근하고 나머지는 차단합니다. 

차단된 요청은 403과 x-deny-reason: host_not_allowed로 실패합니다. 루틴이 사내 서비스를 반드시 호출해야 할 때만 범위를 넓히세요. 그렇지 않으면, 실패는 눈에 띄는 오류가 아니라 전사에만 조용히 남습니다.

다음에 만들어 볼 Claude Code 루틴 아이디어

이제 루틴을 만들고, 트리거하고, 범위를 지정할 수 있습니다. 공식 문서의 다음 예시는 작업과 이에 맞는 트리거를 짝지었습니다:

• 맞춤 코드 리뷰. PR 오픈에 대한 GitHub 트리거. 팀의 리뷰 체크리스트를 적용하고, 보안·성능·스타일에 대한 인라인 코멘트를 남기며 요약을 추가합니다. 데모를 실제 기준으로 일반화한 형태입니다.
• 백로그 정리. 평일 저녁마다 일정 트리거. 지난 실행 이후 열린 이슈를 읽고 라벨을 적용하며, 참조된 코드 영역에 따라 담당자를 지정하고, Slack에 요약을 게시합니다.
• 배포 검증. 프로덕션 배포 후 CD 파이프라인에서 API 트리거. 새 빌드에 대한 스모크 체크를 수행하고, 오류 로그를 스캔해 회귀를 탐지하며, 릴리스 채널에 진행/중단 결과를 게시합니다.
• 문서 드리프트. 주간 일정 트리거. 지난 실행 이후 머지된 PR을 스캔해 변경된 API를 참조하는 문서를 표시하고, 문서 저장소에 업데이트 PR을 엽니다.

루틴은 무인, 반복 가능, 명확한 결과에 연동된 작업에 적합합니다. PR 리뷰에서처럼 성공 기준을 프롬프트로 명시할 수 있다면, 그 작업은 후보입니다. 실시간 인간 판단이 필요한 작업은 적합하지 않습니다.

맺음말

루틴은 반복 업무에 쓰는 시간을 바꿉니다. 각 작업을 터미널에서 실행하는 대신, 한 번 작성해 두고 이미 실행된 결과를 검토합니다. 만든 PR 리뷰는 노트북을 닫아도 실행되며, 준비되었을 때 판정을 읽으면 됩니다.

Claude Code를 더 깊이 학습하려면 다음 튜토리얼이 함께 읽기 좋습니다:

• Claude Code 모범 사례: 세션당 더 많은 가치를 얻는 방법.
• CLAUDE.md 파일 작성: 루틴과 세션에 공통 컨텍스트 제공.
• 스펙 기반 개발: 자동화 전에 명세할 가치가 있는 작업을 위해.
• 오토 모드와 채널: 더 적은 감독으로 Claude Code 실행.