Claude Routine API 트리거로 워크플로우 자동화하기

이 글에서 다루는 내용

Claude Code의 새 기능 Routines의 API 트리거를 사용해 외부 시스템에서 Claude를 호출하는 방법을 정리합니다. Routine 생성, 토큰 발급, curl 한 줄 호출, 응답 구조, Sentry/Slack/n8n과 묶는 실전 시나리오와 자주 막히는 지점까지 한 번에 다룹니다. 2026년 4월 기준 리서치 프리뷰 단계로, Pro/Max/Team/Enterprise 플랜 사용자라면 바로 따라 할 수 있는 내용입니다.

1. Routine 기본 개념

1-1. 무엇이 새로워진 건가

Routine은 프롬프트 + 저장소 + 커넥터를 한 번 묶어 저장한 Claude Code 설정입니다. 한번 만들어 두면 Anthropic이 운영하는 클라우드 인프라에서 자동으로 실행되므로 노트북을 켜둘 필요가 없습니다. 기존에 /schedule 슬래시 명령으로 로컬에서 돌리던 흐름을 클라우드에서 트리거 기반으로 동작시키는 형태로 확장된 셈입니다.

1-2. 세 가지 트리거 비교

트리거	실행 시점	대표 사용처
Scheduled	Cron 표현식 또는 1회 예약	매일 아침 리포트, 야간 백로그 정리
API	외부에서 HTTP POST 요청	알림 시스템, 사내 도구, n8n/Make 연동
GitHub	PR open, push, release 등 이벤트	PR 자동 리뷰, 릴리스 노트 초안

ℹ️ 한 Routine에 여러 트리거를 동시에 붙일 수 있습니다. 예를 들어 "매일 아침 9시 정기 실행 + 필요할 때 API로 즉시 호출" 같은 조합이 가능합니다.

2. API 트리거가 특별히 강력한 이유

스케줄 트리거는 결국 cron 한 발이고, GitHub 트리거는 저장소 이벤트에 묶여 있습니다. 반면 API 트리거는 외부 시스템 어디에서든 HTTP 한 번이면 Claude 워크플로우가 발동합니다. 이 한 줄짜리 진입점 덕분에 다음 같은 구성이 가능해집니다.

Sentry/Datadog/PagerDuty의 알림 액션에서 직접 호출
회의록 자동화 도구(Fireflies, Otter)가 미팅 종료 후 트리거
사내 슬랙 슬래시 커맨드 → 백엔드 → Routine 호출
n8n, Make, Zapier 등 노코드 워크플로우의 한 노드로 편입
자체 제작한 모바일 앱이나 CLI 도구가 사용자의 자연어 요청을 백엔드로 위임

실제로 발표 글의 표현을 빌리면 "POST 한 번 보내면 세션 URL이 돌아온다"는 한 문장이 핵심입니다. 트리거 후 결과는 같은 Anthropic 클라우드에서 돌아가며, 진행 상황은 발급된 세션 URL에서 그대로 추적할 수 있습니다.

3. Routine 생성과 토큰 발급

3-1. 새 Routine 만들기

웹에서는 claude.ai/code/routines, CLI에서는 /schedule 명령으로 진입합니다. 데스크탑 앱의 "루틴(Routine)" 메뉴에서도 같은 화면으로 연결됩니다.

Routine을 만들 때 정해야 하는 항목은 세 가지입니다.

프롬프트 — 매번 실행될 작업 지시문. 일반 Claude Code 대화창과 동일한 자연어로 작성합니다.
저장소 — Routine이 작업할 GitHub 리포지터리. 비어 있어도 됩니다.
커넥터 — 사용할 MCP 서버 목록. 슬랙·노션·구글 드라이브 등 평소 쓰던 커넥터를 그대로 붙입니다.

3-2. API 트리거 추가와 토큰 발급

Routine 상세 화면의 "트리거 추가 → API"를 선택하면 토큰 발급 버튼이 보입니다. 토큰은 발급 시점 한 번만 보여주고 이후에는 다시 조회할 수 없습니다. 그 자리에서 비밀번호 매니저나 알림 도구의 시크릿 스토어에 옮겨 보관합니다.

ROUTINE_ID=rt_abcdef1234
ROUTINE_TOKEN=sk-routine-...

⚠️ 토큰을 분실했다면 토큰을 폐기(revoke)하고 다시 발급받아야 합니다. 같은 Routine에 여러 토큰을 두고 호출자별로 분리해 운영하는 패턴도 가능합니다.

3-3. 토큰 보관 원칙

토큰은 사실상 Routine을 임의로 발동시킬 수 있는 키입니다. 클라이언트 측 코드, 공개 저장소, 채팅 메시지에는 절대 두지 않습니다. n8n이나 Zapier 같은 워크플로우 도구라면 Credentials 영역에, Sentry/Datadog 같은 알림 시스템이라면 Webhook Secret 필드에 넣는 것이 표준 흐름입니다.

