심층 학습 가이드
AI 작업 큐 가드레일
심층 학습 가이드

AI 작업 큐 가드레일

AI가 만든 background job과 queue worker가 중복 실행, retry 폭주, partial failure, poison message로 무너지지 않게 만드는 실전 VIBE 코딩 운영 루프

학습 유형

주제 심층 학습

핵심 주제

AI 백그라운드 작업 큐

키워드

VIBE 코딩 · 백그라운드 작업 · 작업 큐 · 운영 가드레일 · AI 코드 품질 · 비동기 처리

학습 개요

이 페이지에서 다루는 것

AI 백그라운드 작업 큐

한 번에 끝까지 읽으며 맥락을 쌓을 수 있도록 구성했습니다.

예상 학습 시간

15분

본문과 보조 자료(이미지·영상)를 포함한 대략적인 소요입니다.

학습 팁

섹션 순서대로 읽고, 필요한 부분만 다시 찾아보기

표·이미지·영상은 본문 흐름을 돕는 보조 설명입니다.

AI가 만든 기능은 버튼을 눌렀을 때 바로 끝나는 화면보다, 뒤에서 오래 도는 background job에서 더 자주 무너집니다. 메일 발송, 이미지 변환, 결제 후 정산, 크롤링, AI 요약, 데이터 마이그레이션, 알림 팬아웃처럼 시간이 걸리는 작업은 queue와 worker로 분리하는 순간 실패 모드가 늘어납니다. 같은 작업이 두 번 실행될 수 있고, 일부만 성공한 뒤 worker가 죽을 수 있으며, 외부 서비스의 rate limit 때문에 retry가 폭주할 수 있습니다.

초보자는 백그라운드 작업 큐를 “나중에 처리할 일을 줄 세워 두는 시스템”으로 이해하면 됩니다. 실무자는 여기서 한 걸음 더 나아가야 합니다. queue에 넣는 job payload, idempotency key, retry policy, exponential backoff, dead letter queue, visibility timeout, concurrency limit, checkpoint, partial failure 처리, poison message 격리, job state machine, observability, rollback criteria까지 명확히 정해야 합니다. 이 글은 AI에게 큐 기반 기능을 맡길 때 안전장치를 먼저 설계하고 테스트로 고정하는 VIBE 코딩 루프입니다.

핵심 결론

AI 백그라운드 작업 큐 가드레일의 결론은 간단합니다. “worker 하나 만들어서 돌려 줘”라고 시키지 말고 “중복 실행되어도 안전하고, 실패해도 재시도 폭주가 없고, 일부 성공을 추적할 수 있으며, 운영자가 멈추고 되돌릴 기준이 있는 job state machine을 만들어라”라고 요구해야 합니다. 큐는 비동기라서 사용자가 바로 실패를 보지 못합니다. 그래서 작은 누락이 몇 시간 뒤 대량 발송, 중복 과금, 데이터 누락, 영구 retry, 비용 폭증으로 커질 수 있습니다.

좋은 루프는 네 가지 질문으로 시작합니다. 첫째, 이 작업은 같은 입력으로 두 번 실행되어도 결과가 하나로 수렴하는가. 둘째, worker가 중간에 죽었을 때 어디서부터 replay할 수 있는가. 셋째, 실패가 반복될 때 retry policy와 dead letter queue가 사람에게 문제를 넘기는가. 넷째, 배포 후 어떤 지표가 rollback criteria를 넘으면 즉시 멈출 것인가. 이 네 가지가 답되지 않으면 AI가 만든 queue 코드는 데모는 되어도 제품 운영에는 부족합니다.

VIBE 코딩에서 사람의 역할은 모든 worker 코드를 직접 쓰는 것이 아닙니다. 사람이 정해야 할 것은 작업의 안전 계약입니다. job payload에 어떤 식별자가 들어가야 하는지, deduplication은 어디서 할지, concurrency limit은 얼마인지, visibility timeout은 처리 시간보다 얼마나 길어야 하는지, poison message는 몇 번 실패 후 격리할지, observability에는 어떤 카운터와 trace가 있어야 하는지 정해야 합니다. 그런 뒤 AI가 구현한 코드를 테스트와 운영 스모크로 검증합니다.

왜 중요한가

