Claude Code Hooks × Routines × Workflow로 개발 자동화 파이프라인 구축하기

이 기사에서 알 수 있는 것

• Claude Code의 자동화 기능을 Hooks · Routines · Dynamic Workflows의 3개 계층으로 정리하여, 사용 구분 기준을 이해할 수 있습니다.
• settings.json에 Hooks를 설정하여 코드 포맷팅(Code Formatting), 커맨드 가드(Command Guard), 알림을 자동화하는 구현 패턴을 습득할 수 있습니다.
• Routines를 통해 클라우드 상의 스케줄 실행, GitHub 이벤트 기반(Event-driven), API 기반의 3가지 트리거를 설정할 수 있습니다.
• Dynamic Workflows에서 agent() / parallel() / pipeline()을 사용하여 수십~수백 개의 서브 에이전트(Sub-agent)를 오케스트레이션(Orchestration)할 수 있습니다.
• 3개 계층을 조합한 CI/CD 파이프라인 설계 패턴을 이해하고 실제 프로젝트에 적용할 수 있습니다.

대상 독자

• 상정 독자: Claude Code를 일상적으로 사용하고 있는 중급~상급 개발자
• 필요한 전제 지식:
  • Claude Code v2.1.154 이후의 기본 조작 (파일 편집, Bash 실행)
  • Git/GitHub의 기본적인 워크플로우 (Branch, PR, CI/CD)
  • JSON 읽기/쓰기, JavaScript 기본 구문
  • 터미널에서의 쉘 스크립트(Shell Script) 조작

결론 · 성과

Claude Code의 자동화 기능은 3개의 계층으로 구성되어 있으며, 각각 서로 다른 유스케이스(Use case)를 커버합니다. Hooks는 툴 실행 전후의 가드레일(Guardrail), Routines는 클라우드 상의 정기 실행, Dynamic Workflows는 대규모 멀티 에이전트 오케스트레이션(Multi-agent Orchestration)을 담당합니다.

Anthropic의 공식 문서에 따르면, 이것들을 조합함으로써 다음과 같은 성과가 보고되었습니다.

• Hooks: 모든 파일 편집에 대해 포맷터(Formatter)를 자동 적용하여, 수동 prettier / ruff 실행을 제로(0)로 만들 수 있습니다.
• Routines: GitHub PR에 대한 자동 리뷰, 야간 배치 처리(Batch processing), 알림 대응을 무인으로 실행합니다 (런타임 비용 $0.08/시간).
• Dynamic Workflows: Bun (JavaScript 런타임)의 Zig → Rust 이식 작업에서 75만 행의 코드를 11일 만에 생성했습니다 (공식 블로그 사례).

단, Routines는 2026년 6월 시점에서 리서치 프리뷰(Research Preview) 단계이며, API나 동작이 변경될 가능성이 있습니다. Dynamic Workflows는 2026년 5월 28일 릴리스로 일반 제공(GA)되고 있으나, 대량의 토큰을 소비하므로 운영 환경에 도입할 때는 이러한 제약을 이해한 후 단계적으로 적용하십시오.

Claude Code 자동화의 3계층 아키텍처를 이해하기

Claude Code의 자동화는 용도와 실행 환경이 다른 3개의 계층으로 나뉘어 있습니다. 각 계층은 독립적으로 사용할 수 있지만, 조합함으로써 개발 파이프라인 전체를 커버할 수 있습니다.

3계층의 전체상과 사용 구분

계층	기능	실행 환경	트리거	전형적인 유스케이스
Hooks	툴 실행 전후의 결정론적 규칙	로컬 (세션 내)	라이프사이클 이벤트	코드 포맷팅, 커맨드 가드, 알림
Routines	스케줄 · 이벤트 기반 자동 실행	Anthropic 클라우드	Cron/GitHub/API	PR 자동 리뷰, 야간 배치, 알림 대응
Dynamic Workflows	멀티 에이전트 오케스트레이션	로컬 (백그라운드)	사용자 지시/ultracode	코드 감사, 대규모 이식, 리서치