4. cURL로 첫 호출 해보기

4-1. 엔드포인트 구조

항목	값
Method	POST
URL	`https://api.anthropic.com/v1/claude_code/routines/{routine_id}/fire`
Authorization	`Bearer {routine_token}`
anthropic-beta	`experimental-cc-routine-2026-04-01`
Body	`{"text": "런타임 컨텍스트"}` (선택)

text 필드는 자유 형식 문자열입니다. 알림 본문, 배포 메타데이터, 사용자 입력 등 Routine이 그 회차에 참고할 정보를 그대로 흘려보내면 Routine 프롬프트 안에서 사용할 수 있습니다.

4-2. 실전 호출 예시

curl -X POST \
  https://api.anthropic.com/v1/claude_code/routines/$ROUTINE_ID/fire \
  -H "Authorization: Bearer $ROUTINE_TOKEN" \
  -H "anthropic-beta: experimental-cc-routine-2026-04-01" \
  -H "Content-Type: application/json" \
  -d '{"text": "오늘 아침 경제 뉴스 헤드라인 5개와 한 줄 요약을 만들어 슬랙 #news 채널에 올려줘."}'

예상 응답 보기

{
  "type": "routine_fire",
  "claude_code_session_id": "ses_01HZXY...",
  "claude_code_session_url": "https://claude.ai/code/sessions/ses_01HZXY..."
}

4-3. Python에서 호출

import os
import requests

ROUTINE_ID = os.environ["ROUTINE_ID"]
ROUTINE_TOKEN = os.environ["ROUTINE_TOKEN"]

resp = requests.post(
    f"https://api.anthropic.com/v1/claude_code/routines/{ROUTINE_ID}/fire",
    headers={
        "Authorization": f"Bearer {ROUTINE_TOKEN}",
        "anthropic-beta": "experimental-cc-routine-2026-04-01",
        "Content-Type": "application/json",
    },
    json={"text": "Sentry SEN-4521 알림: 결제 API 5xx 급증, 최근 배포 후 30분 내 발생"},
    timeout=10,
)
resp.raise_for_status()
print(resp.json()["claude_code_session_url"])

💡 응답은 세션 시작만 보장합니다. 본 작업 결과는 비동기로 실행되므로, 결과 확인은 응답에 포함된 세션 URL이나 Routine이 직접 결과를 게시하도록 한 슬랙/PR/이슈 코멘트 같은 출력 채널을 통해 합니다.

5. 실전 활용 시나리오

5-1. Sentry 알림 → 자동 분석 + PR 초안

Sentry의 알림 룰에서 Webhook 액션으로 Routine API를 호출하도록 연결합니다. text에는 이슈 제목·스택 트레이스 요약·해당 커밋 SHA를 넘깁니다. Routine 프롬프트에는 다음 같은 지시를 미리 박아둡니다.

아래 Sentry 알림 본문을 받아 다음을 수행한다:
1) 스택 트레이스에서 가장 의심스러운 함수를 식별
2) 최근 30개 커밋 중 관련 변경을 찾아 회귀 가능성을 평가
3) 결과를 GitHub 이슈로 등록하고, 가능하다면 핫픽스 PR 초안을 만든다
4) 슬랙 #incidents 채널에 이슈 링크와 1줄 요약을 포스트

5-2. 매일 아침 뉴스 스크랩 (스케줄 + API 병행)

매일 7시 정기 실행은 Schedule 트리거로, "지금 당장 한 번 더 돌려봐"는 슬랙 슬래시 커맨드로. 같은 Routine에 두 트리거를 함께 붙여 운영합니다.

# 슬랙 슬래시 커맨드 핸들러 (FastAPI 예시)
@app.post("/slack/news-now")
async def news_now(request: Request):
    requests.post(
        f"https://api.anthropic.com/v1/claude_code/routines/{ROUTINE_ID}/fire",
        headers={
            "Authorization": f"Bearer {ROUTINE_TOKEN}",
            "anthropic-beta": "experimental-cc-routine-2026-04-01",
        },
        json={"text": "임시 호출, 즉시 실행"},
    )
    return {"text": "뉴스 요약을 생성 중입니다. 잠시 후 #news 채널을 확인하세요."}

5-3. n8n에서 노코드로 묶기

n8n의 HTTP Request 노드 한 개만 추가하면 됩니다. 메서드 POST, URL은 위의 fire 엔드포인트, Authentication은 Header Auth로 Authorization에 베어러 토큰을 넣고 anthropic-beta 헤더를 추가합니다. 이전 노드의 출력값을 text 필드로 매핑하면 노코드 자동화 안에서 Claude가 한 단계로 동작합니다.

5-4. 회의록 → 제안서 초안

