정산 도메인 규칙 분산을 단일진실로 통합 관리

도메인별 지침이 여러 곳에 흩어져 있는 문제를 정리했다. 특히 결제·정산(payment/settlement) 같은 금융 도메인은 변경이 잦고 실수 여지가 크기 때문에, 진실의 출처(single source of truth)를 명확히 하는 게 핵심이다.

문서 분산의 비용

팀 규모가 커질수록 문서가 여러 곳에 복제되면:

• 온보딩할 때 어디가 최신 버전인지 못 찾는다
• 코드리뷰에서 같은 규칙을 다르게 해석한다
• 한 곳 갱신을 빠뜨리면 팀원마다 다른 지침을 따른다

특히 정산 도메인은:

• 수수료 계산, 정산 주기, 수정 규칙 등이 정확해야 한다
• 금융 감사 대상이라 "지침 버전"이 명확해야 한다
• 여러 어댑터(payment-adapter 같은)가 같은 규칙을 참고해야 하므로, 하나가 틀리면 연쇄 오류가 난다

내가 겪었던 케이스도 비슷했다. PR 리뷰할 때마다 정산 규칙이 어디 정의돼 있는지 추적하느라 시간을 잃었고, 팀원들이 같은 개념을 두 가지 다르게 이해하는 일도 있었다. 정산처럼 "자주 바뀌지만 정확해야 하는" 도메인일수록 이 문제가 심하다.

구조: 계층형 진실의 출처

이번 작업으로 정리한 구조다:

.claude/CLAUDE.md (최상위 진실의 출처)
  ├─ 공통 규칙 (모든 프로젝트·봇)
  ├─ 세부 지침은 각 서브 디렉토리로 위임
  │
  ├─ .claude/rules/
  │   ├─ db-migration.md (데이터베이스 변경 규칙)
  │   ├─ payment-adapter.md (결제 어댑터 규칙)
  │   └─ settlement-domain.md (정산 도메인 단일진실) ← 새로 중앙화
  │
  ├─ .claude/skills/settlement-fee/
  │   └─ SKILL.md (정산 수수료 자동화 스킬)
  │
  └─ .claude/docs/
      └─ api-reference.md (API 참고)

이전엔 정산 규칙이 여러 곳에 산재되어 있었다. API 스펙은 api-reference, 데이터베이스 규칙은 db-migration, 비즈니스 로직은 어딘가 주석으로… 이래선 안 된다고 느꼈다.

변경 파일별 역할

특히 settlement-domain.md 를 전담으로 두면서, payment-adapter.md 같은 관련 도메인도 그곳으로 참고를 일원화했다.

팀 온보딩·코드리뷰 비용 감소

이전:
- PR 리뷰어가 "이 규칙이 어디 정의돼 있지?" 하면서 여러 파일을 찾아 다닌다
- 정산 담당자와 백엔드 담당자의 지침 버전이 달라서 리뷰가 꼬인다
- 신입이 온보딩할 때 "정산 규칙은 이 파일… 아니 저 파일…" 하면서 헤맨다

지금:
- "settlement-domain.md 봐" 한 줄로 끝난다
- 코드리뷰에서 일관된 기준을 적용할 수 있다
- API 변경, DB 스키마 변경도 api-reference.md, db-migration.md 로 일원화되어 리뷰 비용이 떨어진다

결과적으로 같은 일의 반복 설명이 줄었고, 새로운 팀원이 "정산 도메인을 이해하려면 여기 봐" 라고 명확하게 안내할 수 있게 됐다.

회고: 도메인별 지침 관리의 요점

이 정도 문서 작업은 보통 "써놓고 끝" 인데, 내 생각에 중요한 건 세 가지다.

첫째, 진실의 출처를 먼저 정한다. "이 도메인의 유일한 기준은 이 파일" 을 명시하고, 다른 곳은 그곳으로 링크만 건다. 복제(duplication)는 최악의 기술 부채다. 한 줄 빠진 것도 팀마다 다른 해석으로 이어진다.

둘째, 변경이 잦은 도메인일수록 중앙화한다. 정산처럼 비즈니스 규칙이 자주 바뀌는 영역이야말로 한곳에 모여야 동기화 누락이 없다. 반대로 거의 안 바뀌는 것(예: 레거시 호환성 규칙)은 분산되어 있어도 괜찮다.

셋째, 팀 성장 속도에 맞춘다. 현재 팀 규모가 "누군가는 지침 위치를 모름" 수준이라면, 이런 구조화가 ROI가 있다. 너무 미리 하면 오버 엔지니어링이 되고, 너무 늦으면 이미 기술 부채가 쌓여 있다.

좀 더 팀이 커지면 이런 지침들이 CLAUDE.md 외부 시스템(wiki, 설계 문서, 스키마 정의)으로도 확산될 텐데, 그때까지는 이 정도 구조로 일관성을 유지하는 게 현실적이다.

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

• 모니터 쿠팡에서 보기 →
• 기계식키보드 쿠팡에서 보기 →
• 사무의자 쿠팡에서 보기 →

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