시나리오: 결제·정산 팀
결제·정산 도메인에서 하네스가 승인, 정합성 검증, 감사 추적, rollback 시스템으로 작동하는 방식을 설명합니다.
핵심 요약
- 결제·정산 하네스는 생산성 도구가 아니라 사고 확률과 손실 반경을 줄이는 financial correctness 통제 시스템입니다.
- approval policy, reconciliation check, audit trail, rollback plan이 load-bearing 요소입니다.
- reconciliation은 "실행됨"으로 끝나지 않고, input fixture·expected ledger·actual result를 비교해 단위·세금 반올림·환불 상태 불일치를 잡아냅니다.
- 가격·정산 규칙·환불 처리·회계 필드 변경은 human_gate로 분리하고 risk-classification.yaml을 강제합니다.
- 30일 도입은 가격·환불·정산 변경에 risk-classification을 붙이고 reconciliation-report 없이는 merge를 막는 것입니다.
결제·정산 팀은 하네스가 없으면 가장 위험해지는 팀에 속합니다. 이 도메인에서 "대충 맞는 것 같다"는 곧장 사고로 이어집니다.
문제 구조
- 금전 처리 로직의 작은 오류가 직접 손실로 이어짐
- 변경 후 즉시 눈에 안 보여도 정산 시점에 사고가 드러날 수 있음
- 감사 로그와 승인 근거가 사후에 필요함
- 배포 전에 사람이 봐야 할 변경이 명확해야 함
load-bearing 하네스 요소
| 요소 | 왜 중요한가 |
|---|---|
| approval policy | 위험 변경을 자동화 범위에서 분리 |
| reconciliation check | "실행됨"이 아니라 "맞게 반영됨"을 확인 |
| audit trail | 나중에 누가 어떤 판단을 했는지 복원 가능 |
| rollback plan | 실수했을 때 빠르게 되돌릴 수 있어야 함 |
권장 루프
아티팩트 구조 예시
pricing-rules.md
ledger-invariants.md
approval-policy.md
risk-classification.yaml
reconciliation-report.md
audit-log.md
rollback-plan.md
approval policy 예시
payments_change:
auto:
- "운영 문서 수정"
review_required:
- "테스트/fixture 변경"
- "정산 화면 UI 변경"
human_gate:
- "가격 로직 변경"
- "정산 규칙 변경"
- "환불/취소 처리 변경"
- "회계/세무 관련 필드 변경"reconciliation check 예시
reconciliation:
compare:
- "input fixture"
- "expected ledger output"
- "actual persisted result"
fail_if:
- "minor unit mismatch"
- "tax rounding mismatch"
- "refund state transition mismatch"왜 이게 엔지니어링인가
결제 하네스는 사실상 financial correctness engineering입니다.
- 구현 결과를 fixture와 ledger invariant로 검증합니다.
- 승인을 human gate로 분리합니다.
- audit trail을 남겨 나중에 검증할 수 있게 합니다.
- rollback을 설계에 포함합니다.
이 도메인에서 하네스는 생산성 보조도구가 아니라 사고 확률과 손실 반경을 줄이는 통제 시스템입니다.
자주 망하는 패턴
| 실패 패턴 | 하네스로 막는 방식 |
|---|---|
| 금액 계산 변경을 일반 코드 수정처럼 취급 | risk classification으로 고위험 분리 |
| 테스트는 통과했지만 정산 결과가 틀림 | reconciliation report 필수화 |
| 나중에 왜 승인했는지 모름 | audit log와 approval note 남김 |
| rollback이 배포 후에야 논의됨 | 작업 시작 시 rollback plan 작성 |
30일 도입 순서
- 가격/환불/정산 변경은 모두
risk-classification.yaml을 붙인다. reconciliation-report.md없이는 merge하지 않도록 고정한다.- human gate가 필요한 변경 범위를 문서가 아니라 workflow로 연결한다.