오너십을 코드에 다는 법

결제·정산 코드에서 "아무도 모르는 파일"이 생기는 순간

결제 시스템을 운영하다 보면 "이 코드, 건드려도 되는 거야?"라는 질문이 생각보다 자주 나온다. PG사 콜백 처리 로직, 정산 배치, 환불 자동화 스크립트 — 이런 코드는 잘못 건드렸을 때 실제 돈이 움직이거나 멈춘다. HEDVION처럼 결제·정산·자동화를 직접 운영하는 팀에서 코드 오너십은 "누가 리뷰할 것인가"의 문제가 아니라, 장애가 났을 때 누가 즉시 판단할 수 있는가의 문제다.

"작은 팀이니까 다들 안다"는 전제는 빠르게 무너진다. 우리 팀은 3명이지만, 6개월 전에 만든 정산 집계 쿼리를 지금 누구도 자신 있게 설명하지 못했던 순간이 있었다. git blame을 뒤져보면 세 명 중 아무도 기억 못 하는 코드가 의외로 많다. 소규모이기 때문에 오히려 "누군가가 알겠지"라는 착각이 쉽게 생기고, 그 착각이 쌓여 실제 운영 리스크가 된다.

오너십 공백이 만드는 두 가지 실제 비용

오너십이 없을 때 발생하는 비용은 두 가지 형태로 나타난다. 첫 번째는 장애 대응 지연이다. PG사 웹훅이 갑자기 400 에러를 뱉기 시작했을 때, "이 핸들러 누가 만들었지?"를 파악하는 데 15분이 걸렸다. 정산 자동화처럼 이 15분이 수십 건의 주문 상태 불일치로 이어질 수 있는 환경에서 15분의 판단 공백은 단순한 불편이 아니다.

두 번째는 수정 회피다. 코드 맥락을 모르는 사람은 건드리지 않으려 한다. 결제 로직처럼 사이드 이펙트가 겁나는 영역일수록 더하다. 실제로 리팩터링이 필요하다는 걸 알면서도 6주 동안 손을 못 댄 환불 처리 모듈이 있었다. "잘못 바꿨다가 환불이 이중으로 나가면?"이라는 공포가 오너십 부재와 결합하면 기술 부채가 가속화된다. 이 두 비용을 합산하면, 오너십 없이 운영하는 것은 단순히 불편한 수준이 아니라 직접적인 운영 리스크다.

파일 단위 주석: 가장 낮은 비용의 첫 번째 단계

우리가 처음 시도한 건 파일 상단 주석이다. 형식은 단순하게 유지했다.

# owner: mings
# last-major-change: 2026-03-15
# purpose: 외부 PG사 콜백 처리 어댑터
# risk-level: HIGH — 잘못 수정 시 결제 상태 꼬임

여기서 핵심은 risk-level을 추가한 것이다. 오너십만큼이나 중요한 정보는 "이 코드가 얼마나 위험한가"다. 결제 관련 코드 전부가 위험한 건 아니다 — PG사 웹훅 검증 로직은 HIGH, 어드민 대시보드 통계 쿼리는 LOW로 구분했다. 이 레이블 하나만으로 팀원이 수정 전에 얼마나 신중하게 접근해야 하는지 맥락을 잡을 수 있다.

주석 도입 후 3주 만에 변화가 생겼다. 코드 리뷰 요청 시 담당자가 첫 번째 리뷰어가 되는 비율이 올라갔고, "이거 왜 이렇게 짰어?"라는 사후 질문 대신 "이 부분 의도가 뭐야?"라는 사전 대화가 늘었다. 운영 맥락에서는 이 대화 시점의 차이가 크다. 사후에 발견하면 이미 머지된 코드고, 사전에 발견하면 PR에서 막을 수 있다.

CODEOWNERS: 규약을 자동화로 바꾸기

주석이 수동 규약이라면, CODEOWNERS는 이를 자동화한다. GitHub·GitLab 양쪽에서 지원하며, PR에서 해당 경로가 변경되면 지정된 담당자가 자동으로 리뷰어에 추가된다.

