DEV Community

Cover image for 클로드 워크플로우 자동화 방법
Rihpig
Rihpig

Posted on • Originally published at apidog.com

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

에이전트 코딩의 목표는 “더 나은 프롬프트”가 아니라 “당신이 지켜보지 않아도 실행되는 워크플로우”입니다. Claude를 채팅창처럼 쓰면 입력하고, 기다리고, 읽고, 다시 입력하는 패턴에 갇힙니다. 실제로 생산성을 끌어올리는 방식은 Claude가 일정이나 트리거에 따라 실행되고, 작업을 수행하고, 결과를 검증하고, 판단이 필요한 경우에만 사람에게 알리는 구조를 만드는 것입니다.

오늘 Apidog를 사용해 보세요

핵심 요약

당신 없이 실행되는 Claude 워크플로우에는 다음 다섯 가지가 필요합니다.

  1. 정밀한 사양
  2. 헤드리스 실행
  3. 확정적 검증 게이트
  4. 안전 장치
  5. 사람에게 넘기는 인계 절차

Claude Code의 헤드리스 모드(claude -p), Claude 에이전트 SDK, hooks, cron 또는 launchd 같은 스케줄러를 조합하면 이 구조를 만들 수 있습니다.

위험한 것은 에이전트 자체가 아닙니다. 게이트와 안전 장치 없이 에이전트를 방치하는 것이 위험합니다. 먼저 검증 가능한 시스템을 만든 다음 자동화하세요.

“당신 없이 실행”이 진짜 목표인 이유

감독된 채팅 방식의 병목은 사람입니다. 모델은 몇 초 만에 결과를 생성하지만, 다음 지시를 내리기 위해 사람이 출력을 읽고 판단하는 동안 워크플로우는 멈춥니다.

무인 워크플로우는 이 병목을 제거합니다.

  • 에이전트가 작업합니다.
  • 스크립트가 결과를 검증합니다.
  • 실패는 자동으로 다시 입력됩니다.
  • 사람은 마지막 승인이나 실패 처리에만 개입합니다.

이 방식의 장점은 단순한 속도가 아니라 병렬성입니다. 하나의 세션을 더 빠르게 조작하는 대신, 여러 워크플로우를 동시에 실행할 수 있습니다. 이는 Claude Code 동적 워크플로우에서 다룬 것처럼 하나의 세션을 여러 병렬 에이전트로 분산하는 접근과 같습니다.

다만 무인 실행은 위험도 키웁니다. 사람이 지켜보는 경우 잘못된 diff를 읽고 멈출 수 있지만, 무인 에이전트는 잘못된 변경을 커밋하고 다음 단계로 넘어갈 수 있습니다.

따라서 핵심은 프롬프트 작성이 아니라 시스템 설계입니다. 아무도 보고 있지 않을 때도 정확하고, 제한적이며, 관찰 가능한 실행 환경을 만들어야 합니다. Anthropic의 효과적인 에이전트 구축 글도 같은 관점을 제시합니다. 성능은 더 똑똑한 단일 프롬프트가 아니라 모델 주변의 환경과 제어 흐름에서 나옵니다.

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

아래 요소 중 하나라도 빠지면 워크플로우는 잘못된 작업을 자신 있게 수행하거나, 멈추지 않고 반복될 수 있습니다.

1. 정밀한 사양

에이전트가 매 실행마다 읽는 완료 조건입니다.

나쁜 예:

API 수정
Enter fullscreen mode Exit fullscreen mode

좋은 예:

POST /orders 엔드포인트는 201을 반환해야 한다.
요청 본문은 스키마에 따라 검증해야 한다.
필수 필드가 누락되면 422를 반환해야 한다.
Enter fullscreen mode Exit fullscreen mode

모호한 사양은 모호한 작업을 만듭니다. 무인 실행에서는 완료 조건을 사람이 추론해줄 수 없으므로 사양이 더 중요합니다.

2. 헤드리스 실행

Claude는 사람이 키보드 앞에 없어도 실행되어야 합니다. 즉, 채팅 UI가 아니라 비대화형 모드로 실행해야 합니다.

3. 검증 게이트

테스트, 타입 검사, 스키마 검증, 계약 테스트처럼 통과 또는 실패를 명확히 반환하는 검사입니다.

게이트는 모델의 “완료했습니다”라는 응답을 믿지 않고 실제 완료 여부를 판단합니다.

4. 안전 장치

무인 실행에는 다음 제한이 필요합니다.

  • 권한 허용 목록
  • 최대 반복 횟수
  • 비용 상한
  • 로깅
  • 킬 스위치
  • 격리된 작업 공간

5. 인계

워크플로우가 완료되거나 포기할 때 사람에게 알려야 합니다.

예:

  • 검토용 PR 생성
  • 실패 로그 알림
  • 마지막 검증 결과 전송