큐 버그는 사용자가 늦게 발견한다

화면 오류는 사용자가 즉시 보고합니다. 반면 background job 오류는 몇 시간 뒤에야 드러납니다. 예를 들어 가입 환영 메일 worker가 10분 동안 멈춰도 화면은 정상처럼 보입니다. AI 요약 worker가 같은 문서를 두 번 처리해 비용을 두 배로 써도 사용자는 모를 수 있습니다. 정산 job이 partial failure 후 checkpoint 없이 재시작되면 일부 거래는 누락되고 일부는 중복 처리됩니다. 큐는 실패가 늦게 보이는 구조이기 때문에 처음부터 관측 가능성과 정지 기준을 넣어야 합니다.

이 늦은 발견은 AI 코딩과 특히 잘 맞물려 위험해집니다. AI는 happy path를 빠르게 만듭니다. queue에 넣고, worker가 꺼내고, 성공하면 done으로 바꾸는 코드는 쉽게 생성합니다. 하지만 visibility timeout이 처리 시간보다 짧으면 같은 job이 두 worker에서 동시에 실행될 수 있다는 점, retry가 외부 rate limit을 악화할 수 있다는 점, 중간 성공 후 실패하면 다음 replay가 중복 부작용을 만들 수 있다는 점은 프롬프트에 없으면 빠뜨리기 쉽습니다.

비동기 시스템은 “성공”의 정의가 여러 단계다

동기 API는 대체로 요청 하나와 응답 하나로 끝납니다. background job은 enqueue 성공, worker pick 성공, 외부 호출 성공, 상태 저장 성공, 후속 알림 성공, 최종 완료 기록까지 여러 단계가 있습니다. 어느 단계까지 성공했는지 모르면 재시도와 복구를 안전하게 설계할 수 없습니다. 그래서 job state machine이 필요합니다. queued, running, waiting_retry, succeeded, failed, dead_lettered, canceled 같은 상태가 있어야 작업의 현재 위치를 설명할 수 있습니다.

상태가 없으면 운영자는 로그를 뒤져야 합니다. 상태가 있으면 “지난 15분 동안 waiting_retry가 200건으로 늘었고 dead letter queue에 같은 poison message 유형이 쌓였다”처럼 제품 언어로 문제를 볼 수 있습니다. AI에게도 같은 기준을 줄 수 있습니다. “실패하면 그냥 다시 시도”가 아니라 “재시도 가능한 오류와 불가능한 오류를 나누고, retry policy를 넘으면 dead letter queue로 이동시키며, 상태 전이를 테스트하라”라고 지시할 수 있습니다.

비용과 신뢰는 retry에서 무너진다

큐 기반 작업의 가장 흔한 운영 사고는 retry 폭주입니다. 외부 서비스가 느려졌는데 모든 worker가 즉시 재시도하면 rate limit을 더 빨리 소모하고 장애를 키웁니다. AI 호출이 포함된 작업이라면 비용도 급격히 늘어납니다. 메일, 메시지, 결제, 포인트 지급처럼 외부 부작용이 있는 작업은 중복 실행이 곧 신뢰 손상입니다. “한 번 더 보내면 되겠지”가 아니라 “중복 부작용 없이 replay 가능한가”가 핵심 질문입니다.

idempotency key와 deduplication은 이 문제를 줄이는 기본 장치입니다. 같은 사용자의 같은 이벤트를 처리할 때 job id와 비즈니스 id를 분리하고, 외부 호출 전후에 처리 기록을 남기며, 이미 완료된 단계는 다시 실행하지 않아야 합니다. AI에게는 이 구조를 명시적으로 요구해야 합니다. 그렇지 않으면 AI는 try-catch와 단순 retry loop만 만들고, 실제 제품에서 가장 중요한 중복 방지와 정산 가능성을 놓칠 수 있습니다.

실제 작업 순서

1단계: 작업을 큐에 넣어야 하는 이유를 먼저 쓴다

모든 느린 작업이 queue를 필요로 하는 것은 아닙니다. 사용자가 즉시 결과를 기다려야 하는 검색, 짧은 검증, 단순 저장은 동기 처리로 충분할 수 있습니다. queue는 오래 걸리거나 실패해도 나중에 복구할 수 있거나, 외부 서비스의 처리량 제한을 맞춰야 하거나, 여러 작업을 순서대로 분산해야 할 때 씁니다. 먼저 “왜 background job인가”를 문장으로 씁니다. 이 문장이 없으면 AI는 불필요한 복잡성을 만들거나 반대로 필요한 비동기 경계를 생략합니다.

