클로드 워크플로우 자동화 방법

에이전트 코딩이 나아갈 방향을 요약하는 문구가 있습니다. 목표는 더 나은 프롬프트가 아니라, 당신이 지켜보지 않아도 실행되는 워크플로우입니다. 대부분의 사람들은 채팅창을 사용하듯이 Claude를 사용합니다. 입력하고, 기다리고, 읽고, 다시 입력하죠. 이는 작동하지만, 당신이 적극적으로 보살피는 하나의 에이전트로만 결과물이 제한됩니다. Claude에서 진정한 이점을 얻는 엔지니어들은 다른 것을 만들었습니다. 즉, 정해진 일정이나 트리거에 따라 시작되어 작업을 수행하고, 자체 결과를 확인하며, 결정이 필요할 때만 사람에게 알림을 보내는 워크플로우 말입니다.

앱 다운로드

핵심 요약

당신 없이 실행되는 Claude 워크플로우에는 다섯 가지 요소가 필요합니다. 정밀하게 작성된 사양, 헤드리스(비대화형) 실행, 성공 또는 실패를 결정하는 확정적 검증 게이트, 강력한 안전 장치(권한 허용 목록, 제한된 반복, 비용 상한, 킬 스위치), 그리고 사람에게 알리거나 실패 시 에스컬레이션하는 인계 절차입니다. Claude Code의 헤드리스 모드(claude -p), Claude 에이전트 SDK, 훅(hooks), 그리고 스케줄러(cron 또는 launchd)는 이 다섯 가지를 모두 제공합니다. 에이전트 자체가 위험한 부분이 아닙니다. 게이트와 안전 장치 없이 에이전트를 방치하는 것이 위험합니다. 먼저 이들을 구축한 다음 손을 떼세요.

"당신 없이 실행"이 진정한 목표인 이유

감독된 채팅에는 명확한 한계가 있습니다: 바로 당신입니다. 모든 반복은 사람이 출력을 읽고 다음 단계를 결정하기를 기다립니다. 모델은 몇 초 만에 생성하지만, 당신이 컨텍스트를 전환하는 동안 몇 분 동안 유휴 상태에 있습니다. 당신은 다른 부분은 빠른 시스템에서 병목 현상입니다.

무인 워크플로우는 그 한계를 제거합니다. 에이전트가 작동하고, 스크립트가 이를 확인하며, 실패는 자동으로 다시 라우팅되고, 당신은 가장자리에서만 개입합니다. 그 보상은 속도뿐만이 아닙니다. 병렬성입니다. 워크플로우가 감독 없이 실행되면, 더 빨리 입력하는 것이 아니라 워크플로우를 추가함으로써 확장할 수 있습니다. 이는 우리가 Claude Code 동적 워크플로우에서 다루었던 것과 동일한 도약입니다. 한 세션이 여러 병렬 에이전트로 분산되는 것이죠.

하지만 "당신 없이 실행"은 위험을 증가시킵니다. 잘못된 편집을 하는 감독된 에이전트는 당신이 diff를 읽을 때 발견됩니다. 무인 에이전트는 이를 커밋하고 다음 단계를 실행하며 계속 진행합니다. 따라서 훈련은 프롬프트 작성에서 시스템 설계로 바뀝니다. 아무도 보지 않을 때 정확하고, 제한적이며, 관찰 가능한 기계를 구축하는 것입니다. Anthropic의 효과적인 에이전트 구축에 대한 글도 같은 주장을 합니다. 영향력은 모델 주변 환경에서 나오며, 더 똑똑한 단일 메시지에서 나오는 것이 아닙니다.

모든 무인 워크플로우에 필요한 다섯 가지 요소

이 중 하나라도 건너뛰면 워크플로우는 자신 있게 잘못된 작업을 수행하거나 결코 멈추지 않을 것입니다.