왜 3계층으로 나뉘어 있는가

이 분리에는 설계상의 이유가 있습니다.

Hooks는 "무슨 일이 있어도 반드시 실행되는" 결정론적인 규칙입니다. LLM의 판단에 의존하지 않고, 쉘 커맨드(Shell command)로 확실하게 규칙을 강제합니다. 예를 들어, "Claude Code가 파일을 편집하면 반드시 Prettier를 실행한다"라는 규칙은 LLM이 잊어버리지 않고 매번 적용됩니다.

Routines는 노트북을 닫아도 계속 움직이는 클라우드 실행 환경입니다. GitHub PR이 생성된 타이밍에 리뷰를 돌리거나, 매일 밤 3시에 백로그(Backlog)를 정리하는 처리는 개발자의 로컬 환경에 의존해서는 안 됩니다.

Dynamic Workflows는 "하나의 컨텍스트 윈도우 (Context Window)에 담을 수 없는 작업"을 처리하기 위한 메커니즘입니다. 수백 개의 파일에 대한 보안 감사를 에이전트 하나로 수행하면 컨텍스트가 넘쳐버립니다. Workflows는 작업을 분할하고 중간 결과물을 스크립트 변수에 유지함으로써 이러한 제약을 회피합니다.

주의: 세 가지 계층을 모두 사용할 필요는 없습니다. 많은 프로젝트에서는 Hooks만으로도 충분한 자동화를 구현할 수 있습니다. Routines는 다인원 팀에서의 운영, Workflows는 대규모 코드베이스 조작 시에 비로소 필요해지는 경우가 대부분입니다.

Hooks로 결정론적인 자동화 규칙 설정하기

Hooks는 Claude Code의 라이프사이클 이벤트 (Lifecycle Event)에 연결된 쉘 커맨드 (Shell Command)입니다. LLM에게 매번 "코드를 정리해줘"라고 부탁하는 대신, settings.json에 작성한 설정에 따라 확실하게 실행됩니다.

Hooks 설정의 기본 구조

Hooks는 .claude/settings.json (프로젝트 단위) 또는 ~/.claude/settings.json (사용자 단위)에 설정합니다.

