예약 작업과 헤드리스

예약 작업: 클라우드에서 실행되는 저장된 프롬프트

클라우드 예약 작업은 반복 작업을 자동화하는 가장 직접적인 방법입니다. 스크립트도 서버도 필요 없습니다. 클라우드 예약 작업은 프롬프트, 작업 대상 저장소, 필요한 커넥터라는 세 가지를 하나로 묶습니다. 그런 다음 트리거될 때마다 클라우드에서 그 묶음을 실행합니다.

핵심은 인프라가 Anthropic의 것이라는 점입니다. 밤새 켜 두어야 하는 여러분의 머신도 없고, 유지 관리해야 할 워크플로우 파일도 없습니다. 작업을 한 번 설명하면 그냥 실행됩니다.

예약 작업에 반드시 일정이 필요한 것은 아닙니다. 몇 가지 종류의 트리거로 실행될 수 있습니다:

• 매일 아침 9시와 같은 cron 일정.
• 여러분의 코드가 직접 실행할 수 있도록 API 엔드포인트로 보내는 HTTP POST.
• 새 풀 리퀘스트 생성과 같은 GitHub 이벤트.

반복되는 트리거에서 동일한 프롬프트로 실행되는 작업이라면 무엇이든 적합합니다. 아침 의존성 감사, 새 풀 리퀘스트가 들어올 때 실행되는 PR 분류기, 가장 시급한 것을 파악하기 위한 Sentry 티켓의 일일 스캔 등이 있습니다.

예약 작업이 하나로 묶는 것에 대한 멘탈 모델은 다음과 같습니다: 프롬프트, 저장소, 커넥터, 그리고 트리거입니다.

예약 작업을 만드는 두 가지 방법

claude.ai/code/routines에서 웹을 통해 예약 작업을 만들 수 있습니다. 이름을 지정하고, 각 세션에서 Claude가 수행해야 할 작업을 설명하는 지침을 작성하고, 저장소를 선택하고, 트리거를 선택합니다.

터미널을 벗어나지 않고 Claude Code 내부에서도 예약 작업을 만들 수 있습니다. /schedule 명령을 실행하고 원하는 내용을 평범한 언어로 설명하기만 하면 됩니다. 예를 들면:

어느 진입점을 선택하든 개념은 같습니다. 여러분의 작업 흐름에 맞는 쪽을 선택하세요.

클라우드 예약 작업에 의존하기 전에 알아야 할 세 가지

중요한 작업을 클라우드 예약 작업에 맡기기 전에, 다음 세 가지 제한 사항을 염두에 두세요.

• 클라우드 예약 작업은 리서치 프리뷰입니다. 동작과 제한 사항은 계속 변경될 수 있으므로, 변경되더라도 놀라지 마세요.
• 반복 일정은 최대 시간 단위로 실행됩니다. 더 자주 실행해야 한다면 클라우드 예약 작업은 적합한 도구가 아닙니다.
• 실행은 기본 브랜치의 새 클론에서 시작되어 claude/ 브랜치로 푸시됩니다. 단, 프롬프트에서 다른 브랜치를 지정한 경우는 예외입니다. GitHub 풀 리퀘스트 이벤트가 실행을 트리거하면, 해당 풀 리퀘스트의 저장소가 예약 작업의 첫 번째 저장소인 경우에 한해 풀 리퀘스트의 헤드 커밋에서 대신 시작됩니다. 실행이 푸시할 수 있는 브랜치를 제어하려면 GitHub의 브랜치 보호 규칙이나 룰셋을 사용하세요. GitHub는 이를 여러분이 연결한 GitHub 액세스에 적용하므로, 여러분의 액세스가 우회할 수 있는 규칙은 푸시를 막지 못합니다.

헤드리스 모드: 자신만의 환경이 필요할 때

작업을 Anthropic의 인프라에서 실행할 수 있을 때는 클라우드 예약 작업이 훌륭합니다. 하지만 때로는 작업에 여러분의 환경이 필요하거나, 실행을 감싸는 로직이 필요할 수 있습니다. 그럴 때 헤드리스 모드로 내려가게 되는데, 문서에서는 이제 이를 비대화형 모드(non-interactive mode)라고 부릅니다.