정밀한 사양. 에이전트가 모든 실행 시작 시 읽는 완료 상태에 대한 서면 설명입니다. 모호한 사양은 모호한 작업을 생성합니다. "API 수정"은 실패하지만, "POST /orders 엔드포인트는 201을 반환하고, 스키마에 대해 본문을 유효성 검사하며, 누락된 필드를 422로 거부한다"는 성공합니다.
헤드리스 실행. Claude는 키보드에 사람이 없어도 실행되어야 합니다. 이는 채팅 UI가 아닌 비대화형 모드를 의미합니다.
검증 게이트. 테스트, 타입 검사, 스키마 유효성 검사, 계약 테스트 등 구체적인 이유와 함께 통과 또는 실패를 반환하는 확정적 검사입니다. 이것이 워크플로우가 모델의 말을 믿는 대신 실제로 완료되었는지 결정하게 합니다.
안전 장치. 권한 허용 목록, 최대 반복 횟수, 비용 상한선, 로깅, 킬 스위치입니다. 이것들은 당신이 잠든 동안 혼란스러운 실행이 손상을 입히는 것을 방지합니다.
인계. 워크플로우가 완료되거나 포기할 때, 누군가에게 알립니다. 알림, 검토를 위한 초안, 실패 경고입니다. 침묵은 성공이 아닙니다.

가운데 세 가지는 대부분의 설정이 취약한 부분입니다. Claude가 제공하는 도구를 사용하여 각각을 구축해 봅시다.

Claude 빌딩 블록

헤드리스 모드 (claude -p)

Claude Code의 프린트 모드는 프롬프트를 비대화형으로 실행하고 종료합니다. 이는 모든 무인 워크플로우의 기반입니다. 작업을 할당하고, 도구를 제한하며, 출력을 캡처한 다음 다음 단계로 넘어갑니다.

claude -p "spec.md에 따라 orders 엔드포인트를 구현한 다음, 테스트 스위트를 실행합니다" \
  --allowedTools "Edit,Write,Bash" \
  --output-format json \
  >> run.log 2>&1

--allowedTools 플래그는 보이는 것보다 더 중요합니다. 채팅 UI에서는 각 작업을 수동으로 승인합니다. 헤드리스 모드에서는 승인할 사람이 없으므로, 허용 목록이 에이전트가 접근할 수 있는 것을 제어하는 유일한 수단입니다. 처음에는 제한적으로 시작하고 실행을 신뢰할 때만 확장하세요. 전체 플래그 세트는 Claude Code 문서에 있습니다.

Claude 에이전트 SDK

셸 명령만으로는 충분하지 않을 때, Claude 에이전트 SDK를 사용하면 Python 또는 TypeScript에서 Claude를 프로그래밍 방식으로 제어할 수 있습니다. 코드로 루프를 얻을 수 있습니다. 작업을 보내고, 결과를 스트리밍하고, 도구 호출을 검사하고, 계속할지 여부를 결정합니다. 이것이 에이전트 주변에 실제 제어 흐름을 감싸는 방법입니다.

import { query } from "@anthropic-ai/claude-agent-sdk";

const MAX_ITERATIONS = 8;
let feedback = "";

for (let attempt = 0; attempt < MAX_ITERATIONS; attempt++) {
  for await (const msg of query({
    prompt: `${task}\n\nPrevious failures:\n${feedback}`,
    options: { allowedTools: ["Edit", "Write", "Bash"] },
  })) {
    // 에이전트가 작동하는 동안 메시지 스트리밍/로그
  }

  const gate = runVerification();      // 확정적 검사
  if (gate.passed) break;              // 완료
  feedback = gate.failures;            // 다음 프롬프트가 스스로 작성됨
}

정확한 서명은 문서에 있지만, 핵심은 지난 실패를 다음 프롬프트로 사용하여 에이전트를 재실행하는 루프입니다. 자체 루프를 구현할지 호스팅 옵션을 선택할지 고민 중이라면, 관리형 에이전트와 에이전트 SDK 비교에서 각각의 장단점을 자세히 설명합니다.

확정적 안전 장치를 위한 훅(Hooks)

