오류 경로 분석

정상일 때만 작동하는 화면이 아니라, 실패했을 때도 사용자가 현재 상태를 이해하고 안전하게 다음 행동을 할 수 있는지 점검한다.

초보자를 위한 용어

• 정상 경로: 사용자의 행동이 예상대로 끝나는 흐름이다.
• 오류 경로: 입력 오류, 연결 끊김, 권한 부족처럼 정상 결과에 도달하지 못하는 흐름이다.
• 빈 상태: 데이터가 아직 없을 때 보이는 화면이다. 오류와 달리 정상적인 첫 사용 상태일 수 있다.
• 부분 실패: 여러 단계 중 일부만 성공한 상태다. 주문은 저장됐지만 알림 전송은 실패한 경우가 예다.
• 멱등성: 같은 요청을 반복해도 결제나 예약이 한 번만 처리되는 성질이다.
• 복구 경로: 실패 뒤 사용자가 작업을 이어가거나 안전한 상태로 돌아가는 방법이다.

먼저 지킬 원칙

• 사용자가 요청한 흐름이나 변경된 핵심 흐름부터 본다. 가능한 모든 오류를 상상해 목록만 늘리지 않는다.
• 감사 요청과 수정 요청을 구분한다. 검토만 요청받았다면 코드를 바꾸지 않는다.
• 현재 코드, 화면, 로그 구조에서 확인한 사실과 아직 재현하지 않은 가설을 구분한다.
• 오류를 숨기기 위해 무조건 성공 화면을 보여주지 않는다.
• 사용자에게 내부 오류, 스택, 쿼리, 시크릿을 노출하지 않는다.
• 운영 로그에도 비밀번호, 토큰, 결제 원문, 불필요한 개인정보를 남기지 않는다.
• 실제 결제, 이메일 발송, 운영 데이터 작성, 계정 잠금 같은 테스트는 별도 승인 없이 실행하지 않는다.

사용할 때

• 로그인과 권한 확인
• 주문, 결제, 환불, 예약
• 파일 업로드와 변환
• 글 작성과 자동 저장
• 외부 API나 AI 생성 기능
• 오프라인·느린 연결·시간 초과 경험
• 첫 사용의 빈 상태와 검색 결과 없음

특정 오류가 왜 발생하는지 찾는 디버깅 요청이라면 원인 재현과 추적이 먼저다. 이 스킬은 원인보다 실패를 만난 사용자의 상태와 복구 경험을 다룬다.

1. 핵심 흐름을 한 줄로 그린다

사용자 행동 → 요청 시작 → 처리 중 → 결과 저장 → 사용자에게 결과 표시

실제 흐름에 없는 단계를 만들지 않는다. 외부 서비스나 백그라운드 작업이 있으면 해당 위치에 표시한다.

사용자 행동:
기대 결과:
변하는 데이터·금액·권한:
외부 의존성:
완료를 판단하는 기준:

2. 화면과 시스템 상태를 찾는다

필요한 상태만 확인한다.

• 시작 전
• 입력 검증 실패
• 처리 중
• 성공
• 데이터 없음
• 권한 부족 또는 로그인 만료
• 연결 끊김 또는 시간 초과
• 외부 서비스 실패
• 일부만 성공
• 결과를 알 수 없음

“결과를 알 수 없음”은 서버 응답을 받지 못했지만 실제 처리가 끝났을 수도 있는 상태다. 결제나 주문에서 이 상태를 단순 실패로 보고 다시 실행하면 중복이 생길 수 있다.

3. 실패별 사용자 상태를 기록한다

다음을 함께 본다.

• 로딩이 끝나는 조건이 있는가
• 실패 뒤 입력 내용과 업로드 파일이 필요한 만큼 보존되는가
• 저장됐는지 모르는 상태를 성공이나 실패로 단정하지 않는가
• 사용자가 직접 고칠 수 있는 것과 운영자가 해결해야 하는 것을 구분하는가
• 뒤로 가기, 새로고침, 재로그인 뒤 상태가 일관적인가
• 같은 행동을 반복해도 중복 데이터나 금액 손실이 없는가

