결제 연동 시점에 팀 문서 정비로 리뷰 블로킹과 런북 선제 대응

오늘 팀 문서 두 개를 정비했다. 결제 연동 작업이 어느 정도 궤도에 오른 시점에서, "지금 우리가 어디 있는지"를 명문화해두는 작업이 필요했다.

왜 지금 문서인가

코드를 짜다 보면 문서는 항상 후순위로 밀린다. 근데 팀장 입장에서 가장 크게 느끼는 건, 문서가 없을 때 생기는 비용이 코드 작성 비용보다 훨씬 크다는 거다. 특히 아래 세 가지 상황에서.

• 새 팀원이 "지금 이 프로젝트 어떤 상태예요?" 물어볼 때
• 리뷰가 블로킹된 이유를 슬랙으로 반복 설명해야 할 때
• go-live 직전에 "런북 있어요?" 소리 들을 때

이번 커밋이 딱 그 세 가지를 한꺼번에 정리한 작업이었다. CLAUDE.md에는 Polar 셋업 관련 내용을 기록했고, docs/STATUS.md에는 현재 리뷰 블로킹 상태와 go-live 런북을 담았다.

CLAUDE.md — 셋업 기록의 위치 문제

처음엔 "이걸 굳이 CLAUDE.md에 넣어야 하나?" 싶었다. 근데 생각해보면 이 파일은 이미 AI 컨텍스트 + 프로젝트 규칙 + 환경 셋업이 섞여 있는 종합 가이드 역할을 하고 있었다. Polar 셋업 과정에서 삽질한 포인트들을 여기다 박아두면, 나중에 환경 재현할 때 같은 실수를 반복하지 않아도 된다.

셋업 문서를 어디 두느냐는 팀마다 다른데, 내가 선호하는 기준은 이렇다.

이번엔 CLAUDE.md가 맞다고 판단했다. Polar 셋업은 이 프로젝트 컨텍스트에 종속된 내용이고, 외부 공개용이 아니기 때문.

STATUS.md — 리뷰 블로킹 상태를 명문화한다는 것

docs/STATUS.md에 review-blocked 상태를 기록한 게 이번 작업의 핵심이었다.

리뷰가 블로킹됐을 때 가장 흔히 일어나는 일은, 그 이유가 구두로만 떠돌다가 사라지는 것이다. "아 그거 아직 ○○ 때문에 못 올라가잖아요"라는 말이 슬랙에 흩어져 있고, 정작 다음 주에 새 팀원이 PR을 보면 왜 멈춰 있는지 모른다. 더 심한 경우엔 블로킹 사유를 잊고 merge해버리는 사고도 생긴다.

명문화의 효과는 단순하다.

## 현재 상태

- 상태: review-blocked
- 사유: [블로킹 조건]
- 해제 조건: [조건 충족 시 재개]
- 마지막 업데이트: 2026-05-26

이렇게 박아두면 PR 댓글이나 슬랙 스레드를 뒤질 필요 없이 STATUS.md 한 파일로 현황 파악이 된다. 팀 리딩하면서 느낀 건데, 상태를 관리하는 파일 하나가 있다는 것 자체가 팀원들한테 "이 프로젝트는 관리되고 있다"는 신호를 준다.

go-live 런북을 지금 쓰는 이유

런북은 보통 go-live 직전에 부랴부랴 쓴다. 근데 그러면 늦다. 직전에 쓰는 런북은 확인 절차가 빠지고, 롤백 시나리오가 부실하고, "그냥 우리가 기억하는 순서" 수준이 된다.

지금 review-blocked 상태라 어차피 배포는 못 하는 시점이다. 이 시간을 런북 작성에 쓰는 게 맞다고 봤다. 블로킹이 해제되는 순간 배포 체크리스트, 헬스체크 확인 절차, 롤백 트리거 조건이 이미 준비돼 있으면 go-live 당일 팀 스트레스가 확연히 줄어든다.

런북에 들어가야 하는 최소 항목은 대략 이렇다.

• 배포 전 체크리스트 (의존 서비스, 피처 플래그, 환경변수 확인)
• 배포 순서 (서비스 간 의존성 순서 명시)
• 헬스체크 기준 (어떤 지표가 정상인지)
• 롤백 트리거 조건과 절차
• 온콜 담당자 및 에스컬레이션 경로

변경 파일이 CLAUDE.md와 docs/STATUS.md 두 개라 stat 상으로는 작은 커밋이지만, 이런 핀포인트 문서 정비가 나중에 팀 전체 속도에 영향을 준다. 코드 커밋만 커밋이 아니다.

끝.

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

• 모니터암 쿠팡에서 보기 →
• 기계식키보드 쿠팡에서 보기 →
• 외장SSD 쿠팡에서 보기 →

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