훅은 Claude의 생명주기에서 모델이 개입하지 않고 고정된 지점에서 사용자 정의 명령을 실행합니다. 이는 에이전트가 피할 수 없는 규칙을 강제하는 방법입니다. 모든 파일 편집 후에 테스트 스위트를 실행하고 싶으신가요? PostToolUse 훅이 확정적으로 이를 수행합니다.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "npm test --silent" }]
      }
    ]
  }
}

훅은 모델에 대한 요청이 아닌 일반 코드이므로 항상 실행됩니다. 이는 무인 실행에서 안전 장치에 필요한 속성입니다. 에이전트는 이를 건너뛸 수 없습니다.

실행을 트리거하는 스케줄러

당신 없이 실행되는 워크플로우는 당신 없이 시작될 무언가가 필요합니다. 서버에서는 cron이고, Mac에서는 launchd입니다. 어느 쪽이든 정해진 일정에 따라 헤드리스 명령을 실행합니다.

# 매주 평일 오전 7시: 유지보수 워크플로우 실행, 모든 것을 로그에 기록
0 7 * * 1-5  cd /srv/api && claude -p "$(cat tasks/nightly-maintenance.md)" \
  --allowedTools "Edit,Bash" >> logs/run-$(date +\%F).log 2>&1

이것이 자율 설정의 전체 골격입니다. 스케줄러가 헤드리스 Claude를 실행하고, 에이전트가 사양에 따라 작동하며, 훅과 게이트가 정확성을 유지하고, 로그가 발생한 일을 알려줍니다.

프롬프트가 아닌 루프를 설계하라

모든 것을 연결하는 사고방식은 다음과 같습니다. "Claude에게 무엇을 말해야 할까?"라고 묻는 것을 멈추세요. 대신 "어떤 루프가 Claude가 스스로에게 말하게 만들까?"라고 묻기 시작하세요. 에이전트는 올바른지 여부를 신뢰할 수 있게 판단하는 감각이 없는 빠른 생성기입니다. 루프는 게이트를 통해 그 감각을 제공합니다. 우리는 코딩 에이전트에 프롬프트 제공을 멈추고 대신 루프를 구축하라에서 이에 대해 심도 있게 다루었으며, 이는 무인 작업에 있어 중요한 아이디어입니다. 모델의 자신감은 더 이상 중요하지 않고, 오직 게이트의 판결만이 중요합니다.

이것이 또한 명확한 사양이 똑똑한 프롬프트보다 더 나은 이유입니다. 동일한 사양은 모든 반복을 구동하고 문서 역할도 합니다. 의도, 제약 조건, 완료 정의를 담고 있는 design.md 또는 AGENTS.md 파일은 당신이 매번 컨텍스트를 다시 설명할 필요 없이 에이전트에게 모든 실행에서 안정적인 목표를 제공합니다.

실전 예시: 무인 API 유지보수

구체적으로 설명해 봅시다. OpenAPI 사양과 동기화되어 있으며, 매일 아침 실행되고, 결함 있는 엔드포인트를 절대 배포하지 않는 워크플로우를 원한다고 가정해 봅시다. 구조는 다음과 같습니다.

사양. 계약은 OpenAPI 파일에 있고, 동작은 테스트 케이스에 있습니다. 에이전트는 실행 시작 시 둘 다 읽습니다.
트리거. 오전 7시 cron 작업이 유지보수 작업을 통해 헤드리스 Claude를 실행합니다.
생성. 에이전트는 구현과 사양을 조화시킵니다: 누락된 엔드포인트를 추가하고, 불일치하는 응답 형태를 수정하며, 유효성 검사를 강화합니다.
게이트. 워크플로우는 실행 중인 서비스에 대해 API 테스트 스위트를 실행합니다. 상태 단언, 모든 응답에 대한 JSON 스키마 유효성 검사, 사양에 대한 계약 검사. 실패는 구조화되어 반환됩니다: "customer_id 누락 시 422 예상, 500 반환됨." "응답 필드 total은 문자열이지만, 스키마는 숫자라고 명시."
루프 또는 에스컬레이션. 빨간색 게이트인가요? 구조화된 실패는 다음 프롬프트가 되고 에이전트는 반복 상한까지 특정 격차를 패치합니다. 녹색인가요? 드래프트 PR을 엽니다. 시도 횟수를 초과했나요? 마지막 실패를 포함한 경고를 발행하고 멈춥니다.
인계. 사람은 검토할 깨끗한 PR 또는 정확한 실패 보고서를 받습니다. 절대 자동 커밋은 없습니다.