4. 오류 메시지를 점검한다

좋은 메시지는 세 가지를 알려준다.

무슨 일이 있었는가
현재 무엇이 보존됐거나 처리됐는가
사용자가 다음에 무엇을 할 수 있는가

예시:

나쁨: 오류가 발생했습니다. 다시 시도하세요.

개선: 파일 업로드가 완료되지 않았습니다.
작성한 제목과 설명은 보존했습니다.
연결을 확인한 뒤 파일만 다시 선택해주세요.

원인을 모르면 꾸며내지 않는다. 운영팀이 추적할 식별자가 필요하면 개인정보나 내부 상세 대신 안전한 오류 번호를 제공한다.

5. 재시도 안전성을 확인한다

비교적 단순한 재시도

데이터를 읽는 요청처럼 반복해도 상태가 바뀌지 않는 작업은 재시도하기 쉽다. 그래도 무한 반복이나 과도한 요청은 막는다.

상태가 바뀌는 작업

결제, 예약, 포인트, 주문, 이메일, 파일 생성은 다음을 먼저 확인한다.

• 요청을 구별할 고유 식별자가 있는가
• 서버가 같은 요청의 중복 처리를 막는가
• 처리 결과를 다시 조회할 수 있는가
• 부분 성공 뒤 이어서 처리하거나 보상할 방법이 있는가
• 사용자가 반복 클릭하지 않도록 진행 상태를 보여주는가

안전성이 확인되지 않으면 “다시 시도” 버튼을 먼저 추가하지 않는다. 상태 확인이나 고객 지원 연결이 더 안전할 수 있다.

6. 우선순위를 정한다

• 즉시 수정: 금액·데이터·권한 손실, 중복 처리, 개인정보 노출, 작업 전체 유실 위험이 확인됐다.
• 중요 수정: 사용자가 막히거나 잘못된 행동을 반복할 가능성이 높다.
• 개선 후보: 복구는 가능하지만 설명이나 편의가 부족하다.
• 미확인: 관련 코드·화면·실행 환경을 확인하지 못했다.

발생 가능성과 영향 근거 없이 모든 항목을 최고 우선순위로 만들지 않는다.

7. 검증한다

수정까지 요청받았다면 가장 작은 재현 조건을 만든다.

실패를 만드는 입력 또는 조건:
예상되는 시스템 상태:
예상되는 화면 메시지:
보존돼야 할 사용자 입력:
허용되는 다음 행동:
중복되지 않아야 할 데이터·금액:

정적 코드 확인, 테스트 환경 실행, 운영 환경 확인을 구분해서 보고한다. 모의 응답으로 통과한 결과가 실제 외부 서비스에서도 통과한다고 말하지 않는다.

출력 형식

## 점검한 흐름
- 사용자 행동:
- 기대 결과:
- 변경되는 상태:

## 발견 사항
| 우선순위 | 실패 조건 | 사용자에게 생기는 일 | 시스템 상태 | 안전한 복구 | 근거 |
|---|---|---|---|---|---|

## 먼저 고칠 것
- 위치:
- 이유:
- 최소 수정 방향:

## 검증 결과
- 정적 확인:
- 실행 확인:
- 확인하지 못한 영역:

초보자가 바로 쓸 요청 예시

파일 업로드가 실패했을 때 사용자가 처음부터 다시 작성해야 하는지 점검해줘.
입력 보존, 오류 메시지, 다시 시도 흐름을 보고
아직 코드는 수정하지 말아줘.

결제 버튼을 두 번 누르거나 응답이 늦을 때
중복 결제가 생길 수 있는 경로를 찾아줘.
실제 결제 테스트는 하지 말고 코드와 테스트 환경에서 확인 가능한 범위만 알려줘.

검색 결과가 없을 때와 서버 오류일 때가 같은 화면으로 보여.
두 상태를 어떻게 구분하고 사용자가 무엇을 할 수 있게 해야 하는지 검토해줘.