수수료 최소값과 비교 기준값을 정책 문서에서 명확히 분리

정책 문서를 정리하다 보면 "이름이 비슷하게 생긴 값 두 개"가 한 파일 안에 공존하는 상황을 꽤 자주 만난다. 이번에 내부 정책 문서에서 '비교 기준값'과 '플랫폼 수수료 최소값'을 명확히 분리하는 작업을 했는데, 단순히 이름을 고친 게 아니라 각 값이 어디에 속하고 무엇을 책임지는지 문서 수준에서 선언하는 작업이었다. 생각보다 배운 게 많아서 남겨둔다.

두 가지 값의 혼동이 왜 생기나

시스템 어느 도메인에든 '기준'이라는 단어는 여러 맥락에서 나타난다. 비교 기준값(A)은 특정 조건을 판단할 때 쓰는 임계값이고, 플랫폼 수수료 최소값(B)은 거래에서 부과되는 수수료의 하한선이다. 서로 전혀 다른 개념인데, 초기 문서를 작성한 사람은 맥락을 알고 있어서 '기준'이라는 단어를 두 곳에 자연스럽게 썼을 것이다.

문제는 6개월, 1년 뒤에 시작된다. 새로 합류한 개발자가 문서를 빠르게 훑으면서 두 값을 동의어처럼 읽는다. 아니면 기존 팀원이라도 코드베이스가 커지면서 "이 변수 이름 어디서 봤더라?" 하고 혼동하기 시작한다. 특히 두 값의 타입이 같거나(예: 둘 다 number) 값 범위까지 비슷하면, 코드를 잘못 읽어도 즉시 오류가 터지지 않는다. 런타임에 조용히 틀린 결과를 내는 종류의 버그다.

혼동이 고착화되는 패턴 중에 이런 것이 있다. 초기에 A와 B가 우연히 같은 값이었던 시기가 있다. 그 시기에 짠 코드 중 일부가 A를 써야 하는 자리에 B를 쓰고 있어도 결과가 같으니 아무도 눈치채지 못한다. 이후 둘 중 하나만 정책 변경으로 수정됐을 때 버그가 드러나는 구조. 더 불편한 건, 그 버그가 테스트에서 안 잡히고 운영 단계에서 특정 케이스에서만 나타나는 경우다. 명확한 개념 분리는 이 시나리오 자체를 원천적으로 차단한다.

온보딩 초기에 문서를 빠르게 읽은 개발자가 특히 취약하다. 처음엔 "이 두 값이 비슷한 거 아닌가?" 싶어도 바쁘게 돌아가는 환경에서 물어보기 망설여지고, 그냥 둘 중 하나를 골라 쓰게 되는 경우가 생긴다.

분리 작업에서 실제로 한 것

이번 작업의 핵심은 각 값이 어떤 '책임(responsibility)'을 가지는지 문서에 명시하는 것이었다.

단순히 이름을 고치는 데서 멈추지 않고, 각 값 옆에 어느 도메인이 소유하는 값인지, 변경 시 영향도 분석을 어디까지 해야 하는지를 명시했다. 구조로 보면 이런 방향이다.

# 정책 문서 예시 (실제 구조 단순화)
comparison_threshold:
  owner: "비즈니스 로직"
  affects: ["조건 분기", "등급 분류"]
  note: "수수료 계산과 무관. 변경 시 분기 로직 전체 영향도 분석 필요."

platform_fee_minimum:
  owner: "정산 도메인"
  affects: ["결제 처리", "정산 배치"]
  note: "비교 임계값과 별개. 변경 시 정산 도메인 테스트 필수."

이렇게 구조화해두면 나중에 어느 값을 수정할 때 어느 부분을 봐야 하는지 문서 자체가 안내한다. 영향도 분석의 출발점 역할을 하는 셈.

코드 레벨에서도 상수 이름을 같이 정리했다.

// 변경 전 - 맥락 없이 'threshold', 'minimum' 혼용
const THRESHOLD = policy.threshold;
const MIN_FEE = policy.min;

// 변경 후 - 이름 자체가 도메인 귀속을 드러냄
const COMPARISON_THRESHOLD = policy.comparisonThreshold;
const PLATFORM_FEE_MINIMUM = policy.platformFeeMinimum;

이름이 길어지는 건 사실이다. 그런데 코드 리뷰에서 "수수료 계산하는데 여기서 왜 COMPARISON_THRESHOLD를 쓰지?"라는 질문이 즉시 나온다. 이름만으로 맥락이 틀렸다는 게 보이니까. 리뷰어가 도메인 전문가가 아니어도 이름에서 "이건 수수료 관련이 아닌 값이다"를 읽어낼 수 있다.

개념 분리가 예방하는 것들

이번 작업을 하면서 정리한, 명확한 분리가 실질적으로 막아주는 문제들:

• 두 값이 우연히 같을 때 조용히 숨어 있던 버그가 정책 변경 시 수면 위로 올라오는 패턴
• 새 팀원이 온보딩 문서를 빠르게 읽으면서 두 개념을 하나로 묶어 이해하는 오독
• 코드 리뷰에서 잘못된 값 참조를 즉시 잡을 수 있는 조건 형성
• 정책 변경 요청이 들어왔을 때 "어느 값을, 어디까지" 수정할지 협의 비용 감소

역으로 "꼭 분리해야 하나?"를 고민할 때는 이 기준을 써볼 수 있다. 두 값의 변경 권한이 같은 팀에 있고, 영향 범위가 완전히 겹치고, 앞으로도 동기화해서 움직일 가능성이 높다면, 굳이 분리하는 게 오히려 관리 포인트를 늘리는 셈이 된다. 분리의 핵심은 "변경 사이클과 소유권이 다르다"는 사실이 전제일 때 의미를 갖는다.

회고

문서화는 코드 변경만큼 중요하다는 말은 많이 한다. 그런데 실제로 그만큼 공을 들이는 경우는 드물다. 특히 정책·비즈니스 규칙이 얽혀 있는 값들은 코드보다 문서에서 먼저 혼동이 시작된다는 걸 이번에 다시 실감했다.

.claude/CLAUDE.md 같은 운영 문서는 초기에만 쓰이는 게 아니다. 6개월 뒤에 "어라, 이 로직 왜 이렇게 짰더라?"라고 다시 읽게 되는 파일이고, 그때 잘 정리된 문서 하나가 몇 시간의 추적 작업을 아껴준다. 당장 급하게 돌아가는 스프린트 안에서는 "나중에 정리하자"가 되기 쉽지만, 나중에 그 부채를 갚는 비용은 꽤 비싸다.

이번 작업을 하면서 느낀 건, 개념 분리는 선언적인 행위라는 것. "이 두 개는 다른 것이다"라고 이름 짓고 문서에 명시하는 순간, 그 이후의 모든 코드와 리뷰와 협의가 그 기준 위에서 이뤄진다. 버그를 고치는 게 아니라 버그가 생길 맥락 자체를 없애는 것. 총괄 팀장 포지션에서 이런 작업을 주도하는 이유가 거기 있다. 누군가 "이 두 값 뭐가 달라요?"라고 물어오기 전에, 물어볼 필요가 없는 구조를 만드는 것.