안녕하세요, 구독자님. 프로덕트를 만들며 생각이 점점 많아지고 있는 hubert입니다.
요즘은 기획한 것을 실제로 만드는 데 걸리는 시간이 많이 줄었습니다. 요구사항을 정리하거나 화면 초안을 만들 때도 자연스럽게 AI의 도움을 받습니다.
그런데 문서를 들고 개발 검토를 시작하면 막힐 때가 있습니다. 요구사항은 자세히 적었는데, 어느 시스템에서 처리할지는 정하지 않은 경우입니다.
이번에는 오류 메시지를 통일해달라는 요청을 받고 기획을 구체화하면서 겪은 일을 이야기해보려고 합니다.
회의에서 이런 요청을 받은 적이 있습니다.
PG사는 결제를 대신 처리해주는 업체입니다. 요청을 정리하면 ‘결제 실패 때 고객에게 보여주는 오류 메시지를 같은 기준으로 맞춘다’는 뜻이었습니다.
일단 그렇게 적었지만 다음 내용을 쓰기가 어려웠습니다. 문구를 어떻게 쓸지보다 어느 시스템에서 바꿀지부터 정해야 했습니다.
문구를 고치기 전에, 어디에서 고칠지 정했습니다
이미 플랫폼과 PG사 사이에서 결제를 중계하고 있었습니다. 플랫폼의 결제 요청을 받아 PG사에 보내고, 결과를 다시 플랫폼에 전달합니다. 이 중계 시스템을 게이트웨이라고 합니다. 결제 결과가 우리 시스템을 거치니 오류 메시지도 여기서 정리할 수 있겠다고 봤습니다.
우리 게이트웨이를 쓰는 플랫폼은 여러 곳입니다. 각 플랫폼에서 메시지를 따로 고치면 어떻게 될까요?
같은 작업이 플랫폼 수만큼 반복됩니다.
PG사에 새 오류코드가 생길 때마다 모든 플랫폼이 각자 수정해야 합니다.
이후에도 플랫폼마다 계속 관리해야 하고요.
반대로 게이트웨이에서 한 번 정리하면, 새 코드가 생겨도 한 곳만 고치면 됩니다.
저는 개발자에게 기획을 잘 전달하려면 요구사항을 자세히 쓰면 된다고 생각했습니다. 상황별 상태값과 예외를 빠짐없이 적고, 화면마다 동작 조건을 설명하는 일이요.
지금은 그전에 어느 시스템에서 처리할지부터 정합니다. 그래야 같은 작업을 여러 곳에서 반복하지 않고, 이후에 누가 관리할지도 알 수 있습니다.
데이터를 보니, 고쳐야 할 문제가 달랐습니다
다음으로 실제 오류를 살펴봤습니다. 최근 몇 달치 결제 실패 로그, 즉 시스템에 남은 기록을 AI에게 주고 유형별로 분류해달라고 했습니다. 자주 나오는 코드와 메시지를 확인하고, 무엇부터 정리하면 좋을지도 물었습니다.
이 작업은 확실히 빨랐습니다. 예전에는 데이터를 뽑아 며칠 동안 직접 읽고 묶어야 했습니다. AI가 분류와 우선순위를 정리해주니 문서를 쓰기도 수월했습니다.
그리고 결과에서 두 가지가 눈에 들어왔습니다.
먼저 자주 발생하는 오류가 눈에 띄었습니다. 코드 종류는 많았지만, 실제로는 몇 가지 코드와 메시지 조합이 대부분을 차지했습니다. 이것부터 정리해도 많은 고객이 보는 안내를 바꿀 수 있었습니다.
더 중요한 발견도 있었습니다. 실패로 집계된 기록 중 상당수는 시스템 오류가 아니었습니다. 고객이 직접 결제를 취소하거나 인증 화면에서 나간 경우였는데도 실패 안내가 뜨고 있었습니다.
처음 요청은 ‘메시지가 제각각이라 혼란스럽다’는 것이었습니다. 하지만 데이터를 보니, 스스로 결제를 중단한 고객에게도 실패했다고 안내하고 있었습니다. 문구를 통일하는 것과 함께 이 안내도 고쳐야 했습니다.
저는 이 분류표를 보면서 이제 기획만 하면 되겠다고 생각했습니다.
돌아보면 너무 일찍 안심했습니다. 몇 달치 기록을 봤고, 자주 발생하는 오류와 우선순위도 알았으니 더 확인할 게 없다고 느꼈습니다.
하지만 제가 확인한 건 결제가 실패한 기록뿐이었습니다. 다른 시스템이 그 결과를 받아 어떻게 처리하는지는 보지 못했습니다. 기록을 많이 봤다는 이유로 그 부분까지 확인했다고 생각한 겁니다.
개발자의 질문으로 놓친 부분을 알았습니다
제품 요구사항 문서(PRD) 초안을 개발자에게 검토받을 때였습니다. 개발자가 이런 의견을 줬습니다.
확신해서 한 말은 아니었습니다. 이런 구조라면 플랫폼에서도 오류코드에 따라 다르게 처리하고 있을 수 있다는 의견이었습니다.
확인해보니 실제로 그랬습니다. 우리가 바꾸려던 오류코드 중 일부를 플랫폼에서도 쓰고 있었습니다. 특정 코드가 오면 고객을 다른 화면으로 보내거나 다음 행동을 안내하도록 만들어져 있었습니다.
우리가 그 코드를 바꾸면 어떻게 될까요? 메시지는 통일되지만, 플랫폼이 기존 코드를 인식하지 못해 다음 화면으로 보내지 못할 수 있습니다. 오류 표시가 뜨지 않은 채로요.
그제야 알았습니다. 오류코드는 고객에게 보여줄 문구뿐 아니라 시스템의 다음 동작을 정하는 값이기도 했습니다. 문구만 고친다고 생각했는데 다른 시스템의 동작까지 바꾸려던 셈입니다.
처음에는 제가 놓쳤다고 생각했습니다. 그런데 우리에게는 플랫폼의 코드 저장소를 열어볼 권한이 없었습니다. 주문 화면이 그 코드를 어떻게 쓰는지 직접 확인할 수 없었던 겁니다.
AI에게 질문을 더 잘했어도 이 기록만으로는 확인할 수 없었습니다. 로그에는 어떤 코드가 몇 번 나왔는지만 있고, 플랫폼이 그 코드를 어디에 쓰는지는 없었으니까요.
오류를 나누는 기준을 바꿨습니다
이후 표준 오류코드를 다시 설계했습니다. 처음에는 한도 초과, 잔액 부족, 카드 정지, 인증 실패처럼 오류의 종류로 나누려 했습니다. AI가 정리한 표도 비슷했습니다.
하지만 실제 결제는 여러 단계로 나뉘어 처리됩니다.
먼저 고객과 카드가 유효한지 확인하는 인증이 있습니다.
그다음 실제 결제를 처리하는 승인이 있습니다.
그리고 별도로 취소가 있습니다.
각 단계에서 오류가 날 수 있습니다. 그래서 결제의 어느 단계에서 발생했는지를 기준으로 오류코드를 나눴습니다.
같은 이유로 실패해도 발생한 단계에 따라 고객이 해야 할 일이 다릅니다. 인증 중에 막혔을 때와 승인이 거절됐을 때는 그 상황에 맞는 안내가 필요합니다.
이 기준을 먼저 정하니 어떤 문구를 보여주고 어느 화면으로 안내할지도 정할 수 있었습니다. 문구부터 쓰려 했다면 놓쳤을 부분입니다.
이런 결정을 하려면 결제가 어떤 순서로 처리되는지 알아야 합니다. 직접 코드를 짜지는 않더라도, 어느 단계에서 어떤 일이 일어나는지는 확인해야 합니다.
전부 바꾸지 않기로 했습니다
남은 건 두 가지 결정이었습니다.
첫째는 바꿀 범위였습니다. 플랫폼의 기존 동작에 영향을 주지 않는 오류코드부터 정리하기로 했습니다.둘째는 아직 정리하지 못한 오류를 어떻게 보여줄지였습니다. 이 부분이 가장 고민됐습니다. 방법은 두 가지였습니다.
하나는 모두 같은 안내 문구로 바꾸는 방법입니다. 화면은 깔끔해집니다.
다른 하나는 기존 메시지를 그대로 보여주는 방법입니다.
저는 기존 메시지를 보여주기로 했습니다. 대신 아직 정리하지 못한 메시지가 얼마나 자주 나오는지 확인할 수 있게 했습니다. 자주 나오는 것부터 차례로 통일할 계획이었습니다.
‘그럼 지금이랑 뭐가 다르냐’고 물을 수 있습니다. 제 생각은 이랬습니다. 기록을 보면서 다음에 고칠 메시지를 정하면 됩니다. 모두 같은 문구로 바꾸면 어떤 메시지를 더 정리해야 하는지 파악하기 어려워집니다.
플랫폼이 기존 방식대로 동작한다는 장점도 있었습니다. 우리가 메시지 변환 규칙을 추가한 부분만 달라집니다. 플랫폼이 결제 요청이나 데이터 구조를 바꿀 필요 없이, 우리가 보내는 결과값을 정리하면 됐습니다.
다른 조직에도 ‘기존 동작을 유지하면서 메시지를 조금씩 개선하겠습니다’라고 설명할 수 있었습니다. 무엇이 바뀌는지 분명하게 이야기하니 설득하기도 좋았습니다.
규칙은 운영자가 관리자 화면에서 직접 추가할 수 있게 했습니다. 새 오류가 생길 때마다 개발 일정을 잡지 않아도 되도록요.
그래서 기획서에 항목이 하나 늘었습니다
이후에는 값을 새로 만들거나 바꾸는 기획을 할 때 다음 내용을 먼저 확인합니다.
이 글에서 가장 이야기하고 싶은 건 마지막 항목입니다. 기획을 잘 전달하려면 문서를 쓰기 전에 어느 시스템에서 처리할지부터 정해야 했습니다. 요구사항을 자세히 적는 것만으로는 해결되지 않았습니다.
여러분은 기획서에 적은 값이 실제로 어느 화면이나 기능에서 쓰이는지 확인하고 있나요?
📮 다음 호 예고
[32호] 우리 회사에 몇 개의 Agent가 있는지 아시나요?
AI Agent 하나를 만드는 데 며칠이면 충분한 시대. 조직에 수십, 수백 개의 Agent가 생겨났을 때 필요한 것은 무엇일까요? 다음 호에서는 Agent를 개별 도구가 아닌 하나의 포트폴리오로 바라보는 방법을 이야기해봐요!
✉️ 다음 호가 궁금하신 분들은 아래 [구독하기] 버튼을 눌러주세요.
의견을 남겨주세요