한 명이 빠졌을 때를 대비한 문서화 룰

결제·정산 시스템에서 '한 명 공백'이 다른 이유

결제와 정산을 직접 운영하는 팀에서 구성원 한 명의 공백은 단순한 업무 공백이 아니다. 특정 PG사 웹훅을 왜 멱등성 처리를 이중으로 하는지, 정산 배치가 왜 특정 시간대를 피해 스케줄링되는지 — 이런 맥락은 담당자의 머릿속에 있다. 문제는 결제 오류는 휴일에도, 새벽에도, 담당자가 면접을 보는 오전에도 발생한다는 것이다.

세 명이 모든 시스템을 나눠 맡는 구조에서 한 명이 빠진다는 건 33% 인력 손실이 아니다. 그 사람이 단독으로 알고 있던 시스템의 맥락이 통째로 사라지는 것이다. HEDVION은 결제 승인 처리, 일별 정산 자동화, PG사 연동 상태 모니터링을 동시에 운영한다. 이 중 하나라도 비정상 작동할 때 "담당자한테 물어봐야 해"가 통하지 않는 상황이 분기에 두세 번은 반드시 온다. 그리고 그 순간은 언제나 예고 없이 온다.

왜 기존 방식이 결제 현장에서 더 빠르게 무너지나

슬랙 스레드와 노션 페이지로 문서화를 시도했을 때 무너진 이유는 단순히 찾기 어렵고 업데이트가 귀찮아서가 아니었다. 결제 시스템의 특성상 이슈 발생과 해결 사이의 시간이 짧고 극도로 집중적이기 때문이다. 새벽 2시에 PG사 결제 실패율이 급등하면 그 자리에서 로그 뒤지고, 재시도 로직 확인하고, PG사 어드민 접속하는 것만으로도 벅차다. "나중에 정리하겠다"는 결심은 해결이 끝난 새벽 4시에 함께 소멸한다.

더 구조적인 문제는 결제·정산 자동화 코드에는 이유 없이 보이는 예외 처리와 하드코딩된 분기가 많다는 점이다. PG사 응답 코드 중 특정 코드만 재시도하고 나머지는 즉시 실패 처리하는 로직, 특정 시간대를 피해 돌아가는 정산 배치 스케줄 — 이것들이 왜 그렇게 되어 있는지는 최초 구현자만 안다. 2주가 지나면 본인도 잊기 시작하고, 3개월이 지나면 "일단 건드리지 말자"는 블랙박스가 된다. 문서화를 별도의 작업으로 정의하는 한, 이 블랙박스는 팀이 커질수록 두꺼워진다.

세 가지 룰: 결제·정산 현장 맞춤 버전

첫 번째, ADR 한 줄 원칙 — 결제 코드에서는 실패 케이스까지

단순히 "왜 이걸 선택했나"를 남기는 것을 넘어, 결제·정산 코드에서는 "이 방식의 실패 케이스"까지 한 줄씩 남기는 것을 규칙으로 정했다. 예를 들어 PG사 웹훅 멱등성 키를 DB에 저장하는 방식을 택했다면, 커밋 메시지에 "Redis TTL 방식 검토했으나 PG사 웹훅 재전송 주기가 최대 72시간이라 TTL 관리 복잡도 증가 → DB 방식 선택"이라고 남긴다. 이 한 줄이 없으면 다음 사람은 "왜 Redis 안 썼지?"라는 의문을 가지고 그냥 바꿔버릴 수 있다. 결제 시스템에서 잘못된 멱등성 처리는 이중 결제 또는 누락 결제로 직결된다.

실제로 우리 팀에서 이 원칙 도입 전에 겪은 사례가 있다. 정산 자동화 배치에서 특정 조건 분기를 "불필요해 보여서" 제거했더니 다음 달 정산에서 약 30만 원 규모의 누락이 발생했다. 해당 분기가 왜 존재했는지 커밋 로그 어디에도 설명이 없었고, 당시 담당자는 이미 다른 작업으로 넘어가 있어서 맥락 복원에 하루가 걸렸다. ADR 한 줄만 있었어도 30분 안에 해결됐을 문제다. 30만 원의 금전 오류보다 신뢰 문제가 더 컸다.

두 번째, "내가 없으면 어떻게 되나" 분기 체크리스트

분기에 한 번, 각자 자신이 주로 다루는 시스템을 대상으로 "나 없이 나머지 둘이 새벽에 이슈가 터졌을 때 처음부터 끝까지 처리할 수 있는가"를 검토한다. 정상 운영 상태에서 처리할 수 있느냐가 아니라, 새벽 이슈 기준이다. HEDVION 기준으로 체크리스트 우선순위 상위 항목은 (1) PG사 어드민 접속 및 권한 구조, (2) 정산 배치 실패 시 수동 재처리 절차, (3) 결제 승인 실패율 급등 시 1차 진단 경로, (4) 환경별 시크릿 교체 절차다.

