Claude Code Routines: 서버 없이 GitHub 이벤트로 에이전틱 루프 자동화하기

PR이 올라오는 순간, 아무도 건드리지 않았는데 코드 리뷰 코멘트가 달린다. 릴리스를 퍼블리시하면 변경 로그가 자동으로 완성된다. 서버도 없고, cron도 없고, GitHub Actions 워크플로 파일도 없다. 이 화면을 처음 봤을 때 "이게 진짜 되는 건가?" 싶었습니다.

2026년 4월, Anthropic이 Claude Code Routines를 리서치 프리뷰로 내놨습니다. Claude Code는 Anthropic이 만든 개발자용 CLI 에이전트로, 터미널에서 코드 작성·수정·실행을 자율적으로 처리하는 도구입니다. GitHub Copilot이나 Cursor가 편집기 안에서 코드를 제안하는 방식과 달리, Claude Code는 셸 명령, 파일 수정, Git 작업까지 직접 실행합니다. Routines는 그 세션을 한 번 구성해두면 이후 실행을 Anthropic 클라우드 인프라가 전담하는 기능입니다. 로컬 프로세스도, 셀프 호스팅 CI 러너도 필요 없습니다.

팀에서 실제로 써본 결과, 가장 체감되는 변화는 이겁니다. 야간에 올라온 PR이 다음 날 출근했을 때 이미 1차 리뷰가 완료된 상태고, 릴리스 태그를 붙이면 변경 로그가 알아서 채워져 있습니다. 이 글에서는 GitHub 이벤트를 트리거로 클라우드에서 에이전틱 루프를 돌리는 구체적인 구성 방법과, 초기 설계에서 자주 놓치는 함정을 다룹니다.

핵심 개념

Routine이 뭘 하는 건지, 한 문장으로

Routine은 "구성된 프롬프트 + 저장소 컨텍스트 + 커넥터"를 받아, 트리거가 발생할 때마다 신선한 Claude Code 세션을 스핀업해서 자율 실행하는 클라우드 에이전트입니다.

에이전틱 루프(Agentic Loop): AI 에이전트가 인간의 개입 없이 도구 호출 → 결과 확인 → 다음 액션 결정을 반복하는 자율 실행 사이클. Routine은 이 루프를 클라우드에서 관리해줍니다.

트리거 감지
    → 새 Claude Code 세션 시작
    → 프롬프트 읽기 + 저장소 검사
    → 커넥터(MCP) & 셸 커맨드 호출
    → 결과를 커밋·PR·메시지·API 호출로 출력
    → 세션 종료

사람이 개입하는 지점은 없습니다. 실행 중에 "잠깐, 이게 맞나요?"라고 물어볼 수 없는 구조입니다. 그래서 프롬프트 설계가 전부라고 해도 과언이 아닙니다.

세 가지 트리거 유형

이 글에서 집중할 건 GitHub 트리거입니다. Claude GitHub App을 저장소에 설치하면 Anthropic 웹훅 서버가 이벤트를 직접 수신해서 에이전트를 기동합니다. GitHub Actions처럼 .github/workflows/ 파일을 만들 필요가 없습니다.

GitHub 트리거의 작동 구조

GitHub 저장소
    └─ 이벤트 발생 (PR opened, push, release...)
         └─ Claude GitHub App (설치 필요)
              └─ Anthropic 웹훅 서버가 이벤트 수신
                   └─ 매핑된 Routine 기동
                        └─ 에이전트가 저장소 접근 + 작업 수행
                             └─ PR 코멘트 / 브랜치 푸시 / API 호출

로컬에서 실행되는 건 아무것도 없습니다. 기본적으로 claude/ 접두사 브랜치에만 푸시가 허용되어 있어, 에이전트가 실수로 main에 직접 푸시하는 사고는 구조적으로 막혀 있습니다. 이 가드레일은 Routine 설정에서 변경할 수 있습니다만, 처음 도입할 때는 기본값 그대로 두는 편을 권장합니다.