좋은 작업 정의는 입력, 출력, 부작용, 허용 지연, 실패 허용 범위를 포함합니다. 예를 들어 “사용자가 문서를 올리면 5분 안에 AI 요약을 만들고, 같은 문서는 동시에 한 번만 처리하며, 실패 시 최대 5회 retry 후 dead letter queue로 보내고, 사용자는 처리 중 상태를 볼 수 있어야 한다”처럼 씁니다. 이 한 문장이 queue 설계의 acceptance criteria가 됩니다.

2단계: job payload를 작고 재현 가능하게 만든다

AI가 자주 만드는 나쁜 payload는 화면 상태 전체나 큰 본문을 그대로 queue에 넣는 방식입니다. payload가 커지면 저장 비용이 늘고, 오래된 데이터가 섞이고, 개인정보나 민감한 문맥이 불필요하게 복제될 수 있습니다. 안전한 payload는 job type, job id, 비즈니스 id, idempotency key, 생성 시각, attempt 수, 필요한 최소 파라미터만 담습니다. 실제 데이터는 worker가 처리 시점에 다시 읽고 권한과 상태를 확인하는 편이 안전합니다.

payload에는 재현 가능성이 있어야 합니다. 같은 payload를 테스트 환경에서 replay했을 때 같은 단계로 이동해야 합니다. 시간이 필요한 작업은 현재 시각을 직접 읽기보다 주입 가능한 clock을 쓰거나 기준 시각을 payload 또는 작업 컨텍스트에 기록합니다. 외부 호출이 필요한 작업은 fixture와 fake adapter로 테스트합니다. 이렇게 해야 AI가 코드를 바꿔도 기존 job을 다시 처리할 수 있는지 contract test로 확인할 수 있습니다.

3단계: idempotency key와 deduplication 위치를 정한다

idempotency key는 “이 작업은 논리적으로 같은 작업이다”를 나타내는 키입니다. 사용자가 같은 파일을 두 번 업로드했는지, 결제 완료 이벤트가 재전송되었는지, 같은 알림을 두 번 보내려는지 판단할 때 씁니다. deduplication은 queue에 넣기 전, worker 시작 전, 외부 부작용 직전 세 지점에서 검토해야 합니다. 한 곳만 믿으면 race condition에서 깨질 수 있습니다.

실무 기준은 다음과 같습니다. enqueue 단계에서는 같은 비즈니스 이벤트의 중복 job 생성을 줄입니다. worker 단계에서는 이미 succeeded인 job이면 즉시 종료합니다. 외부 부작용 직전에는 발송 기록, 정산 기록, 생성 기록처럼 부작용별 idempotency key를 확인합니다. AI에게 “중복 방지 추가”라고만 말하면 한 단계만 구현할 가능성이 큽니다. “enqueue, worker start, side-effect boundary 세 단계에서 deduplication을 검증하라”라고 구체적으로 지시해야 합니다.

4단계: retry policy를 오류 종류별로 나눈다

모든 실패가 retry 대상은 아닙니다. 네트워크 타임아웃, 일시적 503, 외부 rate limit은 retry할 수 있습니다. 잘못된 payload, 권한 없음, 삭제된 리소스, 검증 실패는 retry해도 성공하지 않습니다. retry policy는 오류를 transient, permanent, manual_review로 나누고, transient에만 exponential backoff와 최대 attempt를 적용해야 합니다.

exponential backoff는 retry 간격을 점점 늘려 장애 확산을 막습니다. 여기에 jitter를 더하면 많은 worker가 같은 시각에 동시에 재시도하는 현상을 줄일 수 있습니다. rate limit이 있는 외부 서비스라면 응답의 재시도 가능 시각을 존중해야 합니다. AI에게 이 부분을 맡길 때는 “실패하면 3번 재시도”가 아니라 “transient 오류만 최대 5회, exponential backoff와 jitter, rate limit 응답 우선, permanent 오류는 즉시 failed”처럼 정책을 적어야 합니다.

