릴리스 노트에 '수정됨' 대신 재현 조건과 확인 방법을 쓰는 이유

배포 끝나고 릴리스 노트에 "로그인 오류 수정됨" 한 줄 적고 넘어간 적이 많았어요. 직접 써 보니 이 한 줄은 나중에 아무것도 말해 주지 않더라고요. 어떤 토큰 상태에서, 어느 엔드포인트가, 무슨 응답을 돌려줬는지가 전부 빠져 있으니까요. 2주 뒤 비슷한 문의가 들어오면 그 노트는 쓸모가 없었어요.

그래서 요즘은 항목을 4칸으로 고정해서 적어요.

재현 조건은 입력과 상태를 같이 적어요

"가끔 401이 떠요"는 재현 조건이 아니에요. 만료된 액세스 토큰과 아직 유효한 리프레시 토큰을 같이 보냈을 때, 이런 식으로 상태까지 적어야 해요. 백엔드 버그는 입력값보다 그 순간의 상태 때문에 생기는 경우가 더 많거든요. DB 행이 이미 있었는지, 캐시가 비어 있었는지, 같은 요청이 몇 번 들어왔는지가 조건이에요.

플랜비 회비 납부 API 노트에 이 형식을 적용해 봤더니 조건이 꽤 또렷해졌어요. 예를 들어 같은 납부 요청이 2번 들어와 기록이 두 줄 생기는 문제라면, "동일한 멱등성 키로 POST를 2회 전송"이 재현 조건이에요. 이 문장은 그대로 회귀 테스트 이름이 돼요.

기대와 실제를 상태코드로 남겨요

고쳤다는 말 대신 전후를 숫자로 적어요. 수정 전에는 두 번째 요청도 201을 돌려주며 새 행을 만들었고, 수정 후에는 200과 함께 첫 번째 기록의 id를 그대로 돌려준다, 이렇게요. 돌려 보니 리뷰어가 코드 diff를 안 열어도 뭐가 바뀌었는지 바로 알더라고요.

확인 명령은 복사해서 바로 실행되게

여기가 제일 자주 빠지는 칸이에요. curl 한 줄과 SQL 한 줄이면 충분해요.

-- 같은 멱등성 키로 남은 납부 기록이 1건인지 확인
select count(*) from payments where idempotency_key = '<키>';

결과가 1이면 통과예요. 테스트해 보면 이 쿼리가 배포 직후 점검 체크리스트로 그대로 넘어가요. 로그 대시보드가 초록색이어도 이 숫자가 2면 배포는 실패인 거고요.

영향 범위에는 롤백 조건까지

마이그레이션이 들어갔는지, 되돌릴 수 있는지, 어떤 커밋부터인지 적어요. 커밋 해시는 7자리만 적어도 찾는 데 문제없어요. 마이그레이션이 비가역이면 그 사실 자체가 롤백 판단 기준이라 꼭 남겨야 해요.

4칸 채우는 데 5분 정도 더 걸려요. 대신 그 5분이 회귀 테스트 하나와 배포 점검 항목 하나를 덤으로 만들어 줘요. '수정됨'은 결론만 적은 문장이고, 재현 조건은 다음 사람이 검증할 수 있는 문장이에요. 라이프케어로그 플랜 시리즈처럼 혼자 여러 서비스를 굴리면 다음 사람이 결국 몇 달 뒤의 나라서, 이 습관이 생각보다 자주 저를 구해 줬어요.