GitHub App 설치 시 저장소 read/write 권한이 부여됩니다. 보안에 민감한 팀이라면 App 설치 범위를 특정 저장소로 제한하고, 에이전트가 어떤 브랜치·파일에 접근하는지를 프롬프트 수준에서 명시적으로 제어하는 것이 좋습니다.

리서치 프리뷰란?: 일반 출시 전 단계로, Pro/Max/Team/Enterprise 유료 플랜에서 접근 가능합니다. API 스펙, 한도, 동작이 예고 없이 변경될 수 있습니다. 아직 별도 신청 절차 없이 해당 플랜이면 활성화됩니다.

실전 적용

예시 1: PR 열리는 즉시 코드 리뷰 자동화

솔직히 팀에서 가장 반응이 좋았던 케이스입니다. 주니어 개발자가 PR을 올리면 몇 초 만에 리뷰 코멘트가 달립니다. 시니어가 퇴근한 저녁에 올라온 PR도 다음 날 아침이면 이미 1차 리뷰가 완료된 상태입니다. 사람의 리뷰를 대체하는 게 아니라, 기계적으로 확인할 수 있는 항목을 미리 걸러주는 역할이라 거부감도 없었습니다.

아래 YAML은 Claude Code의 Routine 설정 화면(UI 폼 또는 CLI claude routine create)에서 구성하는 방식을 개념적으로 표현한 것입니다. 실제 인터페이스는 공식 문서를 참고하시는 것을 권장합니다.

trigger:
  type: github
  event: pull_request.opened
  repository: your-org/your-repo
 
prompt: |
  이 PR을 팀 체크리스트에 따라 리뷰해라.
  다음 항목을 확인하고 인라인 코멘트와 요약 코멘트를 GitHub에 남겨라:
  - 테스트 커버리지 공백 (새 함수에 테스트가 없는 경우)
  - 보안 안티패턴 (하드코딩된 크레덴셜, SQL 인젝션 가능성)
  - 문서 누락 (공개 API 변경 시 README 미업데이트)
 
  코멘트는 구체적이고 개선 방향을 제시하는 형태로 작성하라.
  모든 결과는 GitHub PR 코멘트로만 남기고, 브랜치 커밋은 하지 마라.
 
connectors:
  - github

라벨 기반 필터(pull_request.labeled)를 활용하면 팀이 "ai-review" 라벨을 붙일 때만 실행되도록 제어할 수 있습니다. 일일 실행 한도가 있는 현재 리서치 프리뷰 환경에서 특히 유용합니다. 팀이 리뷰가 필요하다고 판단한 PR에만 에이전트를 쓰는 구조라 신뢰도도 더 높게 유지됩니다.

예시 2: 릴리스 이벤트에서 변경 로그 자동 생성

버전 태그를 붙이고 릴리스를 퍼블리시하는 순간, 변경 로그가 이미 완성되어 있다면 어떨까요. 처음엔 이게 얼마나 번거로운 작업인지 과소평가했는데, 매 릴리스마다 커밋 목록을 뒤지는 작업이 실제로 꽤 지칩니다.

trigger:
  type: github
  event: release.published
  repository: your-org/your-repo
 
prompt: |
  이 릴리스에 포함된 커밋을 분석하라.
 
  다음 기준으로 변경 로그를 작성하라:
  - Breaking Changes (있는 경우 최상단)
  - New Features
  - Bug Fixes
  - Dependencies
 
  사용자 관점의 언어로 작성하고, 내부 리팩토링은 제외하라.
  완성된 변경 로그로 GitHub 릴리스 노트를 업데이트하라.
 
connectors:
  - github

프롬프트 안에서 {{ release.tag_name }} 같은 컨텍스트 변수를 사용할 수 있는지는 공식 문서에서 지원 변수 목록을 먼저 확인하시는 것을 권장합니다. 사용 가능한 변수 범위가 트리거 유형에 따라 다릅니다.

출력이 명확한 아티팩트(릴리스 노트)이고, 실행 중 사람의 판단이 필요 없다는 점이 Routine에 딱 맞는 태스크입니다. 입력(커밋 목록)과 출력(릴리스 노트 업데이트)이 명확할수록 에이전트가 실수할 여지가 줄어듭니다.