5단계: visibility timeout과 concurrency limit을 숫자로 정한다

visibility timeout은 worker가 job을 가져간 뒤 일정 시간 동안 다른 worker에게 보이지 않게 하는 장치입니다. 너무 짧으면 긴 작업이 아직 처리 중인데 다른 worker가 같은 job을 가져갑니다. 너무 길면 worker가 죽었을 때 복구가 늦어집니다. 처리 시간의 p95 또는 p99를 기준으로 잡고, 장기 작업은 heartbeat나 checkpoint로 진행 중임을 갱신해야 합니다.

concurrency limit은 동시에 몇 개의 job을 처리할지 정하는 값입니다. 데이터베이스, 외부 API, AI 모델, 메일 제공자, 파일 저장소의 처리량보다 worker가 빨라지면 시스템 전체가 흔들립니다. 초기에 넉넉한 worker 수를 열기보다 작은 수에서 시작하고, 처리 시간, 실패율, 대기열 길이, 외부 rate limit 사용량을 보며 늘립니다. 이 값은 코드 상수 하나가 아니라 운영 기준입니다. 테스트에는 “동시에 같은 idempotency key를 처리해도 하나만 성공한다” 같은 race 조건을 넣습니다.

6단계: checkpoint와 partial failure 복구를 설계한다

긴 작업은 한 번에 성공하거나 실패하지 않습니다. 1,000명에게 알림을 보내는 job은 723명까지 성공하고 724번째에서 실패할 수 있습니다. 문서 변환은 파일 다운로드는 성공했지만 AI 요약에서 실패할 수 있습니다. 이런 partial failure를 모르면 replay가 중복 발송이나 누락을 만듭니다. checkpoint는 어떤 단계를 완료했는지 저장하는 기록입니다.

checkpoint는 너무 세밀해도 복잡하고, 너무 거칠어도 복구가 어렵습니다. 외부 부작용이 있는 경계마다 저장하는 것이 기본입니다. 메일 발송, 포인트 지급, 파일 생성, 알림 생성, 외부 호출 완료처럼 되돌리기 어려운 단계가 checkpoint 후보입니다. AI에게는 “작업 단계를 나누고, 각 단계가 이미 완료된 경우 건너뛰며, replay 시 완료된 부작용을 반복하지 않게 하라”라고 요구합니다.

7단계: dead letter queue와 poison message 대응을 만든다

poison message는 몇 번을 재시도해도 worker를 계속 실패시키는 job입니다. 잘못된 입력, 삭제된 리소스, 예상하지 못한 데이터 조합, 코드 버그가 원인일 수 있습니다. poison message를 일반 queue에 계속 두면 worker 처리량을 먹고 장애를 숨깁니다. dead letter queue는 이런 job을 격리해 사람이 원인을 볼 수 있게 합니다.

dead letter queue에 들어간 job은 “실패한 쓰레기통”이 아니라 운영 대기열입니다. 어떤 오류 코드로, 몇 번째 attempt에서, 마지막으로 어떤 단계에서 실패했는지 기록해야 합니다. 재처리 버튼을 만들더라도 모든 job을 무작정 replay하지 말고, 수정된 코드 버전, payload 검증, 영향 범위 확인 후 제한적으로 replay해야 합니다. AI가 관리자 화면까지 만들 때는 공개 페이지와 분리하고, 일반 사용자에게 내부 상태나 조작 UI가 보이지 않게 해야 합니다.

8단계: observability와 rollback criteria를 먼저 연결한다

큐 기능은 “테스트 통과”만으로 운영 준비가 끝나지 않습니다. enqueue 수, succeeded 수, failed 수, retrying 수, dead letter queue 수, 평균 처리 시간, p95 처리 시간, queue lag, attempt 분포, 외부 rate limit 응답, 비용 지표를 봐야 합니다. 로그는 job id, job type, state transition, attempt, 오류 분류, checkpoint 이름을 포함하되, 민감한 payload 자체를 그대로 남기지 않습니다.

