AI 코딩 도구

Claude Code Routines 완전 가이드 — 스케줄·API·GitHub 트리거로 워크플로우를 자동화하는 법

2026년 4월 Anthropic이 연구 프리뷰로 공개한 Claude Code Routines를 실전 분석한다. 루틴의 구성 요소(프롬프트·저장소·커넥터), 3가지 트리거(Scheduled·API·GitHub) 설정법, 플랜별 일일 실행 한도, 막히는 케이스 해결까지 개발팀 자동화에 바로 적용할 수 있는 가이드.

2026-04-16

한 줄 요약: Anthropic이 2026년 4월 14일 연구 프리뷰로 공개한 Claude Code Routines는 프롬프트·저장소·커넥터를 한 번 설정하면 스케줄·API·GitHub 이벤트를 트리거로 삼아 Anthropic 관리형 클라우드 인프라에서 자율적으로 실행되는 자동화 기능이다.

이 글이 필요한 사람

밤새 CI/CD나 코드 리뷰 자동화를 크론탭으로 직접 관리하는 개발자
PR 머지 시점에 자동으로 특정 작업을 Claude에게 맡기고 싶은 팀
모니터링 알람이 오면 Claude가 먼저 트리아지하게 하고 싶은 인프라 담당자
Claude Code 4월 업데이트의 Routines 기능을 실전에 적용하려는 엔지니어

Claude Code Routines란 무엇인가

Routines는 Claude Code의 자동화 실행 단위다. 기존에는 Claude Code를 쓰려면 터미널을 열고 직접 명령을 입력해야 했다. 노트북이 닫히면 작업도 멈췄다.

Routines는 이 제약을 제거한다. 한 번 설정하면 내 컴퓨터가 꺼져 있어도 Anthropic 서버에서 Claude가 계속 돌아간다.

루틴의 구성 요소는 세 가지다:

프롬프트 — Claude에게 줄 지시문 (무엇을 할지)
저장소(Repositories) — 작업 대상이 되는 GitHub 저장소 하나 이상
커넥터(Connectors) — GitHub, Slack, Linear 등 Claude가 접근할 외부 서비스

이 세 가지를 묶어 하나의 루틴으로 저장하고, 실행 트리거를 지정하면 된다. 이후 Claude가 지정된 조건에서 자율적으로 코드 리뷰, 이슈 분류, 문서 업데이트 등 작업을 수행한다.

연구 프리뷰(Research Preview) 상태: Routines는 2026년 4월 14일 기준 연구 프리뷰다. API 엔드포인트, 베타 헤더, 트리거 동작이 정식 출시 전 변경될 수 있다. 프로덕션 크리티컬 워크플로우보다는 자동화 실험·내부 효율화 용도로 먼저 적용하길 권장한다.

Claude Code Routines cloud automation dashboard — claude.ai/code/routines에서 루틴을 생성·관리할 수 있다. 트리거 유형과 실행 이력을 한눈에 볼 수 있다

3가지 트리거 유형 완전 정리

루틴의 핵심은 트리거다. 같은 루틴 설정에 여러 트리거를 동시에 붙일 수 있다.

트리거 유형	실행 조건	대표 사용 예
Scheduled	cron식 주기 (매시간·매일·매주)	야간 이슈 라벨링, 주간 문서 동기화
API	HTTP POST 요청 수신 시	모니터링 알람 → Claude 트리아지
GitHub	PR 생성·머지, 릴리즈 등 저장소 이벤트	PR 자동 코드 리뷰, 릴리즈 노트 생성

각 트리거 설정 시 주의 사항은 아래에서 상세히 다룬다.

루틴 만들기 — 생성부터 트리거 연결까지

루틴 생성 방법은 두 가지다. 브라우저에서 claude.ai/code/routines에 접속하거나, Claude Code CLI 안에서 /schedule 명령어를 실행한다.

기본 생성 흐름 (CLI):

Claude Code CLI — 루틴 생성
# Claude Code 세션 안에서 실행
/schedule

# 프롬프트 입력: Claude에게 줄 지시문 작성
# 예시:
# "이 저장소의 새로운 이슈에 라벨을 붙이고, 담당자를 할당하라.
# bug 키워드 → bug 라벨, feat 키워드 → enhancement 라벨,
# 담당자 없는 이슈 → @lee-seunghwan 할당"

# 저장소 연결: GitHub App 설치 필요
# 트리거 선택: Scheduled / API / GitHub 중 하나 이상

API 트리거 엔드포인트 구조:

API 트리거 — HTTP POST 호출 예시
# API 트리거 생성 시 엔드포인트와 Bearer 토큰이 발급된다
# 토큰은 생성 시 1회만 표시 — 즉시 시크릿 스토어에 저장할 것

curl -X POST https://api.anthropic.com/v1/routines/{routine-id}/fire \
  -H "Authorization: Bearer {YOUR_ROUTINE_TOKEN}" \
  -H "anthropic-beta: experimental-cc-routine-2026-04-01" \
  -H "Content-Type: application/json" \
  -d '{"context": "PagerDuty alert: DB CPU 92%, instance prod-db-01"}'

# context 필드로 실행 시점의 동적 정보를 루틴에 전달할 수 있다