침묵은 성공이 아닙니다.

Claude 빌딩 블록

헤드리스 모드: claude -p

Claude Code의 print 모드는 프롬프트를 비대화형으로 실행하고 종료합니다. 무인 워크플로우의 기본 실행 단위로 사용할 수 있습니다.

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

여기서 중요한 것은 --allowedTools입니다.

채팅 UI에서는 사람이 각 작업을 승인할 수 있지만, 헤드리스 모드에서는 승인할 사람이 없습니다. 따라서 허용 목록이 에이전트가 접근할 수 있는 범위를 제한하는 핵심 장치입니다.

처음에는 최소 권한으로 시작하세요.

--allowedTools "Edit,Write"
Enter fullscreen mode Exit fullscreen mode

실행이 안정화된 뒤에만 필요한 도구를 추가합니다.

전체 옵션은 Claude Code 문서를 참고하세요.

Claude 에이전트 SDK

셸 명령만으로 충분하지 않다면 Claude 에이전트 SDK를 사용해 Python 또는 TypeScript에서 Claude를 프로그래밍 방식으로 제어할 수 있습니다.

SDK를 사용하면 다음을 코드로 관리할 수 있습니다.

  • 작업 입력
  • 메시지 스트리밍
  • 도구 호출 검사
  • 검증 결과 기반 재시도
  • 반복 횟수 제한
  • 실패 시 에스컬레이션

예시는 다음과 같습니다.

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;
}
Enter fullscreen mode Exit fullscreen mode

핵심은 “이전 실패 결과”를 다음 프롬프트에 넣어 에이전트를 다시 실행하는 루프입니다.

직접 루프를 구현할지, 관리형 옵션을 사용할지 고민 중이라면 관리형 에이전트와 에이전트 SDK 비교를 참고하세요.

Hooks로 확정적 안전 장치 만들기

Hooks는 Claude 실행 생명주기의 특정 지점에서 고정 명령을 실행합니다. 모델이 선택하는 것이 아니라 시스템이 강제로 실행하는 명령입니다.

예를 들어 모든 파일 편집 후 테스트를 실행하려면 PostToolUse hook을 사용할 수 있습니다.

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

이 방식의 장점은 에이전트가 테스트를 건너뛸 수 없다는 점입니다. 무인 실행에서는 이런 강제성이 중요합니다.

스케줄러로 실행 트리거하기

무인 워크플로우는 사람이 실행하지 않아도 시작되어야 합니다.

서버에서는 cron, macOS에서는 launchd를 사용할 수 있습니다.

예를 들어 평일 오전 7시에 유지보수 작업을 실행하려면 다음처럼 설정할 수 있습니다.

# 매주 평일 오전 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
Enter fullscreen mode Exit fullscreen mode

전체 구조는 다음과 같습니다.

  1. 스케줄러가 Claude를 헤드리스로 실행합니다.
  2. Claude가 사양을 읽고 작업합니다.
  3. hooks와 검증 게이트가 결과를 검사합니다.
  4. 로그와 알림이 실행 결과를 남깁니다.

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

무인 워크플로우를 만들 때 질문을 바꿔야 합니다.

나쁜 질문:

Claude에게 뭐라고 말해야 할까?
Enter fullscreen mode Exit fullscreen mode

좋은 질문:

어떤 루프가 Claude의 작업을 검증하고 다시 입력하게 만들까?
Enter fullscreen mode Exit fullscreen mode

에이전트는 빠르게 생성하지만, 자신의 결과가 맞는지 안정적으로 판단하지 못합니다. 판단은 외부 게이트가 해야 합니다.

이 관점은 코딩 에이전트에 프롬프트 제공을 멈추고 대신 루프를 구축하라에서 자세히 다룬 내용과 같습니다. 무인 작업에서는 모델의 확신보다 게이트의 판정이 중요합니다.

명확한 사양도 같은 이유로 중요합니다. design.md 또는 AGENTS.md 같은 파일에 의도, 제약 조건, 완료 정의를 작성해두면 매 실행마다 일관된 목표를 제공할 수 있습니다. 관련 내용은 design.md 또는 AGENTS.md 파일을 참고하세요.

실전 예시: 무인 API 유지보수 워크플로우

OpenAPI 사양과 구현을 매일 동기화하고, 결함 있는 엔드포인트를 배포하지 않는 워크플로우를 만든다고 가정해보겠습니다.

구조는 다음과 같습니다.

1. 사양 준비

계약은 OpenAPI 파일에 둡니다. 동작은 테스트 케이스에 둡니다.

에이전트는 실행 시작 시 둘 다 읽습니다.

- openapi.yaml을 기준으로 엔드포인트 계약을 확인한다.
- tests/api 디렉터리의 테스트를 통과해야 한다.
- 테스트 파일은 수정하지 않는다.
Enter fullscreen mode Exit fullscreen mode