# CODEOWNERS
/src/payment/          @mings
/src/settlement/       @mings
/src/infra/            @slecs
/src/automation/       @slecs
/.github/workflows/    @slecs @mings   # 인프라 변경은 공동 리뷰 필수

여기에 GitHub branch protection rule의 "Require review from Code Owners"를 활성화했다. 결제·정산 경로의 파일 변경은 담당자 승인 없이 머지가 불가능해진다. 이 설정이 실제로 한 번 잠재적 장애를 막았다 — 자동화 스크립트 의존성을 업그레이드하는 PR이 settlement 경로를 건드렸는데, 담당자 리뷰 과정에서 해당 라이브러리의 breaking change가 발견됐다. 단순한 의존성 업그레이드처럼 보였지만, 정산 소수점 처리 방식이 바뀌는 변경이었다.

트레이드오프: 오너십이 병목이 되는 순간

오너십 제도의 가장 큰 위험은 담당자가 병목이 되는 것이다. 작은 팀에서는 특정 인물이 자리를 비울 때 문제가 생긴다. 실제로 결제 담당자가 며칠 자리를 비웠을 때, CODEOWNERS 리뷰 요구가 긴급 핫픽스 배포를 막는 상황이 생겼다. 이건 오너십 제도의 실패가 아니라, 우회 규칙을 미리 만들지 않은 운영 실수였다.

이 문제를 풀기 위해 두 가지 규칙을 추가했다. 첫째, EMERGENCY 레이블이 붙은 PR은 담당자 승인 없이 다른 팀원 1명의 승인으로 머지 가능하되, 담당자에게 즉시 Slack 알림이 간다. 둘째, 모든 HIGH risk 파일은 2명 이상이 컨텍스트를 공유해야 한다는 "no single point of knowledge" 원칙을 두었다. 실제로 2인이 함께 페어 리뷰를 해야 CODEOWNERS에서 공동 담당자로 등록되는 방식으로 구현했다. 오너십은 접근을 막는 것이 아니라 주도권의 위치를 명확히 하는 것 — 이 구분이 팀에서 받아들여질 때만 제도가 지속 가능하다.

지금 당장 쓸 수 있는 4단계 적용 시나리오

코드 오너십 제도를 처음 도입할 때 가장 중요한 건 완벽한 설계가 아니라 빠른 시작이다. 우리가 실제로 거친 순서를 그대로 공유한다.

1단계 (1일): 가장 "위험한" 5개 파일을 골라 상단 주석(owner, risk-level, purpose)을 추가한다. 결제 콜백 핸들러, 정산 집계 로직, 자동화 트리거 스크립트가 우선순위다. 전체 코드베이스를 한 번에 커버하려 하지 말 것.

2단계 (1일): 저장소 루트에 CODEOWNERS 파일을 만든다. 처음엔 세분화하지 말고 큰 디렉토리 단위로만 나눈다. 완벽한 매핑보다 파일이 존재하는 것 자체가 중요하다.

3단계 (설정 10분): GitHub branch protection에서 "Require review from Code Owners"를 켠다. main 브랜치만이라도 먼저 적용한다. 여기서 EMERGENCY 우회 레이블 규칙도 함께 정의한다.

4단계 (2주 후 회고): 어떤 PR에서 담당자 리뷰가 실질적으로 도움이 됐는지, 어디서 병목이 생겼는지 팀이 함께 본다. 이 시점에 CODEOWNERS 매핑을 조정하고, 필요하면 "no single point of knowledge" 원칙을 HIGH risk 파일부터 적용한다.

결제·정산 시스템에서 오너십은 편의의 문제가 아니다. 장애 대응 속도, 변경의 신뢰성, 팀원 간 신뢰 — 모두 오너십이 얼마나 명확한가에서 나온다. 파일 하나에 주석 한 줄 다는 데 1분도 안 걸린다. 오늘 가장 무서운 파일부터 시작하면 된다.

— by mings