헤드리스 모드의 핵심은 -p 플래그(--print의 줄임말)입니다. 이는 대화형 UI 없이 Claude Code를 일회성 명령으로 실행합니다. 표준 입력을 읽고 표준 출력에 쓰기 때문에, 다른 셸 도구와 마찬가지로 파이프로 연결할 수 있습니다:

한 가지 알아둘 점은, -p만 단독으로 사용하면 훅(hooks), Skills, 플러그인, MCP 서버, CLAUDE.md 파일을 포함해 대화형 세션과 동일한 컨텍스트를 로드한다는 것입니다. 이 모든 것을 건너뛰려면 아래에서 다룰 --bare를 추가하세요.

구조화된 출력 받기

헤드리스 모드는 다른 셸 도구와 마찬가지로 파이프로 연결되기 때문에, 산문 대신 구조화된 데이터를 받고 싶은 경우가 많을 것입니다. JSON 스키마를 JSON 출력 형식과 함께 사용하면 Claude가 여러분의 스키마에 맞게 출력을 제한합니다.

스키마와 일치하는 객체는 JSON 응답의 structured_output 필드에 담깁니다. 따라서 jq 명령으로 이를 추출하여 데이터베이스나 다른 스크립트로 파이프할 수 있습니다:

claude -p "Extract the exported function names from src/core/style.js" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}' \
  | jq '.structured_output.functions'

이렇게 하면 다음 단계로 넘길 수 있는 깔끔한 배열을 얻을 수 있습니다.

세션을 활용한 다단계 자동화

여러 단계에 걸쳐 진행되는 작업의 경우, 모든 것을 하나의 명령에 욱여넣을 필요는 없습니다. JSON 출력에서 세션 ID를 캡처해 두었다가 나중에 재개할 수 있습니다:

한 스크립트가 작업을 시작합니다. 다른 스크립트가 나중에 전체 컨텍스트와 함께 이를 재개합니다. 첫 번째 단계에서 계획을 세우고 두 번째 단계에서 이를 실행하는 경우에 유용합니다.

CI를 위한 일관된 실행

CI가 모든 머신에서 동일한 설정을 필요로 할 때를 위해 만들어진 모드가 있습니다.

--bare 플래그는 훅, Skills, 플러그인, MCP 서버, CLAUDE.md 파일의 자동 검색을 건너뜁니다. Bash, 파일 읽기, 파일 편집 도구를 갖춘 Claude와, --settings나 --mcp-config 같은 플래그로 전달하는 모든 것을 얻게 됩니다. 따라서 모든 머신이 동일한 설정에서 시작하며, 시작 속도도 더 빠릅니다. Bare 모드는 여러분의 구독 로그인을 사용하지 않으므로, 먼저 ANTHROPIC_API_KEY를 설정하세요.

Agent SDK: 여러분의 앱 안에 있는 Claude Code

스펙트럼의 마지막 단계는 Agent SDK입니다. 이를 통해 여러분의 TypeScript 또는 Python 애플리케이션 안에 Claude Code를 내장하는 라이브러리를 얻을 수 있습니다.

두 언어 모두 query 함수와 CLI와 동일한 기본 요소(primitives)를 제공합니다. 프롬프트와 함께 다음과 같은 옵션을 전달합니다:

• Claude가 할 수 있는 작업을 제어하는 allowedTools,
• 시스템 프롬프트,
• 그리고 권한 모드.

그런 다음 Claude가 스트리밍으로 반환하는 메시지를 순회하며 여러분의 앱에 필요한 방식으로 처리합니다. CLI와 동일한 엔진이지만, 여러분의 제품 내부에서 호출할 수 있을 뿐입니다.

어떤 것을 선택해야 할까요?

빠른 결정 가이드는 다음과 같습니다:

• 클라우드 예약 작업은 반복 작업의 기본 선택지입니다. 여러분이 호스팅할 것 없이 Anthropic의 인프라에서 실행됩니다.
• -p를 사용한 헤드리스 모드는 작업에 여러분의 파이프라인이 필요하고 스크립트를 통해 데이터를 파이프하고 싶을 때 사용합니다.
• --bare는 CI가 모든 머신에서 동일한 설정을 필요로 할 때 사용합니다.
• Agent SDK는 작업이 여러분의 제품 내부에 속할 때 사용합니다.

클라우드 예약 작업부터 시작하세요. 작업에 추가적인 제어가 필요할 때만 스펙트럼을 따라 내려가세요.