2. 트리거 설정

cron이 매일 오전 7시에 Claude를 실행합니다.

0 7 * * 1-5 cd /srv/api && claude -p "$(cat tasks/api-maintenance.md)" \
  --allowedTools "Edit,Write,Bash" \
  --output-format json >> logs/api-maintenance-$(date +\%F).log 2>&1
Enter fullscreen mode Exit fullscreen mode

3. 생성 작업

에이전트는 구현과 사양을 맞춥니다.

예:

  • 누락된 엔드포인트 추가
  • 응답 필드 형식 수정
  • 요청 검증 강화
  • 상태 코드 불일치 수정

4. 검증 게이트 실행

워크플로우는 실행 중인 서비스에 대해 API 테스트를 수행합니다.

검증 항목은 다음과 같습니다.

  • HTTP 상태 코드
  • JSON 스키마 검증
  • OpenAPI 계약 준수
  • 필수 필드 누락 처리
  • 오류 응답 형식

실패는 구조화해서 반환해야 합니다.

POST /orders
예상: customer_id 누락 시 422
실제: 500

GET /orders/{id}
예상: total 필드는 number
실제: string
Enter fullscreen mode Exit fullscreen mode

이 실패 결과가 다음 반복의 입력이 됩니다.

5. 루프 또는 에스컬레이션

검증이 실패하면 에이전트가 다시 실행됩니다.

const result = runApiTests();

if (!result.passed) {
  feedback = result.failures;
  // 다음 Claude 실행에 feedback 전달
}
Enter fullscreen mode Exit fullscreen mode

반복 상한에 도달하면 멈추고 사람에게 알립니다.

API 유지보수 워크플로우 실패
시도 횟수: 8
마지막 실패:
- POST /orders: customer_id 누락 시 422 예상, 500 반환
Enter fullscreen mode Exit fullscreen mode

6. 인계

게이트가 통과하면 자동 배포가 아니라 검토용 PR을 만듭니다.

무인 실행의 목표는 “사람 없이 프로덕션 반영”이 아니라 “사람이 검토할 수 있는 검증된 변경 생성”입니다.

API 워크플로우에서는 4단계의 게이트가 핵심입니다. 게이트가 없으면 에이전트는 자체 판단으로 코드를 편집하고 성공을 보고합니다. 이는 결함 있는 엔드포인트가 프로덕션에 들어가는 전형적인 경로입니다.

Apidog는 이 지점에서 유용합니다. API 설계, 스키마, 목(mock) 서버, 자동화된 테스트를 하나의 워크스페이스에서 관리할 수 있으므로, 사양과 게이트를 같은 흐름 안에 둘 수 있습니다.

Apidog 테스트 시나리오를 실행 게이트로 연결하면 에이전트는 매 반복마다 스키마 검증을 거친 통과/실패 결과를 받을 수 있습니다. 목 서버는 불안정한 외부 의존성을 대체할 수 있어 새벽 실행이 타사 서비스 대기로 막히는 상황을 줄입니다.

엔드포인트 호출과 검사를 에이전트 흐름에 연결하고 싶다면 Apidog AI 에이전트 디버거를 참고하세요. 수동 러너를 작성하는 대신 시각적으로 게이트를 구성하고 싶다면 Apidog를 다운로드할 수 있습니다.

Apidog API workflow

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

무인 에이전트에는 좋은 의도가 아니라 강한 제한이 필요합니다.

좁은 권한 허용 목록 사용

헤드리스 모드에서는 허용 목록이 에이전트 권한의 핵심 게이트입니다.

작업에 필요한 최소 도구만 허용하세요.

--allowedTools "Edit,Write"
Enter fullscreen mode Exit fullscreen mode

무인 실행에 샌드박스 없는 무제한 셸 권한을 주지 마세요.

반복 횟수 제한

루프에는 항상 상한이 있어야 합니다.

const MAX_ITERATIONS = 8;
Enter fullscreen mode Exit fullscreen mode

N번의 시도 안에 게이트를 통과하지 못하면 계속 반복하지 말고 중단하고 에스컬레이션해야 합니다.

비용 상한 설정

무인 루프는 사람이 인지하지 못하는 사이 토큰을 소비할 수 있습니다.

실행마다 다음을 기록하세요.

  • 입력 토큰
  • 출력 토큰
  • 실행 시간
  • 모델 비용
  • 반복 횟수

수렴하지 않는 루프는 비용 상한에 도달하면 중단해야 합니다. 관련해서는 에이전트 토큰 비용 절감을 참고하세요.

게이트 보호

에이전트가 테스트 파일이나 사양 파일을 마음대로 수정할 수 있으면 게이트가 의미 없어집니다.

예를 들어 다음 파일은 읽기 전용으로 취급하는 것이 좋습니다.