Fireflies, Otter, Fathom 같은 음성 회의 도구가 트랜스크립트를 webhook으로 보내는 기능을 사용합니다. Routine은 트랜스크립트에서 거래 조건과 요구 사항을 추출해 사내 템플릿에 맞춰 제안서 초안을 만들고, 검토할 채널이나 저장소에 결과를 떨어뜨립니다. 이때 text 길이가 길어질 수 있는데, 메시지 본문보다는 회의록 URL을 넘기고 Routine이 커넥터로 직접 가져오게 하는 편이 안정적입니다.

6. 사용량 제한과 운영 고려 사항

플랜	하루 Routine 실행 한도
Pro	5회
Max	15회
Team / Enterprise	25회

스케줄 트리거의 cron은 표준 5필드 표현식이며, 최소 간격은 1시간입니다. 분 단위 스케줄이나 L, W 같은 확장 문법은 사용할 수 없습니다. 시간대는 입력 시 로컬 타임존으로 받아 UTC로 저장됩니다.

API 트리거의 호출 자체는 위 한도와 별도지만, 실제 세션을 만들면 결국 같은 일일 한도를 소비합니다. 알림 시스템에서 한 번에 폭발적으로 호출되는 상황(retry storm)을 방지하기 위해 호출 측에서 디바운스 또는 큐잉을 두는 것이 안전합니다.

트러블슈팅

문제 1: 401 Unauthorized

가장 흔한 원인은 베타 헤더 누락 또는 만료된 베타 식별자입니다. anthropic-beta: experimental-cc-routine-2026-04-01이 빠지면 인증을 통과하지 못합니다. 토큰 자체가 폐기됐을 가능성도 함께 확인합니다.

문제 2: 호출은 됐는데 세션이 비어 있다

Routine 프롬프트가 text에 들어온 값을 사용하도록 작성되어 있지 않으면 빈손으로 시작합니다. 프롬프트 안에 다음 같은 지시를 명시적으로 두는 것이 안전합니다.

호출 시 함께 전달된 text 본문을 1차 입력으로 삼는다. text가 비어 있으면 평소 기본 흐름(예: 오늘 날짜 기준 뉴스 수집)을 수행한다.

문제 3: 동일 이벤트로 중복 세션이 생성된다

fire 엔드포인트에는 idempotency key가 없습니다. 호출 측이 retry를 걸면 호출 횟수만큼 세션이 새로 만들어집니다. Sentry나 Datadog처럼 알림 도구가 자체 재시도를 하는 경우, 다음 두 가지 중 하나를 적용합니다.

호출 측에서 일정 시간 내 동일 이벤트 ID를 기억해 디바운스
중간에 큐(SQS, n8n, Lambda 등)를 두고 거기서 1회만 fire

문제 4: 시간대가 어긋난다

스케줄은 UTC로 저장됩니다. 한국 시간 오전 9시로 보이게 하려면 입력 단계에서 KST를 명시하거나, cron을 직접 작성하는 경우 UTC 0시(0 0 * * *)로 설정해야 합니다. UI에서 입력했는데 시간이 어긋난다면 브라우저의 타임존 설정을 함께 확인합니다.

문제 5: 토큰을 잃어버렸다

토큰은 발급 시 1회만 노출되고 이후 조회가 불가능합니다. 분실 시 Routine 설정에서 해당 토큰을 폐기(revoke)하고 새 토큰을 발급해 호출 측 시크릿을 갱신합니다. 한 Routine에 토큰을 여러 개 두는 것이 가능하므로, 호출 주체별로 분리하면 폐기 영향 범위를 줄일 수 있습니다.

마무리

Routine API 트리거의 가치는 Claude를 자체 워크플로우의 일부로 박아 넣을 수 있다는 점에 있습니다. 알림 도구든 사내 봇이든 노코드 워크플로우든, HTTP POST 한 번이면 Claude 세션이 클라우드에서 시작되고 결과는 미리 정해둔 채널로 떨어집니다. 노트북을 켜둘 필요가 없고, 별도 서버 운영도 필요하지 않습니다. 리서치 프리뷰 단계라 베타 헤더와 일일 한도가 붙어 있지만, 자동화 워크플로우의 실험 환경으로는 이미 충분히 쓸 만합니다.

공식 가이드: Automate work with routines
API 레퍼런스: Trigger a routine via API
발표 글: Introducing routines in Claude Code
관련 글: Claude Code 설치 및 활용 완벽 가이드

'AI & LLM' 카테고리의 다른 글

OpenRouter 입문 - AI 모델 게이트웨이 한 번에 이해하기 (0)	2026.04.30
Claude Code 활용 매뉴얼 - 8가지 원칙 (0)	2026.04.29
Claude for Chrome 사용기 - 브라우저가 에이전트가 되는 순간 (0)	2026.04.27
Claude Code + VS Code + 로컬 LLM 완벽 세팅 가이드 (0)	2026.04.25
OpenClaw에 Ollama 로컬 LLM 연동하기 (2)	2026.04.24