예시 3: push 이벤트로 코드 품질 드리프트 감지

이 패턴은 팀에서 "기술 부채 가시화"를 목표로 도입했습니다. 개별 PR 리뷰에서 놓치는 패턴들, 예를 들어 TODO 주석 누적이나 테스트 없이 추가된 공개 함수들을 자동으로 추적합니다. 처음엔 이슈가 너무 많이 생기는 거 아닐까 걱정했는데, "이슈가 없으면 아무것도 하지 마라"는 조건 하나가 소음을 대부분 잡아줬습니다.

trigger:
  type: github
  event: push
  branch: main
  repository: your-org/your-repo
 
prompt: |
  방금 머지된 커밋을 분석하라.
  다음 항목을 확인하고 이슈가 있으면 GitHub Issue를 생성하라:
 
  1. 새로 추가된 TODO/FIXME 코멘트 목록
  2. 테스트 없이 추가된 공개 함수
  3. 환경 변수 직접 참조 (process.env를 config 모듈 없이 사용)
 
  이슈는 'tech-debt' 라벨을 붙이고, 발견된 파일 경로와 라인 번호를 포함하라.
  이슈가 없으면 아무 동작도 하지 마라.
 
connectors:
  - github

마지막 줄 "이슈가 없으면 아무 동작도 하지 마라"가 생각보다 중요합니다. 명시하지 않으면 에이전트가 "이상 없음 확인 완료"라는 이슈를 열어버리는 경우가 실제로 생깁니다. 입력에 이상이 없을 때의 동작도 프롬프트에서 명시해두는 것을 권장합니다.

push를 아무 조건 없이 트리거로 쓰면 활발한 개발일에 일일 한도가 바닥날 수 있습니다. branch: main 필터처럼 머지 이후에만 실행되도록 제한하는 편이 좋습니다.

예시 4: API 트리거로 Slack → Linear 티켓 파이프라인

GitHub 이벤트가 아닌 API 트리거 예시도 하나 소개합니다. Slack에서 특정 이모지 반응이 달린 메시지를 버그 티켓으로 자동 변환하는 패턴입니다. API 트리거는 외부 시스템이 먼저 Routine을 호출하는 구조라, Slack 앱이 이벤트를 감지하고 → Routine API를 호출하는 흐름입니다. MCP 커넥터 생태계가 얼마나 실용적인지 잘 보여주는 케이스라 개인적으로도 즐겨 쓰는 패턴입니다.

# Slack 앱에서 Claude Routine API 호출
curl -X POST https://api.anthropic.com/v1/claude-code/routines/{routine_id}/fire \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-beta: experimental-cc-routine-2026-04-01" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "slack_message": "결제 페이지에서 500 에러 발생 중, 재현 100%",
      "channel": "#bugs",
      "reporter": "alice"
    }
  }'

위 엔드포인트 URL과 베타 헤더(experimental-cc-routine-2026-04-01)는 리서치 프리뷰 기준입니다. 스펙이 변경될 수 있으므로 실제 연동 전에 공식 API 문서에서 최신 스펙을 확인하시는 것을 권장합니다.

trigger:
  type: api
 
prompt: |
  다음 Slack 메시지를 분석해 Linear 버그 티켓을 생성하라:
 
  메시지: {{ input.slack_message }}
  채널: {{ input.channel }}
  보고자: {{ input.reporter }}
 
  티켓에 포함할 내용:
  - 제목: 간결한 버그 설명
  - 우선순위: 메시지 내용 기반 추정 (500 에러 = High)
  - 재현 방법: 메시지에서 추출 가능한 정보
  - 보고자와 원본 Slack 링크
 
connectors:
  - slack
  - linear

이 패턴이 특히 효과적인 건 Slack과 Linear라는 두 외부 시스템을 별도의 웹훅 서버나 인증 브릿지 없이 연결할 수 있다는 점입니다. 기존에는 이런 연동에 Lambda 함수 하나 정도는 필요했는데, 커넥터가 인증을 대신 처리해줍니다.

장단점 분석