rollback criteria는 배포 전에 숫자로 정합니다. 예를 들어 “15분 동안 dead letter queue가 20건 이상”, “retrying 비율이 10% 초과”, “queue lag가 30분 초과”, “같은 idempotency key 중복 성공 1건 이상”, “외부 서비스 rate limit 오류가 평소의 3배”처럼 씁니다. 기준이 없으면 장애 중에 논쟁이 길어집니다. 기준이 있으면 worker를 멈추거나 이전 버전으로 되돌리거나 concurrency limit을 낮추는 결정을 빠르게 할 수 있습니다.

상황별 예시

예시 A: AI 요약 worker

문서 요약 기능은 queue가 잘 맞는 대표 사례입니다. 사용자는 파일을 올리고 바로 결과를 기다리지 않아도 됩니다. 하지만 같은 문서가 중복 처리되면 AI 비용이 늘고 결과가 서로 덮어써질 수 있습니다. payload에는 documentId, requestedBy, summaryType, idempotency key, createdAt 정도만 넣고 본문은 worker가 저장소에서 다시 읽습니다. 문서가 삭제되었으면 permanent failure로 종료하고, AI 호출 타임아웃은 transient로 분류해 retry policy를 적용합니다.

checkpoint는 “문서 읽기 완료”, “요약 생성 완료”, “결과 저장 완료”, “사용자 알림 완료”처럼 잡을 수 있습니다. replay가 발생하면 이미 결과 저장이 끝난 작업은 같은 idempotency key로 기존 결과를 반환하거나 알림 단계만 확인합니다. observability에는 모델 호출 시간, 비용 추정치, 실패 사유, queue lag를 넣습니다. rollback criteria는 비용과 중복 생성에 민감하게 잡습니다.

예시 B: 결제 후 포인트 지급

결제 이벤트는 중복 전달될 수 있습니다. 이때 worker가 단순히 “이벤트를 받으면 포인트를 더한다”로 구현되면 같은 결제에 포인트가 두 번 지급됩니다. idempotency key는 결제 provider 이벤트 id와 내부 주문 id를 조합합니다. enqueue 단계에서 중복 이벤트를 줄이고, worker 단계에서 이미 처리된 결제인지 확인하며, 포인트 지급 직전에도 지급 원장에 같은 키가 있는지 확인합니다.

retry policy도 보수적이어야 합니다. 결제 검증 API의 일시 오류는 retry할 수 있지만, 주문 금액 불일치나 이미 취소된 주문은 permanent failure입니다. partial failure가 발생해 포인트 원장은 기록됐지만 알림 발송이 실패했다면 replay는 포인트를 다시 지급하지 않고 알림만 재시도해야 합니다. 이 예시에서 rollback criteria는 중복 지급 1건만 있어도 즉시 worker를 멈추는 수준으로 잡는 것이 안전합니다.

예시 C: 대량 알림 팬아웃

공지 알림을 10만 명에게 보내는 작업은 단일 job 하나로 처리하면 위험합니다. 상위 job은 대상자를 chunk로 나누고, 하위 job이 각 chunk를 처리하게 합니다. 각 하위 job에는 batch id, chunk id, cursor, idempotency key를 넣습니다. checkpoint는 chunk 단위와 개별 발송 단위 사이에서 균형을 잡습니다. 너무 개별적으로 저장하면 비용이 크고, 너무 크게 저장하면 replay 중복이 커집니다.

rate limit은 이 예시의 핵심입니다. 외부 메시지 서비스가 초당 100건만 허용한다면 worker concurrency limit과 retry policy가 그보다 낮게 설계되어야 합니다. 실패한 수신자만 다시 처리할 수 있게 결과를 분리하고, 영구 실패 주소는 dead letter queue나 suppression list로 보냅니다. AI가 만든 코드 리뷰에서는 “for loop로 전체 대상자에게 즉시 발송” 같은 구현을 발견하면 반드시 queue 분할과 backpressure 설계를 요구해야 합니다.

실수와 주의점

실수 1: retry를 성공률 향상 장치로만 본다

retry는 성공률을 높이지만 동시에 장애를 증폭할 수 있습니다. 외부 서비스가 느려졌을 때 모든 worker가 즉시 retry하면 장애가 회복될 틈을 주지 않습니다. retry policy는 반드시 오류 분류, 최대 attempt, exponential backoff, jitter, rate limit 존중, dead letter queue 이동을 함께 가져야 합니다. 단순 while loop나 재귀 호출 retry는 운영 환경에서 위험합니다.