4단계의 게이트는 전체 시스템을 무인으로 실행해도 안전하게 만드는 요소입니다. 게이트가 없으면 에이전트가 자체 판단에 따라 코드를 편집하고 성공을 보고하게 되며, 이는 결함 있는 엔드포인트가 프로덕션에 도달하는 방식과 정확히 같습니다. Apidog가 자율 워크플로우에 적합한 지점이 바로 여기입니다. API 설계, 스키마, 목(mock) 서버, 자동화된 테스트가 하나의 워크스페이스에 존재하므로, 게이트와 사양이 기본적으로 동기화됩니다. 실행을 Apidog 테스트 시나리오에 연결하면 에이전트는 모든 반복에서 스키마 유효성 검사를 거친 통과/실패 결과를 얻습니다. 목 서버는 작동하지 않는 종속성을 대체하므로, 새벽 3시 실행이 불안정한 타사 서비스 대기로 인해 차단되지 않습니다. Apidog AI 에이전트 디버거를 통해 에이전트의 엔드포인트 접근을 연결하는 팀은 사람이 직접 테스트하는 것과 동일한 방식으로 엔드포인트를 호출하고 검사할 수 있습니다. 수동으로 러너를 작성하는 대신 시각적으로 게이트를 구축하고 싶다면 Apidog를 다운로드하세요.

무인 실행을 안전하게 만드는 안전 장치

이것은 밤새도록 신뢰할 수 있는 워크플로우와 새벽 3시에 당신을 깨우는 워크플로우를 구분하는 부분입니다. 감독되지 않는 에이전트에게는 좋은 의도가 아니라 엄격한 제한이 필요합니다.

좁은 권한 허용 목록. 헤드리스 모드에서 허용 목록은 에이전트가 할 수 있는 일에 대한 유일한 게이트입니다. 작업에 필요한 최소한의 도구만 부여하세요. 샌드박스 없이 무제한 셸 또는 파괴적인 명령을 무인 실행에 절대 넘겨주지 마십시오.
제한된 반복. 루프에 상한을 두세요. N번의 시도 내에 녹색 게이트에 도달할 수 없는 실행은 영원히 작동하는 대신 중단하고 에스컬레이션해야 합니다.
비용 상한. 무인 루프는 사람이 알아차리지 못하게 토큰을 소모합니다. 지출 한도를 설정하고 실행당 지출을 기록하세요. 수렴하지 않는 루프는 한도를 초과하여 중단되어야 합니다. 에이전트 토큰 비용 절감에 대한 우리의 내용은 여기에 직접 적용됩니다.
게이트 보호. 테스트 파일과 사양을 에이전트가 편집할 수 있는 파일 목록에서 제외하세요. 에이전트가 통과하도록 테스트를 다시 작성할 수 있다면, 당신은 진행 상황을 속이는 기계를 만든 것입니다.
샌드박스. 무인 작업을 주 환경이 아닌 격리된 작업 공간 또는 컨테이너에서 실행하세요. git worktree 또는 임시 브랜치는 잘못된 실행의 파급 효과를 제한합니다.
로깅 및 킬 스위치. 모든 실행을 실제로 읽는 로그에 기록하고, 작업이 진행 중일 때 중지할 수 있는 방법을 유지하세요. 기록하지 않은 것은 디버그할 수 없습니다.
가장자리에서의 사람 승인. "당신 없이"는 "아무도 없이, 영원히"를 의미하지 않습니다. 시작(작업 승인) 또는 끝(PR 승인)에 사람을 배치하되, 내부 루프에는 배치하지 마세요. 여기의 와이어링 패턴 및 실패 모드는 에이전트 워크플로우 도구 와이어링과 일치합니다.

