에러 상태(Error States)는 오늘날의 자신을 위해서가 아니라, 3개월 뒤의 낯선 이를 위해 작성하세요

대부분의 에러 메시지는 잘못된 독자를 대상으로 작성됩니다.

에러 메시지는 무언가 고장 났을 때 지켜보고 있는 사람을 위해 작성됩니다. 당신은 터미널 앞에 있고, 실행이 실패하며, 메시지에 connection refused 또는 validation failed at step 3라고 표시됩니다. 지금 당신의 머릿속에 모든 맥락(Context)이 있기 때문에 그것만으로도 충분합니다. 당신은 무엇을 하고 있었는지, 무엇을 변경했는지, 시스템이 무엇을 하기로 되어 있었는지 알고 있습니다. 메시지는 그저 당신이 이미 가지고 있는 기억을 상기시켜 주기만 하면 됩니다.

하지만 실제로 에러 상태(Error state)가 필요한 독자는 완전히 다른 사람이며, 그들은 몇 달 뒤에 나타납니다. 저는 이전 포스트의 긴 댓글 스레드에서 이러한 관점을 받아들이게 되었고, 이는 제가 실패 처리(Failure handling)를 생각하는 방식, 특히 제가 현재 많이 수행하고 있는 비동기(Async), 에이전트 기반(Agent-driven) 작업에 대한 생각을 바꾸어 놓았습니다.

당신이 설계 대상으로 삼지 않는 독자

여기에 간극이 있습니다. 대화형 도구(Interactive tool)가 실패할 때는 즉각적으로 반응하는 인간이 루프 안에(Human in the loop) 있습니다. 맥락이 실시간으로 존재하기 때문에 에러 메시지는 간결해도 됩니다. 위로 스크롤하여 대화 내용을 확인하고 문제를 수정하면 됩니다.

비동기(Async) 작업에는 그런 것이 전혀 없습니다. 에이전트가 새벽 2시에 파이프라인(Pipeline)을 실행하다가 중간에 무언가 실패하면, 아무도 그 상황을 목격하지 못합니다. 되돌려 볼 대화 내용도 없고, 재생 버튼도 없으며, 누구의 머릿속에도 따뜻한 맥락(Warm context)이 남아 있지 않습니다. 조사하는 사람은 몇 시간 또는 몇 주 뒤에 아무런 정보 없이 나타나며, 그들이 가진 유일한 것은 프로세스가 멈추기 전에 기록해 둔 것뿐입니다.

이는 해당 독자에게 에러 상태가 실패에 대한 보고서가 아니라는 것을 의미합니다. 그들이 볼 수 있는 한, 그것이 곧 실패 그 자체입니다. 만약 기록에 무슨 일이 일어났는지 재구성하는 데 필요한 정보가 포함되어 있지 않다면, 그 정보는 사라진 것입니다. 찾기 어려운 것이 아니라, 사라진 것입니다.

이것은 설계 질문 전체를 재구성합니다. 질문은 "이 에러를 어떻게 포맷할 것인가"에서 "조사자가 아무것도 없는 상태에서 이 실행(Run)을 재구축하기 위해 무엇이 필요한가"로 바뀝니다. 이 둘은 서로 다른 사양(Spec)이며, 제가 지금까지 작성한 거의 모든 에러 메시지는 조용히 첫 번째 질문에만 답하고 있었습니다.

메시지(Message) 대 기록(Record)

가장 명확하게 구분하자면 이렇습니다: 대부분의 에러는 메시지(message)이고, 비동기 작업(async work)이 필요로 하는 것은 기록(record)입니다.

메시지는 당신과 같은 상황을 공유하는 사람에게 쓰여집니다. 둘 다 이미 알고 있는 것을 가리키고 있기 때문에 짧아도 됩니다.

저는 마치 독자가 해당 실행(run)의 나머지 부분에 접근할 수 없는 것처럼 에러 상태(error states)를 작성합니다. 단순히 "3단계 실패"라고 적는 것이 아니라, 3단계가 무엇을 하려고 했는지, 무엇을 받았는지, 그리고 무엇을 기대했는지를 적습니다. 이 추가적인 한 문장은 지금 당장은 비용이 들지 않지만, 나중에 한 시간을 아껴줍니다.

저는 깔끔한 에러 상태를 시간이 남을 때 덧붙이는 것이 아니라, 제가 선택한 감사 추적(audit trail)으로 취급합니다. 비동기(async) 작업에서는 다른 추적 수단이 없습니다. 실패가 증거를 남겼거나 남기지 않았거나 둘 중 하나이며, 이는 장애(incident)가 발생했을 때가 아니라 핸들러(handler)를 작성할 때 결정됩니다.

그리고 저는 데모를 위해 실패 출력(failure output)을 최적화하는 것을 그만두었습니다. 성공하는 모습을 지켜보고 있을 때 보기 좋은 버전은, 관리되지 않는 상태에서 실패했을 때 도움이 되는 버전이 아닙니다. 그들은 서로 다른 대상(audience)이며, 관리되지 않는 상태의 대상이야말로 실제로 도움이 필요한 대상입니다.

이 아이디어의 가장 핵심적인 요약

이 모든 것을 한 줄로 압축한다면 다음과 같습니다: '지금 당장 유용한 것'과 '3개월 뒤에 유용한 것'은 서로 다른 사양(spec)이며, 보통 그중 하나만 충족할 수 있습니다. 그러니 더 까다로운 독자를 선택하세요.

낯선 이를 선택하세요. 당신이 이해할 수 있는 메시지가 아니라, 그들이 필요로 할 기록을 작성하세요. 그 기록이 읽힐 때 당신은 그 자리에 없을 것이며, 에러 상태의 목적 자체가 당신이 없을 때 작동하는 데 있기 때문입니다.

저는 WordPress 플러그인을 제작하며, https://raplsworks.com/에서 AI 툴링(tooling)과 보안에 대해 글을 씁니다.