이 네 항목에 런북 한 페이지씩을 작성해두었고, 실제로 2025년 4분기에 담당자 부재 중 PG사 API 인증 오류가 발생했을 때 나머지 팀원이 런북만 보고 30분 내에 처리했다. 런북이 없었다면 담당자에게 연락해 설명 듣고, 어드민에서 경로 찾고, 재발급 요청까지 최소 2~3시간이 걸렸을 일이다. 분기에 한 번이라는 주기는 부담 없이 유지할 수 있으면서도 시스템이 크게 바뀌기 전에 업데이트가 가능한 간격이다.

세 번째, 온콜 노트의 생활화 — 가공하지 않는다

이슈 발생 시 타임라인을 남기는 것은 많은 팀이 시도한다. 대부분 실패하는 이유는 "이슈 해결 후 정리된 형태로 문서화하겠다"는 기준 때문이다. 그 기준이 있는 한 문서는 쌓이지 않는다. 우리가 바꾼 것은 간단하다. 날것 그대로 붙여넣는다. "01:12 배치 실패 알림 수신 → 01:15 로그 확인, DB 커넥션 풀 고갈 → 01:22 커넥션 수 조정 후 재시작 → 01:30 배치 정상 완료 / 루트 코즈: 전일 야간 대용량 쿼리로 인한 커넥션 잠식" — 이 수준이면 충분하다.

현재 우리 위키에는 이런 온콜 노트가 약 40개 쌓여 있으며, 실제로 이후 이슈 대응 시 참조된 비율은 60% 이상이다. 특히 인프라 관련 이슈는 증상이 반복되는 경우가 많아 재활용률이 더 높다. 가공하지 않아도 된다는 기준을 명시적으로 정한 것이 핵심이다. 다듬으려는 순간 그 작업이 새로운 부채가 된다.

트레이드오프: 문서화 비용 vs 공백 비용

이 세 가지 룰에도 비용이 있다. ADR 한 줄은 PR마다 30초~~2분을 추가로 쓴다. 분기 체크리스트는 한 번에 1~~2시간이 든다. 온콜 노트는 이슈 해결 중에 타이핑하는 것이 흐름을 방해한다는 느낌이 든다. 이 비용들을 부정하면 룰은 지속되지 않는다. 실제 비용이고, 팀이 감수하는 것이다.

우리가 이 비용을 감수하는 근거는 하나다. 결제 시스템에서 맥락 없이 구조를 건드렸을 때 발생하는 비용이 문서화 비용보다 수십 배 크다는 경험이다. 앞서 언급한 30만 원 정산 누락 외에도, 고객사 정산이 하루 늦어지면 신뢰 문제로 이어지고, 결제 실패율 상승은 매출 손실로 직접 이어진다. 세 명이 모든 걸 돌리는 구조에서 한 명이 이틀 빠졌을 때 나머지 둘이 결제 이슈를 처리하지 못하면, 그 피해는 문서화에 쓴 모든 시간을 합산해도 회복이 안 된다. 완벽한 문서화가 목표가 아니다. 다음 공백이 왔을 때 팀이 첫 번째 행동을 결정할 수 있는 최소한의 맥락을 남기는 것이 목표다.

당장 써먹을 실행 시사점

문서화를 "해야 한다"는 당위로 접근하면 항상 후순위가 된다. 아래는 HEDVION 방식을 그대로 가져가도 되는 구체적인 실행 단위다.

이번 주 안에:

PR description 템플릿에 Why 필드를 한 줄 추가한다. 빈칸으로 머지하면 리뷰어가 코멘트를 남기는 것을 규칙으로 만든다.
가장 최근에 발생한 이슈 하나를 골라 타임라인을 지금 당장 5줄로 적고 위키에 올린다. 가공하지 않는다.

이번 달 안에:

"내가 내일 아파서 쉬면 팀에서 처리 못 하는 것이 뭔가"를 10분 동안 적는다. 그 목록에서 가장 위험한 항목 하나에 런북을 만든다. 한 페이지면 충분하다.
결제 연동, 정산 배치, 모니터링 알림 중 담당자 의존도가 가장 높은 컴포넌트를 지정하고, 실패 시나리오를 한 페이지로 정리한다.

분기 루틴으로:

팀 전체가 30분씩 자신의 시스템을 "처음 보는 사람의 눈으로" 진단하는 세션을 캘린더에 고정한다. 결과물은 런북 추가 또는 기존 런북 업데이트다. 세션 없이 "알아서 하기"는 분기 체크리스트가 분기마다 미뤄지는 가장 흔한 이유다.

문서화는 완성하는 것이 목표가 아니다. 다음 번 공백이 왔을 때 팀이 버티는 것이 목표다. 세 명이 돌아가는 팀에서는 그 최소한이 실제로 작동해야 하고, 그러려면 습관이 시스템보다 앞서야 한다.

— by slecs