openapi.yaml
tests/**
contracts/**
Enter fullscreen mode Exit fullscreen mode

에이전트가 테스트를 통과하도록 테스트 자체를 바꿀 수 있다면, 실제 진척이 아니라 통과한 것처럼 보이는 결과만 만들게 됩니다.

샌드박스에서 실행

무인 작업은 주 환경이 아니라 격리된 작업 공간에서 실행하세요.

사용 가능한 방식:

  • 임시 브랜치
  • git worktree
  • 컨테이너
  • 별도 CI 작업 공간

잘못된 실행의 영향 범위를 제한해야 합니다.

로깅과 킬 스위치 준비

모든 실행은 로그로 남겨야 합니다.

>> logs/run-$(date +\%F).log 2>&1
Enter fullscreen mode Exit fullscreen mode

또한 실행 중인 작업을 중단할 수 있는 방법이 있어야 합니다.

로그가 없으면 디버깅할 수 없고, 킬 스위치가 없으면 잘못된 루프를 멈추기 어렵습니다.

사람 승인은 가장자리에 배치

“당신 없이 실행”은 “영원히 아무 승인 없이 실행”을 의미하지 않습니다.

사람은 내부 반복이 아니라 워크플로우의 시작 또는 끝에 배치하는 것이 좋습니다.

예:

  • 시작 시 작업 승인
  • 끝에서 PR 승인
  • 실패 시 수동 판단

도구 연결 패턴과 실패 모드는 에이전트 워크플로우 도구 와이어링에서 다룬 내용과 맞닿아 있습니다.

흔한 실수

게이트 없이 에이전트 응답만 믿기

유일한 검사가 다음과 같다면 워크플로우가 아닙니다.

완료했나요?
Enter fullscreen mode Exit fullscreen mode

에이전트 외부의 테스트, 타입 검사, 계약 검증이 필요합니다.

너무 큰 작업을 한 번에 실행하기

나쁜 예:

전체 서비스를 유지보수하라
Enter fullscreen mode Exit fullscreen mode

좋은 예:

POST /orders 엔드포인트의 요청 검증과 응답 스키마를 OpenAPI 사양에 맞춰라
Enter fullscreen mode Exit fullscreen mode

큰 실행은 수렴하기 어렵습니다. 엔드포인트 단위, 기능 단위, 파일 단위로 나누세요.

권한을 너무 넓게 주기

편하다는 이유로 모든 도구를 허용하면 작은 버그가 큰 사고가 됩니다.

무인 실행에서는 최소 권한이 기본값이어야 합니다.

성공과 실패를 조용히 처리하기

알림 없이 커밋하거나, 실패했는데 아무에게도 알리지 않는 워크플로우는 위험합니다.

항상 다음 중 하나를 남기세요.

  • PR
  • 실패 보고서
  • 로그 링크
  • 검증 결과

모델의 자체 보고를 신뢰하기

에이전트는 완료했다고 말할 수 있습니다. 하지만 완료 여부는 게이트가 판단해야 합니다.

완료된 것처럼 보임
Enter fullscreen mode Exit fullscreen mode

과

검증을 통과함
Enter fullscreen mode Exit fullscreen mode

은 다릅니다.

무인 실행에서는 이 차이를 사람이 즉시 발견해주지 않습니다.

더 깊은 구조가 필요하다면 에이전트 하네스 설계를 참고하세요.

결론

당신 없이 실행되는 Claude 워크플로우를 만드는 핵심은 Claude 자체가 아니라 Claude 주변의 시스템입니다.

필요한 구성은 명확합니다.

  1. 정밀한 사양
  2. 헤드리스 실행
  3. 확정적 검증 게이트
  4. 강력한 안전 장치
  5. 명확한 인계 절차

처음부터 큰 자동화를 만들 필요는 없습니다. 하나의 워크플로우로 시작하세요.

실행 순서는 다음과 같습니다.

  1. 엄격한 사양을 작성합니다.
  2. claude -p로 헤드리스 실행합니다.
  3. 테스트 또는 계약 검증 게이트를 붙입니다.
  4. 도구 권한을 최소화합니다.
  5. 반복 횟수와 비용을 제한합니다.
  6. 격리된 작업 공간에서 실행합니다.
  7. 완료 또는 실패 시 알림을 보냅니다.

API 작업에서는 테스트 스위트가 무인 실행을 안전하게 만드는 핵심 게이트입니다. Apidog는 API 설계, 목(mocking), 자동화된 테스트를 하나의 워크스페이스에서 제공하므로 이 게이트를 구성하는 데 사용할 수 있습니다.

다운로드해서 검증 게이트를 연결하고, 당신이 다른 일을 하는 동안 워크플로우가 제한된 범위 안에서 작업하게 만드세요.

Top comments (0)