실수 2: job payload에 모든 것을 넣는다

큰 payload는 오래된 데이터와 민감한 문맥을 복제합니다. 특히 사용자의 본문, 토큰처럼 취급해야 하는 값, 내부 경로, 디버그 문자열을 queue에 넣으면 추적과 삭제가 어려워집니다. payload는 재처리에 필요한 최소 식별자와 정책 값만 담고, worker가 처리 시점에 최신 데이터를 읽도록 설계합니다. 테스트 fixture도 실제 개인정보가 아니라 익명화된 샘플을 씁니다.

실수 3: 상태 전이를 로그로만 남긴다

로그는 검색에는 좋지만 제품 상태의 원천으로 쓰기 어렵습니다. job state machine은 데이터로 남아야 합니다. queued에서 running으로, running에서 succeeded 또는 waiting_retry로, retry 한도 초과 시 dead_lettered로 이동하는 상태 전이가 명확해야 합니다. 그래야 운영 화면, 알림, 테스트, 복구 스크립트가 같은 기준을 봅니다.

실수 4: replay를 수동 버튼 하나로 해결하려 한다

replay는 위험한 작업입니다. 수정된 코드가 정말 같은 job을 안전하게 처리하는지, 이미 완료된 checkpoint를 건너뛰는지, 외부 부작용이 중복되지 않는지 확인해야 합니다. 모든 dead letter queue 항목을 한 번에 replay하는 버튼은 사고를 키울 수 있습니다. 작은 샘플, dry-run, rate 제한, 결과 비교, 중단 기준을 갖춘 replay가 안전합니다.

실수 5: AI에게 큐 라이브러리 선택만 맡긴다

큐 라이브러리나 클라우드 서비스 선택은 중요하지만, 더 중요한 것은 작업 계약입니다. 어떤 라이브러리를 쓰든 idempotency key, retry policy, visibility timeout, concurrency limit, checkpoint, dead letter queue, observability는 필요합니다. AI가 특정 도구의 예제 코드를 가져와도 이 가드레일이 없으면 제품 품질은 보장되지 않습니다. 도구 선택 전에 실패 모드 표를 먼저 만들게 하세요.

검증 체크리스트

구현 전 체크

  • 이 작업이 동기 처리보다 queue에 적합한 이유를 한 문장으로 썼다.
  • job payload가 최소 식별자와 정책 값만 포함한다.
  • idempotency key 생성 규칙이 비즈니스 이벤트 기준으로 정의되어 있다.
  • enqueue, worker start, side-effect boundary 세 지점의 deduplication 전략이 있다.
  • transient, permanent, manual_review 오류 분류가 있다.
  • retry policy가 exponential backoff, jitter, 최대 attempt, rate limit 존중을 포함한다.

테스트 체크

  • 같은 idempotency key를 가진 job을 두 번 넣어도 결과가 하나로 수렴한다.
  • worker가 checkpoint 후 죽어도 replay가 완료된 부작용을 반복하지 않는다.
  • transient 오류는 retry되고 permanent 오류는 즉시 failed로 끝난다.
  • 최대 attempt를 넘은 poison message가 dead letter queue로 이동한다.
  • visibility timeout보다 긴 작업에서 heartbeat 또는 checkpoint 갱신이 동작한다.
  • concurrency limit 상황에서도 같은 리소스에 중복 성공이 생기지 않는다.
  • queue lag, 실패율, retrying 수, dead letter queue 수가 관측 지표로 노출된다.

배포 후 체크

  • 신규 worker 배포 직후 enqueue 수와 succeeded 수가 예상 범위에 있다.
  • failed와 retrying 비율이 기준선을 넘지 않는다.
  • dead letter queue가 증가하면 알림 또는 운영 대시보드에서 확인된다.
  • 외부 rate limit 오류가 늘면 concurrency limit을 낮출 수 있다.
  • rollback criteria가 숫자로 정의되어 있고 담당자가 바로 실행할 수 있다.
  • 공개 화면에는 내부 job id, 작업자용 상태, 조작 버튼, 민감한 payload가 노출되지 않는다.

다음 단계

