AI 에이전트가 이메일을 다룰 때, 어려운 점은 메시지를 보내는 것 자체가 아닙니다. 진짜 어려운 점은 재시도(retries), 부분적 실패(partial failures), 그리고 쌓여가는 백그라운드 작업(background jobs) 이후에 정확히 어떤 실행에서 어떤 일이 일어났는지 증명하는 것입니다. 몇 달 전부터 저는 각 이메일 작업을 고유한 실행 폴더(run folder)를 가진 하나의 작은 아티팩트 번들(artifact bundle)로 취급하기 시작했고, 덕분에 디버깅이 훨씬 덜 극단적으로 변했습니다.

이것은 화려한 패턴이 아닙니다. 대부분 절제된 파일 명명 규칙, 하나의 실행 ID(run ID), 그리고 적은 가정이 전부입니다. 하지만 크론 작업(cron jobs), 승인 흐름(approval flows), 그리고 스크립트된 지원 작업(scripted support tasks)의 경우, 전체 파이프라인의 일상적인 동작을 바꾸어 놓았습니다.

에이전트가 재시도할 때 이메일 작업이 이상해지는 이유

이메일 기반 워크플로우(workflows)는 세 가지 일이 동시에 자주 발생하기 때문에 빠르게 흐트러집니다:

1. 한 에이전트가 동작을 트리거하지만, 다른 워커(worker)가 전달을 수행합니다.
2. 재시도(Retries)가 언뜻 보기에는 여전히 유효해 보이는 추가 메시지들을 생성합니다.
3. 로그(Logs), 편지함 확인(inbox checks), 그리고 생성된 콘텐츠(generated content)가 서로 다른 곳에 존재합니다.

이러한 분리는 가장 짜증 나는 종류의 버그를 만들어냅니다. 즉, 작업이 "어느 정도" 작동은 했지만, 어떤 출력이 어떤 실행(run)에 속하는지 아무도 설명할 수 없는 상황입니다. 저는 팀들이 이를 덮으려고 대기 시간을 늘리거나, 추가적인 폴링(polling)을 하거나, 더 많은 대시보드 알림을 추가하는 것을 보았습니다. 이는 하루 정도는 도움이 되지만, 곧 혼란이 다시 찾아옵니다.

만약 당신의 자동화가 검증이나 스테이징 확인(staging checks)을 위해 임시 메일 주소를 생성해야 한다면, 동일한 문제가 훨씬 더 빠르게 나타납니다. 실행(run)에 엄격한 경계가 없다면 하나의 편지함은 쓰레기통이 될 수 있습니다. 이는 로컬 모크(local mock), 제공업체(provider), 또는 임시 메일 서비스(temp mail service)를 사용하는 것과 상관없이 마찬가지입니다.

제가 현재 사용하는 실행 폴더 계약(run folder contract)

저의 규칙은 간단합니다. 하나의 실행은 하나의 run_id를 가지며, 해당 실행을 위한 모든 유용한 아티팩트(artifact)는 하나의 폴더에 담깁니다.

예를 들어:

generated/
  20260718T022222Z-mrdapperx/
    plan.json
...

그 폴더는 단순한 저장소가 아닙니다. 그것은 계약(contract)입니다. 만약 어떤 단계(step)가 자신이 어떤 실행 폴더에 속하는지 나에게 말할 수 없다면, 저는 그것을 설계상의 악취(design smell)로 간주합니다.

이 계약에는 보통 다음이 포함됩니다:

• 하나의 생성된 run_id
• 해당 실행(run)을 위해 선택된 하나의 수신함(inbox) 또는 별칭(alias)
• 의도(intent)를 설명하는 하나의 계획(plan) 파일
• 사람이 검사할 수 있는 하나의 출력 아티팩트(output artifact)
• 최종 URL 또는 에러를 포함한 하나의 게시(publish) 또는 실행(execution) 결과

이것은 거의 너무 당연하게 들릴 수도 있지만, 모호한 추론(hand-wavy reasoning)을 많이 제거해 줍니다. "봇이 올바른 것을 보냈는가?"라고 묻는 대신, "20260718T022222Z-mrdapperx 실행에서 무슨 일이 일어났는가?"라고 묻게 됩니다. 그 질문은 새벽 2시나, 동료가 자신이 작성하지 않은 실패 사례를 분류(triaging)하고 있을 때 훨씬 대답하기 쉽습니다.

또한 저는 이 패턴이 운영 훈련을 위한 컨테이너 기반 이메일 체크나 프론트엔드 워크플로우에서의 타입 지정된 이메일 이벤트와 같은 관련 아이디어와 함께 작동한다는 점이 마음에 듭니다. 스택은 다르지만 정신 모델(mental model)은 동일합니다: 하나의 실행을 격리하고 검사 가능하게 유지하는 것입니다.

하나의 실행 폴더 안에 들어가는 것

저는 의도적으로 구조를 지루하게 유지하려고 노력합니다. 지루한 시스템이 신뢰하기 더 쉽기 때문입니다.

여기 아주 간단한 스케치가 있습니다:

RUN_ID="$(date -u +%Y%m%dT%H%M%SZ)-agent42"
RUN_DIR="generated/${RUN_ID}"
mkdir -p "${RUN_DIR}"
...

그러면 이후의 모든 단계는 느낌(vibes) 대신 사실(facts)을 추가합니다:

const fs = require("fs");

fs.writeFileSync(`${process.env.RUN_DIR}/publish-result.json`, JSON.stringify({
...

이 가치는 단순히 기록 보관에만 있는 것이 아닙니다. 시스템이 가동 중일 때 의사 결정을 개선합니다:

• 재시도(retries) 시 결과 파일이 이미 존재하는지 확인할 수 있습니다.
• 사람은 대시보드를 뒤져보지 않고도 하나의 실행을 다른 실행과 비교(diff)할 수 있습니다.
• 크론 작업(cron tasks)이 전체 두 번째 초안을 다시 생성하지 않고도 명확하게 실패를 알릴 수 있습니다.
• 폴더가 이미 컨텍스트(context)를 담고 있기 때문에 에이전트 프롬프트(agent prompts)를 더 작게 유지할 수 있습니다.

이러한 구조가 없는 오래된 리포지토리들을 보면 dummy e mail이나 tempail mail 같이 지저분한 피스처(fixture) 이름들이 있는 것을 자주 발견합니다. 이것들은 워크플로우가 시간이 지나면서 다소 옆으로 엇나갔음을 보여주는 작은 신호들입니다. 치명적인 것은 아니지만, 시스템이 팀의 기대보다 보통 더 취약하게 느껴지게 만듭니다.

임시 인박스(Temporary Inboxes)가 도움이 되는 지점

임시 인박스(Temporary inboxes)는 여기서 유용하지만, 실행 폴더(run folder) 계약을 대체하는 것이 아니라 이를 지원할 때만 유용합니다.

인박스 제공자에게 제가 원하는 것은 꽤 겸손합니다:

• 실행 범위(run-scoped) 주소에 대한 빠른 생성 또는 라우팅
• 한 수신자에 대한 예측 가능한 메시지 조회
• 하나의 실행(run)을 깔끔하게 상관관계(correlate) 지을 수 있는 충분한 메타데이터

이것이 바로 임시 메일을 생성하는 도구들이 AI 및 자동화 워크플로우(workflows)에서 진정으로 유용할 수 있는 지점입니다. 이러한 도구들은 전체 설계를 영구적으로 하나의 메일함에 묶어두지 않고도 빠른 격리(isolation)를 제공합니다. 그럼에도 불구하고, 단언(assertions)은 여전히 나의 것이어야 합니다. 인박스 제공자는 증거를 수집하는 것을 도울 뿐이며, 유일한 진실의 원천(source of truth)이 되어서는 안 됩니다.

이것이 제가 "최신 이메일에 Welcome이 포함되어 있는가"와 같은 체크 방식을 피하는 이유이기도 합니다. 무엇에 따른 최신인가요? 어떤 재시도(retry)인가요? 어떤 워커(worker)인가요? 어떤 리전(region)인가요? 실행 폴더(run folder)는 이러한 질문들이 머물 곳을 제공하며, 모든 실패가 사라지지는 않더라도 디버깅(debugging) 과정이 더 차분해질 수 있습니다.

워크플로우 계측(workflow instrumentation)에 대한 일반적인 참고 자료를 원하신다면, OpenTelemetry의 문서가 시작하기 좋은 곳입니다: https://opentelemetry.io/docs/concepts/signals/traces/. 이 패턴의 이점을 얻기 위해 전체 트레이싱(tracing)이 필요한 것은 아니지만, 트레이스 경계(trace boundaries)가 어떻게 작동하는지 읽어보면 폴더 개념을 더 빨리 이해할 수 있을 것입니다.

Q&A

작은 자동화 작업에 이 방식은 너무 과한 절차(ceremony)인가요?

보통은 아닙니다. 폴더 구조는 매우 작으며, 거의 즉각적으로 더 나은 감사 가능성(auditability)을 얻을 수 있습니다. 혼자 작업하는 빌더(builder)라 할지라도, 일주일 뒤에 크론 잡(cron job)이 실패했을 때 컨텍스트(context)가 여전히 보존되어 있다면 이점를 얻게 됩니다.

실행 폴더에 프롬프트(prompts)도 저장해야 하나요?

때로는 그렇습니다. 프롬프트가 출력값에 실질적인 변화를 준다면, 정확한 프롬프트나 프롬프트 해시(prompt hash)를 저장할 가치가 있습니다. 다만 비밀 정보(secrets)와 개인 데이터에는 주의하십시오.

이것이 로그(logs)나 트레이싱(tracing)을 대체하나요?

아니요. 이것을 하나의 실행(execution)을 위한 안정적인 로컬 번들(local bundle)로 생각하십시오. 로그는 시스템 전반에 걸친 이야기를 들려주며, 실행 폴더는 핵심 아티팩트(artifacts)를 함께 보관하여 그 이야기를 더 쉽게 검증할 수 있도록 합니다.