이러한 대부분의 사항은 하나의 규칙으로 귀결됩니다: 무인 에이전트는 자신의 작업만 수행할 수 있어야 합니다. 도구를 제한하고, 루프에 상한을 두며, 작업 공간을 격리하고, 모든 실행을 관찰 가능하게 만드세요.

흔한 실수

몇 가지 패턴은 자율 워크플로우를 빠르게 침몰시킵니다.

게이트 없음, 그저 느낌만. 유일한 검사가 "에이전트, 완료했습니까?"라면, 워크플로우가 아니라 감독되지 않는 챗봇을 가지고 있는 것입니다. 게이트는 에이전트 외부에 있어야 합니다.
하나의 거대한 작업. "전체 서비스를 유지보수하라"는 지시를 받은 실행은 거의 수렴하지 않습니다. 각자 고유한 게이트를 가진 엔드포인트 크기의 작업으로 분해하세요. 작은 실행은 완료되지만, 큰 실행은 낭비됩니다.
광범위한 권한. 편리하다는 이유로 모든 도구를 부여하면 아무도 보지 않을 때 작은 버그가 큰 사고로 변질됩니다. 엄격하게 허용 목록을 사용하세요.
조용한 성공 또는 조용한 실패. 아무에게도 알리지 않고 커밋하거나, 경고 없이 죽는 워크플로우는 없는 것보다 나쁩니다. 항상 인계하세요.
모델의 자체 보고를 신뢰. 에이전트는 완료되었다고 말할 것입니다. 게이트가 완료 여부를 결정합니다. "완료된 것처럼 보임"과 "실제로 완료됨" 사이의 간극을 위해 구축하세요. 왜냐하면 무인 상태에서는 아무도 그것을 잡아낼 사람이 없기 때문입니다.

이것들을 제대로 갖추면 Claude 워크플로우는 커피를 마시기도 전에 하루치에 해당하는 제한되고 검증된 작업을 수행합니다. 잘못 갖추면 자신감 넘치지만 테스트되지 않은 코드 생성을 자동화하게 됩니다. 그 차이는 모델이 아니라 게이트와 안전 장치에 있습니다. 더 깊은 아키텍처를 원한다면, 에이전트 하네스 설계에 대한 우리의 분석에서 각 부분이 어떻게 대규모로 작동하는지 다룹니다.

결론

당신 없이 실행되는 Claude 워크플로우를 구축하는 것은 Claude 자체에 대한 것보다는 그 주변에 감싸는 시스템에 대한 것입니다. 다섯 가지 부분이 중요합니다: 정밀한 사양, 헤드리스 실행, 확정적 검증 게이트, 강력한 안전 장치, 그리고 깔끔한 인계 절차. 이들을 올바르게 갖추면 모델은 당신이 보지 않을 때에도 정확하고, 제한적이며, 관찰 가능한 기계 내부에서 빠른 작업자가 됩니다.

하나의 워크플로우로 시작하세요. 엄격한 사양을 작성하고, 빠른 검증 게이트에 대해 헤드리스로 실행하며, 도구를 허용 목록에 추가하고, 반복 횟수를 제한하고, 작업 공간을 격리하고, 완료 또는 실패 시 당신에게 알리도록 만드세요. API와 관련된 모든 것에 대해, 테스트 스위트는 무인 실행을 안전하게 만드는 게이트이며, Apidog는 설계, 목(mocking), 그리고 자동화된 테스트를 하나의 워크스페이스에서 제공하여 이를 구축할 수 있게 합니다. 다운로드하여 게이트를 연결하고, 당신이 다른 일을 하는 동안 워크플로우가 작업을 수행하게 하세요.