GitHub 트리거 설정 시 주의: GitHub 이벤트를 받으려면 Claude GitHub App을 대상 저장소에 별도로 설치해야 한다. /web-setup 명령으로 클론 권한만 부여한 상태에서는 웹훅이 동작하지 않는다. 루틴 생성 UI가 설치 링크를 안내하지만 빠뜨리기 쉬운 단계다.

Claude Code Routines triggers setup schedule API GitHub — 루틴 하나에 스케줄·API·GitHub 트리거를 동시에 붙일 수 있다. 각 트리거는 독립적으로 동작한다

실전 활용 케이스 6가지

Anthropic이 공식 문서에서 제시한 6가지 케이스와 각각의 트리거 전략을 정리했다.

케이스	트리거	작동 방식
백로그 관리	Scheduled (야간)	새 이슈 라벨링, 중복 감지, 담당자 할당
알람 트리아지	API (모니터링 시스템 호출)	Datadog·PagerDuty 알람 → Claude가 원인 분석 후 Slack 리포트
코드 리뷰	GitHub (PR 생성 시)	PR 열릴 때마다 Claude가 코드 리뷰 코멘트 자동 작성
배포 검증	API (CD 파이프라인 호출)	배포 완료 후 스모크 테스트 실행, 이상 시 롤백 PR 생성
문서 동기화	Scheduled (주간)	코드 변경 감지 후 README·API 문서 자동 업데이트 PR 생성
라이브러리 포팅	GitHub (PR 머지 시)	내부 라이브러리 PR 머지 → 의존 저장소에 포팅 PR 자동 생성

요금 제한과 현재 제약 — 프로덕션 적용 전 확인 사항

Routines 실행 횟수는 플랜별로 제한된다. 한 번의 루틴 실행이 무거운 에이전틱 작업을 포함할 수 있기 때문에 일 단위로 제한을 둔다.

플랜	일일 실행 한도
Pro	5회/일
Max	15회/일
Team / Enterprise	25회/일

연구 프리뷰 기간의 추가 제약:

베타 헤더 필수: API 트리거는 anthropic-beta: experimental-cc-routine-2026-04-01 헤더 없이는 동작하지 않는다. 정식 출시 전 변경 가능성이 있다
GitHub App 별도 설치: GitHub 이벤트 트리거에는 Claude GitHub App 수동 설치 필요
API 토큰 1회 표시: 루틴 생성 직후 토큰이 단 한 번만 표시된다. 생성 즉시 AWS Secrets Manager, GitHub Secrets 등에 저장해야 한다
컨텍스트 유지 없음: 각 루틴 실행은 독립 세션이다. 이전 실행 내용을 기억하지 않는다

막히는 케이스와 대응 방법

연구 프리뷰에서 자주 겪는 문제 3가지와 해결 방법이다.

케이스 1 — GitHub 웹훅이 오지 않는다
원인: Claude GitHub App이 저장소에 설치되지 않은 상태. /web-setup은 클론 권한만 부여하고 웹훅 수신 권한은 별개다.
해결: github.com/apps/claude-code에서 앱을 대상 저장소에 설치한 뒤 루틴의 GitHub 트리거를 재활성화한다.

케이스 2 — API 트리거 호출 시 401 Unauthorized
원인: 베타 헤더 누락 또는 토큰 만료.
해결: 요청 헤더에 anthropic-beta: experimental-cc-routine-2026-04-01이 포함됐는지 확인한다. 토큰을 분실했다면 루틴을 삭제하고 재생성해야 한다 — 토큰 재발급 기능은 현재 없다.

케이스 3 — 스케줄 루틴이 예상 시각에 실행되지 않는다
원인: cron 표현식이 UTC 기준으로 해석된다. KST(UTC+9) 기준 오전 9시를 원한다면 0 0 * * *으로 설정해야 한다.
해결: 루틴 설정 시 타임존을 명시하거나 UTC 기준으로 역산해 입력한다.

Claude Code automation workflow diagram schedule API GitHub triggers — Routines의 세 트리거가 실제 개발 워크플로우에 통합되는 흐름. 노트북 없이 Claude가 자율 실행된다

Routines 도입 전 실무 체크리스트

Routines를 팀 워크플로우에 도입하기 전 확인해야 할 사항들이다.

플랜 일일 한도 확인: Pro 5회는 하루 5개 이벤트가 상한이다. 팀 협업이라면 Team 플랜(25회) 이상이 실용적이다
프롬프트 명확성: 루틴 프롬프트는 모호하면 Claude가 잘못된 방향으로 오래 작업한다. "이슈를 분류하라"보다 "이슈 제목에 버그 키워드가 있으면 bug 라벨을 붙이고 severity: high 태그를 추가하라"처럼 조건과 행동을 명확히 서술한다
저장소 커넥터 최소화: 루틴에 연결된 저장소가 많을수록 실행 시간과 토큰 사용량이 늘어난다. 실제 작업에 필요한 저장소만 연결한다
API 토큰 보안: 루틴 API 토큰은 Claude Code를 대신해 실행 권한이 있다. GitHub Secrets나 AWS Secrets Manager에 반드시 저장하고, 환경 변수로 직접 코드에 하드코딩하지 않는다
연구 프리뷰 변경 추적: 베타 헤더와 API 구조가 정식 출시 전 변경될 수 있다. 공식 Routines 문서를 북마크해 두고 주기적으로 확인한다

Claude CodeRoutines자동화에이전트스케줄GitHubAPI 트리거AnthropicAI 코딩 도구워크플로우