Claude Code Routines 실전 가이드 — 스케줄·웹훅·API 트리거로 반복 개발 작업 완전 자동화하기
PR 리뷰, 이슈 트리아지, 문서 업데이트. 코드 한 줄 안 짜면서도 하루가 통째로 날아가는 경험, 다들 한 번쯤 있으시죠? 저도 한동안은 "이게 개발자의 숙명인가" 싶었는데, 2026년 4월 Anthropic이 내놓은 Claude Code Routines를 접하고 나서 생각이 좀 바뀌었습니다. 단순히 AI가 코드를 짜주는 게 아니라, 내가 자리를 비운 사이에도 워크플로우가 돌아가는 구조를 만들 수 있거든요.
이 글에서는 Routines가 정확히 무엇인지, 기존 Claude Code 자동화 레이어와 어떻게 다른지, 그리고 실무에서 어떻게 쓸 수 있는지를 정리했습니다. 핵심은 한 번 설정해두면 로컬 머신이 꺼져 있어도 클라우드에서 세션이 알아서 돌아간다는 것입니다. 이 글을 읽고 나면 야간 이슈 트리아지 루틴을 30분 안에 설정하는 것이 충분히 가능하다는 걸 알 수 있을 겁니다.
다만 미리 말씀드리면, 현재 Routines는 리서치 프리뷰 단계라 API 스펙이나 동작 방식이 앞으로 바뀔 수 있습니다. 코드 예시 중 일부는 공식 스펙을 기반으로 하되, 의사(pseudo) 코드 수준으로 작성된 부분도 있으니 실제 적용 전에는 Anthropic 공식 문서에서 최신 스펙을 꼭 확인해보시는 걸 권장합니다.
핵심 개념
Claude Code 자동화의 4개 레이어
Claude Code에는 Routines 이전부터 자동화를 지원하는 레이어가 세 가지 있었습니다. Routines를 이해하려면 이 세 레이어를 먼저 짚어두는 게 좋습니다.
| 레이어 | 위치 | 한 줄 설명 |
|---|---|---|
| CLAUDE.md | 프로젝트 루트 | 세션마다 자동 로드되는 AI 지침 파일. "이 프로젝트는 TypeScript strict mode, 커밋은 한글 가능" 같은 규칙을 적어두는 곳 |
| 커스텀 슬래시 커맨드 | .claude/commands/*.md |
/project:fix-issue 1234처럼 호출할 수 있는 재사용 프롬프트 템플릿 |
| Hooks | 설정 파일 | 도구 실행 전후(PreToolUse, PostToolUse)에 셸 명령을 자동으로 돌리는 트리거 |
| Routines | 클라우드 | 스케줄·API·웹훅 조건에 따라 Claude Code 세션을 자동 실행하는 워크플로우 단위 |
앞의 세 레이어가 "어떻게 실행할지"를 정의한다면, Routines는 **"언제, 무엇을 계기로 실행할지"**를 정의합니다. 그리고 결정적인 차이가 하나 있는데, 바로 클라우드에서 실행된다는 점입니다. 노트북을 닫아도, 인터넷이 끊겨도 루틴은 돌아갑니다.
트리거 유형 세 가지
루틴을 시작하는 방법은 크게 세 가지입니다. 아래는 개념을 이해하기 위한 의사 코드 형태의 예시입니다.
# 1) 스케줄 기반 — cron 표현식으로 정기 실행
# 한국은 UTC+9 고정(서머타임 없음)이므로 KST 02:00 = UTC 17:00
schedule: "0 17 * * *" # 매일 KST 새벽 2시 실행
# 2) GitHub 웹훅 — PR 이벤트 발생 시 자동 시작
trigger:
event: pull_request.opened
# 3) API 트리거 — 외부 시스템에서 직접 호출
# 아래는 개념 설명용 가상 엔드포인트입니다. 실제 API URL은 공식 문서에서 확인하세요.
# POST https://api.claude.ai/routines/{routine-id}/triggerMCP(Model Context Protocol) — Claude와 GitHub, Slack, 데이터베이스 같은 외부 서비스를 연결해주는 표준 프로토콜입니다. 루틴 안에서 "GitHub 이슈를 읽고 Slack에 요약을 보내줘"가 가능한 건 MCP가 중간다리 역할을 해주기 때문입니다.
Hooks와 Routines, 뭐가 다른가
솔직히 처음엔 "Hooks랑 뭐가 다른 거지?" 하고 한참 헷갈렸는데, 정리하고 나니 꽤 명확합니다.
| 비교 항목 | Hooks | Routines |
|---|---|---|
| 실행 환경 | 로컬 머신 | 클라우드 |
| 트리거 | 도구 실행 이벤트(PreToolUse 등) | 스케줄 / API / 웹훅 |
| 로컬 종료 시 | 실행 불가 | 계속 실행 |
| 권한 분리 | 단일 모드 | review-only / deploy 분리 가능 |
| 적합한 용도 | 린트·포맷·로컬 검증 | 야간 배치·이벤트 기반 자동화 |
review-only 모드는 이슈 라벨 수정이나 PR 코멘트 작성처럼 읽기·주석 수준의 작업만 허용하고, 코드 변경이나 머지는 차단합니다. deploy 모드는 그 범위가 넓어져서 PR 생성·푸시까지 포함됩니다. 어떤 권한이 정확히 어느 모드에 속하는지는 프리뷰 기간 중 변경될 수 있으니, 공식 문서의 최신 스펙을 따르는 것을 권장합니다.
참고로 Routines가 클라우드의 어떤 런타임 위에서 돌아가는지(컨테이너인지 서버리스인지)는 현재 공개된 정보가 없습니다. 인프라에 민감한 환경이라면 이 부분도 고려해볼 필요가 있습니다.
실전 적용
예시 1: 야간 이슈 트리아지 자동화
실무에서 자주 맞닥뜨리는 상황인데, 아침에 출근하면 밤새 쌓인 이슈를 처리하느라 오전이 날아가는 경우가 있습니다. 제 팀 기준으로 이 루틴을 도입하고 나서 주 2시간 가까이 아꼈는데, 설정 자체는 30분이 채 안 걸렸습니다.
아래는 루틴 프롬프트 파일의 예시입니다. 실제 파일 경로나 키 구조는 공식 스펙에 따라 다를 수 있습니다.
<!-- .claude/routines/nightly-triage.md (의사 코드 형식) -->
# 야간 이슈 트리아지
## 스케줄
# 한국(UTC+9, 서머타임 없음): UTC 17:00 = KST 02:00
schedule: "0 17 * * *"
## 권한
mode: review-only
# review-only: 이슈 라벨·담당자 수정 허용, 코드 변경·PR 머지 불가
## 커넥터
connectors:
- github
- slack
## 작업 지침
1. 오늘 생성된 모든 오픈 이슈를 조회한다
2. 각 이슈를 다음 라벨 중 하나로 분류한다: bug / enhancement / question / duplicate
3. 심각도(severity)를 P0~P3로 평가한다
4. 담당 팀 레이블(backend / frontend / infra)을 추가한다
5. Slack #dev-issues 채널에 분류 요약을 전송한다| 구성 요소 | 설명 |
|---|---|
cron 표현식 |
UTC 17:00 → KST 02:00. 한국은 UTC+9 고정이라 계산이 단순합니다 |
review-only 모드 |
이슈 수정은 허용하되 코드 변경·배포는 차단. 첫 루틴으로 안전하게 시작하기 좋습니다 |
connectors |
MCP를 통해 GitHub와 Slack을 연결. 루틴 설정 시 각 커넥터 인증도 별도로 해야 합니다 |
예시 2: PR 오픈 시 자동 코드 리뷰
GitHub 웹훅과 연동하면 PR이 열리는 순간 Claude가 리뷰 세션을 시작합니다. 저도 처음엔 "AI 리뷰가 실제로 도움이 될까?" 반신반의했는데, 타입 안전성 이슈나 명백한 엣지 케이스를 꽤 잘 잡아냅니다.
<!-- .claude/routines/pr-review.md (의사 코드 형식) -->
# PR 자동 코드 리뷰
## 트리거
trigger:
event: pull_request.opened
event: pull_request.synchronize
## 권한
mode: review-only
# 코드 읽기·PR 코멘트 작성만 허용. 머지·브랜치 수정 불가
## 커넥터
connectors:
- github
## 작업 지침
1. 변경된 파일 diff를 분석한다
2. 다음 항목을 중점 검토한다:
- 타입 안전성 및 null 처리
- 성능 이슈 (N+1 쿼리: 루프 안에서 DB를 반복 조회하는 패턴)
- 보안 취약점 (OWASP Top 10 기준)
- 테스트 커버리지 누락
3. 인라인 코멘트로 구체적인 개선안을 제시한다
4. 전체 요약을 PR 본문 코멘트로 남긴다예시 3: 커스텀 슬래시 커맨드로 이슈 픽스
루틴과 함께 쓰면 시너지가 나는 슬래시 커맨드 예시입니다. 루틴이 이슈를 자동 분류하면, 개발자가 직접 픽스 커맨드를 호출하는 구조로 자연스럽게 연결됩니다.
<!-- .claude/commands/fix-issue.md -->
Find GitHub issue #$ARGUMENTS, analyze the root cause,
implement a fix, write a test that reproduces the bug,
and open a PR with a clear description.# 터미널에서 이렇게 호출합니다
/project:fix-issue 1234여러 루틴이 동시에 실행될 때 같은 저장소를 건드리면 충돌이 날 수 있습니다. 이 경우 Git Worktrees를 사용하면 각 루틴이 독립된 작업 공간에서 실행되어 문제를 예방할 수 있습니다. git worktree add ../project-routine-1 main 형태로 별도 디렉터리를 만들어두는 방식입니다.
장단점 분석
장점
| 항목 | 내용 |
|---|---|
| 클라우드 실행 | 로컬 머신 종료 여부와 무관하게 루틴이 실행됨 |
| 이벤트 기반 통합 | GitHub 웹훅, 외부 API 등 다양한 트리거 지원 |
| 권한 분리 | review-only / deploy 루틴을 별도 권한 모드로 운용 가능 |
| 생태계 통합 | MCP·Skills·Connectors 모두 루틴 내에서 사용 가능 |
| 반복 오버헤드 절감 | 트리아지·리뷰처럼 구조화된 반복 작업에서 체감 효과가 큼 |
단점 및 주의사항
| 항목 | 내용 | 대응 방안 |
|---|---|---|
| 일일 실행 한도 | Pro 5회 / Max 15회 / Team·Enterprise 25회 (UTC 기준 하루, 출처: 공식 블로그) | 중요 루틴 우선순위 선정 후 스케줄 분산 |
| 환경 변수 미전달 | 로컬 .env가 클라우드에 자동 전달되지 않음 |
루틴 설정에서 Secrets를 별도 등록 |
| API 토큰 일회 노출 | 생성 시 단 한 번만 표시됨 | 생성 즉시 패스워드 매니저에 저장 |
| 리서치 프리뷰 상태 | API 스펙·동작이 변경될 수 있음 | 중요 파이프라인에 즉시 적용하기보다 병행 테스트 권장 |
| 구독 사용량 차감 | 대화형 세션과 동일하게 토큰이 차감됨 | 루틴별 예상 토큰 소모량 사전 계산 |
| 런타임 불투명 | 클라우드 실행 환경(컨테이너 여부 등) 미공개 | 인프라 의존적인 작업은 신중하게 적용 |
Plan Mode — 루틴 설계 단계에서 유용합니다. 실제 코드를 실행하지 않고 Claude가 어떤 계획을 세우는지만 확인할 수 있어서, 루틴 프롬프트를 다듬을 때 안전하게 반복 테스트할 수 있습니다.
실무에서 가장 흔한 실수
- 머지 권한을 루틴에 부여하는 것 — 자동 생성된 PR은 반드시 사람이 검토한 뒤 머지하는 게 안전합니다. 루틴에는 PR 생성까지만 허용하고 머지는 수동으로 유지하는 것을 권장합니다.
- 환경 변수를 빠뜨리는 것 — 로컬에서 테스트할 땐 잘 돌아가다가 클라우드 루틴에서 실패하는 가장 흔한 원인입니다. 루틴 설정 시 필요한 모든 Secrets를 미리 목록화해두면 좋습니다.
- 루틴 프롬프트를 너무 모호하게 작성하는 것 — "이슈를 처리해줘"보다 "P0 버그 이슈에만
urgent라벨을 붙이고 백엔드 팀을 멘션해줘"처럼 구체적으로 작성할수록 결과가 예측 가능해집니다. Plan Mode로 먼저 드라이런을 해보면 의도대로 동작하는지 미리 확인할 수 있습니다.
마치며
Claude Code Routines는 AI를 일회성 도구에서 상시 동작하는 팀원으로 바꾸는 전환점입니다. 아직 리서치 프리뷰 단계이지만, 작은 루틴 하나부터 적용해보는 것만으로도 반복 업무가 얼마나 줄어드는지 체감할 수 있습니다.
지금 바로 시작해볼 수 있는 3단계:
- 야간 이슈 트리아지처럼 부담 없는 review-only 루틴을 첫 번째로 설정해볼 수 있습니다. 코드 변경 권한 없이 라벨 분류·요약 전송만 하는 루틴은 리스크가 낮아 실험하기 좋습니다. 공식 블로그에서 최신 스펙을 확인하고 설정해보세요.
- CLAUDE.md에 프로젝트 컨텍스트를 충실히 정리해두는 것을 권장합니다. 루틴이 클라우드에서 실행될 때 참조할 수 있는 유일한 프로젝트 지침이 이 파일이기 때문입니다. 코드 스타일, 브랜치 전략, 주요 제약사항을 미리 정리해두면 루틴 결과물의 품질이 달라집니다.
- 커스텀 슬래시 커맨드를 만들어 루틴과 연결해볼 수 있습니다.
.claude/commands/폴더에.md파일 하나만 추가하면/project:명령어이름형태로 호출할 수 있습니다. 루틴이 분류한 이슈를 개발자가 직접 픽스 커맨드로 처리하는 흐름이 자연스럽게 만들어집니다.
다음 글: Claude Code Hooks 완전 정복 — PreToolUse·PostToolUse 이벤트로 로컬 자동화 파이프라인 구축하기
참고 자료
- Introducing routines in Claude Code | Anthropic 공식 블로그
- Claude Code Routines: Automate Dev Workflows | DEV Community
- Automate workflows with hooks | Claude Code 공식 문서
- Common workflows | Claude Code 공식 문서
- We tested Anthropic's Claude Code Routines | VentureBeat
- Claude Code Routines: The Cloud Automation Branch | LaoZhang AI Blog
- awesome-claude-code | GitHub
- Claude Code Custom Commands: 3 Practical Examples | AI Engineering Report
- 7 Claude Code best practices for 2026 | eesel AI