실제로 몇 달 써보면서 느낀 점을 솔직하게 정리해봤습니다. 좋은 점만 있는 건 아니고, 리서치 프리뷰 특성상 아직 팀 전체에 무조건 권장하기엔 이른 부분도 있습니다.

장점

단점 및 주의사항

MCP (Model Context Protocol): Anthropic이 정의한 AI 에이전트용 도구 연동 프로토콜. Routine의 커넥터는 이 프로토콜 기반으로 Slack, Linear 등 외부 서비스와 통신합니다. 로컬 MCP 서버는 현재 지원하지 않고, Anthropic이 클라우드에서 호스팅하는 커넥터만 사용할 수 있습니다.

실무에서 가장 흔한 실수

1. 출력 형태를 프롬프트에 명시하지 않는 경우 — "리뷰하라"고만 쓰면 에이전트가 브랜치 커밋을 할지, 코멘트를 남길지, 이슈를 열지 스스로 판단합니다. "GitHub PR 코멘트로만 결과를 남겨라. 커밋하지 마라"처럼 출력 경계를 명확히 지정하는 것을 권장합니다.

2. "아무것도 없으면 아무것도 하지 마라" 조건 생략 — 에이전트는 뭔가 성과를 보여주고 싶어하는 경향이 있습니다. 조건을 명시하지 않으면 "이슈 없음 확인 완료" 코멘트나 빈 PR이 만들어지는 경우가 생깁니다.

3. 일일 한도를 고려하지 않은 트리거 설계 — push를 아무 조건 없이 트리거로 쓰면 팀의 활발한 개발일에 한도가 바닥납니다. 브랜치 필터(branch: main)나 라벨 조건을 조합하는 방식이 좋습니다.

마치며

Claude Code Routines의 핵심 가치는 "에이전트가 뭘 할 수 있냐"가 아니라 "출력이 명확한 반복 작업을 인프라 없이 자동화할 수 있냐"에 있습니다.

아직 리서치 프리뷰라 일일 한도가 낮고 스펙이 유동적이지만, 지금이 오히려 팀에 맞는 패턴을 실험하기 좋은 시점이기도 합니다. 처음부터 모든 걸 자동화하려 하지 않고, 가장 단순하고 결과가 명확한 것 한 가지에서 출발하는 편이 안전합니다.

지금 바로 시작해볼 수 있는 3단계:

1. Claude GitHub App 설치 — claude.ai/code에서 Routines 설정으로 이동해 저장소에 App을 연결하면 GitHub 이벤트를 웹훅으로 수신할 준비가 됩니다. 이 단계 없이는 GitHub 트리거가 동작하지 않습니다.

2. PR 코드 리뷰 Routine 하나 만들어보기 — pull_request.opened 트리거로 시작하되, 프롬프트 마지막에 "브랜치 커밋은 하지 말고 GitHub PR 코멘트로만 결과를 남겨라"를 명시해두시면 의도치 않은 브랜치 생성을 방지할 수 있습니다.

3. 라벨 기반 필터로 실행 빈도 조절하기 — pull_request.labeled + ai-review 라벨 조합을 활용하면 팀이 원할 때만 에이전트가 동작하도록 제어할 수 있습니다. 일일 한도를 아껴두면서 점진적으로 신뢰를 쌓아가는 방식으로 도입할 수 있습니다.

참고 자료

• Automate work with routines | Claude Code 공식 문서
• Trigger a routine via API | Claude API 공식 문서
• Claude on X — Routines 출시 공지 (2026-04-14)
• Anthropic adds routines to redesigned Claude Code | 9to5Mac
• Claude Code can now do your job overnight | The New Stack
• Claude Code Routines: Anthropic's Answer to Unattended Dev Automation | DevOps.com
• Claude Code Routines: From Assistant to Autonomous Agent | Medium
• Claude Code Routines: A Practical Guide (2026) | Nimbalyst
• Claude Code Routines Tutorial | Builder.io
• Claude Code Routines: 8 Prompts + What Breaks | Linas Substack
• Week 16 릴리스 노트 (2026-04-13~17) | Claude Code Docs
• How I Turned Slack Chaos Into Linear Tickets With Claude Code | Samuel Lawrentz