작게 시작하려면 기존 기능 하나를 고르세요. “메일 발송”, “AI 요약”, “이미지 변환”, “정산”, “알림 팬아웃” 중 하나를 선택하고, 현재 구현이 동기 처리인지, queue인지, 수동 배치인지 확인합니다. 그다음 job payload, idempotency key, retry policy, dead letter queue, observability, rollback criteria를 한 장짜리 작업 계약으로 씁니다. 이 계약을 AI 작업 지시서의 첫 부분에 넣으면 결과물이 훨씬 안정됩니다.

두 번째 단계는 테스트입니다. 처음부터 모든 장애를 자동화하려고 하지 말고, 중복 실행, partial failure, retry 한도 초과 세 가지를 우선 테스트합니다. 이 세 가지가 잡히면 대부분의 queue 사고가 초기에 드러납니다. 특히 replay 테스트는 필수입니다. 같은 job을 다시 실행했을 때 이미 완료된 단계가 반복되지 않는지 확인해야 합니다.

세 번째 단계는 운영 스모크입니다. 배포 후 worker가 실제 queue에서 job을 가져가는지, 실패 지표가 올라오는지, dead letter queue가 보이는지, 공개 화면에 내부 상태가 새지 않는지 확인합니다. AI가 만든 비동기 기능은 “로컬에서 한 번 성공”보다 “운영에서 멈추고 복구할 수 있음”이 더 중요합니다. 이 기준을 팀의 VIBE 코딩 루틴으로 만들면 AI 속도를 유지하면서도 제품 신뢰를 지킬 수 있습니다.

마지막으로, queue 설계를 반복 가능한 템플릿으로 남기세요. 새 background job을 만들 때마다 job 목적, payload, idempotency key, retry policy, checkpoint, dead letter queue, observability, rollback criteria를 채우게 하면 AI에게 맡길 수 있는 범위가 넓어집니다. 사람은 안전 계약을 설계하고, AI는 구현과 테스트 초안을 빠르게 만들며, 자동화된 검증은 제품 운영의 마지막 방어선이 됩니다.

다음 학습

같은 섹션에서 이어 읽기 좋은 콘텐츠

윤슬 코드·AI 권한 경계 테스트·2026.04.29·15분 읽기

AI 권한 경계 테스트

AI가 만든 기능은 화면이 예쁘고 테스트 데이터로 동작해도, 권한 경계가 한 번 새면 바로 신뢰 사고가 됩니다. 사용자는 자기 글만 봐야 하는데 다른 팀의 문서를 열 수 있고, 일반 멤버가 관리자 버튼을 호출할 수 있으며, URL의 숫자 하나를 바꿨더니 남의 결제 내역이 보일 수 있습니다. 이런 문제는 authentication, 즉 “누구인지 확인했는가”만으로 막히지 않습니다. 로그인 이후에도 authorization, 즉 “이 사람이 이 객체에 이 행동을 해도 되는가”를 매 요청마다 검증해야 합니다.

초보자는 permission boundary를 “여기부터는 이 사람에게 허용되지 않는 선”으로 이해하면 됩니다. 실무자는 여기에 RBAC, role matrix, tenant isolation, object ownership, least pr…

#VIBE 코딩#권한 테스트#보안 가드레일
요약맥락
윤슬 코드·AI API 계약 테스트·2026.04.29·14분 읽기

AI API 계약 테스트 루프

AI에게 화면과 서버 API를 동시에 맡기면 가장 자주 생기는 실패는 “둘 다 그럴듯하지만 서로 맞지 않는 상태”입니다. 프론트엔드는 name 필드를 기대하는데 서버는 displayName을 돌려주고, 서버는 201을 반환하는데 화면 테스트는 200만 기다리고, 오류 응답은 어떤 곳에서는 message이고 어떤 곳에서는 error.detail입니다. 작은 불일치는 로컬 데모에서는 지나가지만 배포 후에는 빈 화면, 재시도 루프, 잘못된 캐시, 깨진 알림으로 나타납니다.

초보자는 API 계약을 “서로 약속한 요청과 응답의 모양”으로 이해하면 됩니다. 실무자에게는 더 엄격합니다. 요청 스키마, 응답 스키마, status code, error envelope, pagination, idempotency key, versioning, 인증 실패 형태,…

#VIBE 코딩#API 계약#계약 테스트
요약맥락