{
"hooks": {
"<이벤트명>": [
...

matcher는 도구 이름의 패턴이며, Write|Edit와 같이 파이프(|)를 사용하여 여러 개를 지정할 수 있습니다. 환경 변수 $CLAUDE_TOOL_INPUT_FILE_PATH나 $CLAUDE_TOOL_INPUT을 통해 도구의 입출력을 참조할 수 있습니다.

주요 라이프사이클 이벤트

실제 개발에서 사용 빈도가 높은 이벤트는 다음 4가지입니다.

이벤트	발생 타이밍	용도
PreToolUse	도구 실행 전	커맨드 가드 (Command Guard), 인자 (Argument) 재작성
PostToolUse	도구 실행 후	자동 포맷팅 (Auto-formatting), 로그 기록, 검증
SessionStart	세션 시작 시	환경 체크, 리마인더 표시
PostResponse	Claude 응답 완료 후	데스크톱 알림, 요약 기록

공식 문서에는 31종의 라이프사이클 이벤트가 정의되어 있지만 (2026년 6월 기준), 위 4가지로 대부분의 유스케이스 (Use Case)를 커버할 수 있습니다.

구현 패턴 1: 파일 저장 시 자동 포맷팅

Claude Code가 파일을 편집할 때마다 언어에 맞는 포매터 (Formatter)를 자동으로 실행합니다.

{
"hooks": {
"PostToolUse": [
...

이 구현을 선택한 이유:

• PostToolUse를 사용하여 Claude의 파일 편집이 완료된 직후에 포매터가 실행됨
• case 문을 사용하여 확장자에 따른 포매터를 선택하므로, 다국어 프로젝트에서도 하나의 설정으로 대응 가능
• 2>/dev/null과 exit 0을 사용하여, 포매터가 설치되지 않은 언어에서도 에러가 발생하지 않음

구현 패턴 2: 위험한 커맨드 차단

rm -rf /나 DROP TABLE과 같은 파괴적인 커맨드를 Claude Code가 실행하려고 할 때 차단합니다.

{
"hooks": {
"PreToolUse": [
...

exit 2는 특별한 종료 코드(Exit Code)로, "도구 실행을 차단하고 피드백 메시지를 Claude에게 반환함"을 의미합니다. exit 0은 "문제 없음, 도구 실행 계속"을 의미합니다.

구현 패턴 3: 세션 시작 시 환경 체크

세션 시작 시 프로젝트의 셋업 (Setup) 상태를 자동으로 체크합니다.

{
"hooks": {
"SessionStart": [
...

Hooks의 3가지 타입: command · prompt · agent

위의 예시는 모두 type: "command" (쉘 커맨드 직접 실행)이지만, 더 고도화된 판단이나 외부 연동이 필요한 경우에는 4가지 추가 타입을 사용할 수 있습니다.

타입	판단 방법	유스케이스
command	쉘 종료 코드	패턴 매칭 (Pattern Match), 포맷팅, 알림
http	HTTP 엔드포인트로 POST	외부 서비스 연동, Webhook 알림
mcp_tool	연결된 MCP 서버의 도구 호출	MCP를 통한 검증 및 기록
prompt	Claude 모델에 입력을 평가하게 함	코드 리뷰, 보안 체크
agent	서브 에이전트가 도구를 사용하여 검증	복잡한 조건의 다단계 검증 (실험적 기능)

prompt 타입의 예로, SQL 인젝션 (SQL Injection) 가능성이 있는 코드를 탐지하는 경우가 있습니다.

{
"hooks": {
"PreToolUse": [
...

prompt 타입은 Claude의 소형 모델을 호출하여 평가하기 때문에, command보다 레이턴시 (Latency)가 큽니다. 패턴 매칭으로 충분한 경우에는 command 타입을 우선적으로 사용하세요.

주의할 점: Hooks의 command 내에서 싱글 쿼트 (Single Quote)를 사용하면 JSON 파싱 에러가 발생합니다. 쉘 커맨드 내의 문자열은 반드시 더블 쿼트 (Double Quote)로 이스케이프하거나, 외부 스크립트 파일을 호출하는 방식으로 작성해야 합니다.

Routines로 클라우드 상의 정기 실행 설정하기

Routines는 2026년 4월에 출시된 기능으로, Claude Code의 세션을 클라우드 상에서 자동으로 실행합니다. 노트북을 닫아도 동작이 계속 유지되므로, "매일 밤 3시에 PR 리뷰", "PR이 생성되면 자동으로 코드 리뷰"와 같은 유스케이스에 대응합니다.

Routines의 3가지 트리거

트리거	설명	설정 방법
Schedule	cron 식에 기반한 정기 실행 (최소 간격: 1시간)	CLI /schedule 또는 Web UI
GitHub Event	PR 생성, Release 공개 등의 리포지토리 이벤트	Web UI 전용
API	HTTP POST로 임의의 타이밍에 기동	Web UI에서 토큰 발행 후, curl 등으로 호출

하나의 Routine에 여러 트리거를 조합하는 것도 가능합니다. 예를 들어 "매일 밤의 PR 리뷰 + 신규 PR 생성 시의 리뷰"를 하나의 Routine으로 구현할 수 있습니다.

CLI에서 Routine 생성하기

# 매일 아침 9시에 PR 리뷰를 실행하는 Routine 생성
/schedule daily PR review at 9am
# 1회성 스케줄 실행
...

/schedule은 CLI를 통한 Schedule 트리거 전용입니다. GitHub Event 트리거나 API 트리거 설정은 claude.ai/code/routines의 Web UI에서 수행합니다.

GitHub Event 트리거 설정 예시: 자동 PR 리뷰

Web UI에서 Routine을 생성하고 다음과 같이 설정합니다.

• 프롬프트 (Prompt): 리뷰 지시 사항을 기술

Review the pull request according to our team's code review checklist:
1. Check for security vulnerabilities (SQL injection, XSS, etc.)
2. Verify error handling covers edge cases
...

• 리포지토리 (Repository): 리뷰 대상 GitHub 리포지토리 선택
• 트리거 (Trigger): GitHub Event → pull_request.opened 선택
• 필터 (Filter): is_draft = false (Draft PR 제외)

API 트리거 설정 예시: 알람 대응 자동화

모니터링 도구 (Datadog, PagerDuty 등)로부터의 알람으로 Routine을 기동하여, 자동으로 원인 조사를 수행하는 예시입니다.

curl -X POST \
https://api.anthropic.com/v1/claude_code/routines/trig_XXXX/fire \
-H "Authorization: Bearer sk-ant-oat01-xxxxx" \
...

응답에는 세션 URL이 포함되어 있으며, 브라우저에서 Claude의 조사 과정을 실시간으로 확인할 수 있습니다.

{
"type": "routine_fire",
"claude_code_session_id": "session_01HJKLMNOPQRSTUVWXYZ",
...

Routines의 제약 사항 및 주의 사항

비용 측면:

• 일반적인 Claude API Rate +
  런타임(Runtime) $0.08/시간 - 45초의 Routine 실행 시 약 $0.001 (런타임 비용만 해당. 토큰 비용은 별도)

제약 사항:

• 로컬 파일 접근 불가 (매번 리포지토리를 클론)
• 리서치 프리뷰(Research Preview) 단계이므로, API 동작이 변경될 가능성이 있음
• 일일 실행 횟수 상한 있음 (플랜에 따라 다름)
• MCP Connector 인증은 claude.ai 측 계정에 귀속됨

보안 주의 사항:

• Routine이 실행하는 액션(commit, PR 코멘트 등)은
  사용자의 GitHub 계정으로서 실행됨 - 기본적으로
  claude/

접두사(prefix)가 붙은 브랜치에만 push 가능. 제한 해제는 명시적인 설정이 필요함

자주 발생하는 실수: /schedule
명령어를 CLI에서 찾을 수 없는 경우, ANTHROPIC_API_KEY
환경 변수가 설정되어 있는지 확인하십시오. /schedule은 claude.ai 구독 로그인이 필요하며, Console API 키나 Bedrock/Vertex 인증으로는 동작하지 않습니다.

Dynamic Workflows로 대규모 멀티 에이전트(Multi-agent) 실행하기

Dynamic Workflows는 2026년 5월 28일에 일반 제공(GA)된 기능으로, JavaScript 스크립트를 통한 서브 에이전트(Sub-agent)의 오케스트레이션(Orchestration)을 실현합니다. 하나의 컨텍스트 윈도우(Context Window)에 담을 수 없는 대규모 태스크를 수십~수백 개의 에이전트로 분산하여 실행할 수 있습니다.

Workflows의 기본 구조

Workflows의 핵심은 Claude가 동적으로 생성하거나(또는 사용자가 저장하는) JavaScript 스크립트입니다.

export const meta = {
name: 'security-audit',
description: 'Audit API endpoints for auth and injection vulnerabilities',
...

4가지 기본 프리미티브(Primitives)

프리미티브	역할	동기 모델
agent(prompt, opts?)	서브 에이전트 1개를 실행	await로 결과 획득
parallel(thunks[])	여러 태스크를 동시에 실행하고 모두 완료될 때까지 대기	배리어 동기화 (Barrier Synchronization)
pipeline(items, ...stages)	각 아이템을 스테이지 순서대로 처리 (배리어 없음)	스트림형 (Stream)
phase(title)	진행 상황 표시를 위한 페이즈 구분	표시 전용

pipeline()과 parallel()의 구분 사용이 중요합니다.

pipeline()에서는 item A의 stage 3가 실행되는 동안 item B는 아직 stage 1에 있을 수 있습니다. 각 아이템은 독립적으로 스테이지를 진행하므로, 가장 느린 아이템의 처리 시간이 전체 소요 시간(Wall-clock time)이 됩니다.

반면, parallel()은 배리어 동기화 방식입니다. 모든 태스크가 완료될 때까지 다음 처리로 넘어갈 수 없습니다.

// parallel()이 적절한 케이스: 모든 결과를 집계한 후 중복을 제거해야 할 때
const allFindings = await parallel(
dimensions.map(d => () => agent(d.prompt, { schema: FINDINGS }))
...

판단 기준: 다음 스테이지가 다른 아이템의 결과를 참조해야 한다면 parallel()을, 그렇지 않다면 pipeline()을 사용하십시오.

Workflows 실행 방법

세 가지 실행 방법이 있습니다.

# 방법 1: 프롬프트에 "ultracode" 포함하기
ultracode: src/routes/ 하위의 모든 API 엔드포인트에 대해 인증 체크 누락 여부 감사(audit)
# 방법 2: effort 레벨 설정 (세션 전체에 적용)
...

/effort ultracode를 설정하면, 세션 내의 모든 태스크에 대해 Claude가 Workflow 사용을 자동 판단합니다. 토큰 소비가 증가하므로, 대규모 태스크가 끝나면 /effort high로 되돌리는 것을 권장합니다.

Workflows 저장 및 재사용

한 번 실행한 Workflow를 저장하여 명령어로 재사용할 수 있습니다.

# 실행 중이거나 완료된 Workflow 저장
/workflows
# → 워크플로우를 선택하고 "s" 키를 누름
...

저장된 Workflow는 /<이름>으로 실행할 수 있으며, args 파라미터를 통해 입력을 전달할 수 있습니다.

제약 사항

제약	값	이유
동시 실행 에이전트 수	최대 16 (CPU 코어 수-2)	로컬 리소스의 상한
...	Date.now() 등 비결정적 함수	사용 불가

트레이드오프: Dynamic Workflows는 대량의 토큰을 소비합니다. 500개의 파일을 감사하기 위해 수백 개의 에이전트를 실행하면, 한 번의 실행으로 세션 수 시간 분량의 토큰을 사용할 수 있습니다. 먼저 작은 범위(1개 디렉토리, 1개 모듈)에서 테스트한 후 스케일 업(Scale-up)하십시오.

3개 층을 조합한 실전 파이프라인 설계하기

지금까지 소개한 세 가지 자동화 계층을 조합하여, 실제 개발 파이프라인을 구축하는 패턴을 살펴보겠습니다.

패턴 1: PR 품질 게이트 자동화

PR(Pull Request)의 라이프사이클 전체에 걸친 품질 체크를 자동화하는 구성입니다.

페이즈	사용하는 계층	처리 내용
코드 편집 시	Hooks (PostToolUse)	자동 포맷팅, lint 실행
PR 생성 시	Routines (GitHub Event)	자동 코드 리뷰, 보안 체크
복잡한 PR	Workflows (수동 실행)	다각도 리뷰 (보안, 성능, 테스트 커버리지)

{
"hooks": {
"PostToolUse": [
...

Routines 측에서는 GitHub Event 트리거를 통해 신규 PR에 대한 자동 리뷰를 설정합니다.

Review the pull request changes:
1. Security: Check for injection, auth bypass, data exposure
2. Performance: Flag N+1 queries, missing indexes, large payloads
...

패턴 2: 야간 배치 처리 파이프라인

매일 밤 코드베이스의 건전성을 체크하는 Routine 구성 예시입니다.

# Routine 프롬프트 (매일 밤 3시에 실행)
Check the repository health:
1. Review all open PRs - leave review comments if stale (>3 days)
...

이 Routine은 claude.ai/code/routines에서 생성하며, Schedule 트리거를 "Daily at 3:00 AM"으로 설정합니다.

패턴 3: 대규모 리팩터링을 위한 Workflow

레거시 코드를 단계적으로 리팩터링하는 데 Workflows를 활용하는 예시입니다.

export const meta = {
name: 'modernize-error-handling',
description: 'Replace callback-style error handling with async/await',
...

** isolation: 'worktree'**를 지정하면 각 에이전트가 독립된 Git worktree에서 작업하므로, 병렬로 파일을 편집해도 충돌이 발생하지 않습니다. 단, worktree 설정에 200~500ms의 오버헤드가 발생하므로 파일을 변경하지 않는 작업(읽기 전용 분석)에는 사용하지 마세요.

자주 발생하는 문제 및 해결 방법

문제	원인	해결 방법
Hook이 실행되지 않음	settings.json의 JSON 포맷 오류	jq . .claude/settings.json으로 구문 체크
/schedule이 "Unknown command"로 표시됨	API key 인증을 사용 중임	ANTHROPIC_API_KEY를 삭제하고 claude.ai 로그인으로 전환
Workflow가 중간에 중단됨	토큰 한도(Token limit) 도달	/workflows로 진행 상황 확인 후, 더 작은 범위(Scope)로 재실행
Routine의 네트워크 오류	허용 도메인 리스트에 호스트가 없음	환경 설정의 "Allowed domains"에 도메인 추가
Hook의 command 내에서 인용 부호(Quote) 오류	JSON 내의 싱글 쿼트(Single quote) 사용	외부 스크립트 파일로 분리하여 bash script.sh로 호출
Workflow에서 Date.now() 오류	비결정적 함수(Non-deterministic function) 사용 제한	args를 통해 타임스탬프를 전달하거나, Workflow 완료 후 추가

요약 및 다음 단계

요약:

• Claude Code의 자동화는 **Hooks(결정론적 규칙) · Routines(클라우드 정기 실행) · Dynamic Workflows(멀티 에이전트)**의 3개 계층으로 구성된다
• Hooks는 settings.json에 설정하는 것만으로 파일 편집 시 자동 포맷팅이나 커맨드 가드(Command guard)를 확실하게 실행할 수 있다
• Routines는 cron/GitHub 이벤트/API의 3가지 트리거를 통해 클라우드 상의 무인 실행을 실현하며, PR 리뷰나 배치 처리(Batch processing)에 적용할 수 있다
• Dynamic Workflows는 pipeline() / parallel() / agent()를 통해 최대 1,000개의 에이전트를 오케스트레이션(Orchestration)하여 대규모 코드베이스 조작에 대응한다
• 이 3개 계층은 독립적으로 사용할 수 있지만, 조합함으로써 PR 품질 게이트 → 야간 배치 → 대규모 리팩터링까지 커버하는 개발 파이프라인을 구축할 수 있다

다음에 할 일:

• 우선 Hooks부터 시작하기: .claude/settings.json에 PostToolUse 자동 포맷팅을 설정하고 1주일간 운영해 보기
• Routines 시도하기: claude.ai/code/routines에서 기존 리포지토리에 대한 PR 리뷰 Routine을 하나 생성하기
• Workflows는 범위를 좁혀서 테스트하기: ultracode: audit src/auth/ for security issues와 같이 하나의 디렉터리로 한정하여 실행하고 토큰 소비량을 확인하기

관련 기사

참고

• Automate actions with hooks - Claude Code Docs
• Hooks reference - Claude Code Docs
• Run prompts on a schedule - Claude Code Docs
• Automate work with routines - Claude Code Docs
• Orchestrate subagents at scale with dynamic workflows - Claude Code Docs
• Introducing dynamic workflows in Claude Code - Anthropic Blog
• Orchestrate teams of Claude Code sessions - Claude Code Docs

관련 심층 분석 기사

이 글에서 소개한 기술에 대해 더 깊이 있게 다룬 기사를 작성했습니다:

• Anthropic의 멀티 에이전트 리서치 시스템 설계 해설 - tech_blog 해설
• 장시간 가동 에이전트의 하네스 (Harness) 설계 패턴 해설 - tech_blog 해설
• Anthropic이 제창하는 효과적인 AI 에이전트 설계 패턴 해설 - tech_blog 해설
• 논문 해설: SWE-agent — ACI 설계에 의한 소프트웨어 엔지니어링 자동화 - arxiv 해설
• 논문 해설: ChatDev — 멀티 에이전트 협업에 의한 소프트웨어 개발 자동화 - arxiv 해설

Discussion