웰컴 대체경로 문서화로 온보딩 혼동 해소

웰컴 프로세스는 보통 단순할 것 같지만, 실제로는 여러 대체 경로를 가진다. 사용자가 충전 시스템을 통할 수도 있고, 본인인증 절차를 먼저 밟을 수도 있다. 지금까지 이 경로들이 명시적으로 문서화되지 않으면서, 신규 팀원들이 온보딩할 때마다 "어느 경로가 정식이고 어느 게 대체 경로냐"는 질문을 받곤 했다.

왜 대체경로 명시가 중요한가

개발 초반엔 웰컴 플로우가 일직선이었을 가능성이 높다. 하지만 운영을 하면서 여러 시나리오를 만난다. 충전 단계가 먼저 올 수도 있고, 본인인증이 선행되어야 하는 경우도 생긴다. 이런 예외 케이스들이 쌓이다 보면 자연스럽게 "표준 경로 + 대체 경로" 구조가 생긴다.

문제는 이 구조가 개발자들의 머리 안에만 있다는 것이었다. 코드엔 예외 처리로 흩어져 있고, 온보딩 때 신규 팀원에게 구두로 설명하거나, 각자가 시간을 들여 파악해야 했다. 그렇게 되면:

• 신규 팀원이 경로를 잘못 이해하고 버그 신고를 한다
• 비상 상황에서 의사결정이 느려진다 ("대체경로가 있나요?" "어, 있는데 문서에 없네?")
• 유지보수 시 누군가는 대체 경로를 놓친다

문서화의 범위

이번 커밋에서 명시한 건 두 가지 구체적인 대체 경로다.

두 경로 모두 최종 상태는 동일하지만, 진입점이 다르다. 이 차이를 명시함으로써:

1. 코드 리뷰 때 기준이 생긴다 — "이건 충전 경로 로직인가, 인증 경로 로직인가?" 를 빠르게 판단
2. 테스트 케이스가 명확해진다 — 두 경로 각각을 다 커버해야 한다는 걸 팀이 인지
3. 온보딩이 체계화된다 — 신규 팀원이 "이게 뭐예요?" 묻지 않아도 문서를 읽으면 이해

문서의 위치 선택

.claude/CLAUDE.md (전역 지침)와 .claude/rules/settlement-domain.md (도메인 지침)에 모두 명시한 건 의도가 있다.

전자는 "모든 팀원이 알아야 하는 최소 정보"를 담고, 후자는 "결제·정산 도메인에 깊숙이 관여하는 개발자들의 세부 가이드"를 담는 구조다. 신규 팀원은 전역 문서로 개요를 잡고, 충전/결제 쪽 작업을 하게 되면 도메인 지침을 깊게 읽는 흐름이 된다.

이렇게 계층화하면 정보 과부하를 줄이면서도 필요한 사람이 필요한 깊이로 학습할 수 있다.

회고

문서화는 "선택"이 아니라 "채무"라는 걸 다시 느낀다. 코드를 짜는 것도 중요하지만, 그 의도와 경로를 팀 전체가 공유하게 만드는 게 리더의 몫이다. 특히 예외 케이스나 대체 경로처럼 "없는 줄 아는 사람도 있고 있는 줄 아는 사람도 있는" 것들을 명시하는 일이 그렇다.

비슷한 상황이 생기면, "이미 해결했는데 왜 또 물어봐?"라고 생각하기 전에 "명시되지 않았으니 다시 문서에 추가하자"는 태도가 팀을 크게 만든다.

🛒 이 글과 어울리는 추천 상품

• 모니터암 쿠팡에서 보기 →
• 사무의자 쿠팡에서 보기 →
• 커피머신 쿠팡에서 보기 →

*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.