프로젝트 스냅샷 문서로 버그 맥락과 DB 상태를 팀에 남기는 법
목차
STATUS.md 하나 추가했다. 13개 커밋, 5개 버그 픽스가 쌓인 시점의 스냅샷.
왜 지금 STATUS.md인가
프로젝트가 어느 정도 진행되면 반드시 오는 시점이 있다. 코드는 돌아가는데 "지금 이 프로젝트 어디까지 왔어요?"라는 질문에 답하기 위해 PR 목록을 뒤지거나, 커밋 로그를 한 줄씩 읽어야 하는 상황. 나한테 그 시점이 오늘이었다.
13개 커밋이 쌓였다. 그 안에 버그 픽스가 5개. 비율로 보면 전체 커밋의 38%가 픽스다. 뭔가 잘못 짠 게 아니라, 실제로 돌려보면서 발견되는 류의 버그들이었고, 그걸 고치면서 동시에 DB 상태도 몇 번 바뀌었다. 이 흐름을 누군가가 나중에 따라와야 한다면, 커밋 로그만으로는 컨텍스트가 너무 부족하다는 걸 깨달았다.
팀 리딩을 하다 보면 문서화 타이밍이 의외로 중요하다는 걸 느낀다. 너무 초반에 쓰면 금방 outdated가 되고, 너무 늦게 쓰면 기억이 흐릿해진다. 지금처럼 "버그 픽스 싸이클 한 바퀴 돌고 DB 상태가 안정됐을 때"가 사실 스냅샷 찍기 가장 좋은 타이밍이다.
STATUS.md에 담아야 하는 것들
단순히 "현재 완성된 기능 목록"을 나열하는 게 아니라, 다음 사람이 이 시점부터 이어받았을 때 필요한 것들을 담는 게 목표였다.
- 현재 DB 상태: 어떤 테이블이 있고, 마이그레이션이 어디까지 적용됐는지
- 버그 픽스 요약: 어떤 문제가 있었고 어떻게 해결됐는지 (커밋 메시지만으론 부족한 맥락)
- 진행 중인 커밋 흐름: 총 13개 커밋의 큰 흐름, 무엇이 왜 이 순서로 들어갔는지
- 알려진 이슈 / 다음 스텝: 지금 이 스냅샷 이후에 뭘 해야 하는지
특히 DB 상태 기록은 귀찮다고 자꾸 미루게 되는데, 나중에 "이 컬럼이 언제 생겼지?", "이 인덱스 원래 있던 거야?" 같은 질문이 나오기 시작하면 이미 늦은 거다. 마이그레이션 파일이 있어도, 현재 어떤 상태인지에 대한 서사가 없으면 결국 코드 다 까봐야 한다.
버그 5개가 주는 신호
5개의 버그 픽스를 STATUS.md에 정리하면서 패턴을 다시 봤다. 버그는 그냥 실수가 아니라 설계 의도와 실제 동작 사이의 갭이다. 각각의 픽스가 왜 발생했는지 한 줄이라도 적어두면 나중에 비슷한 버그가 생겼을 때 "이거 전에도 있었던 패턴인데"라고 빨리 인식할 수 있다.
## Bug Fixes (5)
| # | 커밋 | 현상 | 원인 요약 |
|---|------|------|-----------|
| 1 | ... | ... | ... |
...
이런 식으로 표 하나 만들어두면, 코드리뷰 때도 "이 부분 이전에 비슷한 버그 있었어요, STATUS.md 참고하세요"라고 링크 하나 던질 수 있다. 리뷰어 입장에서도 맥락이 생기고, 작성자 입장에서도 같은 실수를 반복하지 않게 된다.
문서도 코드처럼 관리해야 한다
md/ 디렉터리에 STATUS.md를 넣은 것도 의식적인 선택이었다. 루트에 던져두면 나중에 README.md랑 섞여서 무엇이 살아있는 문서이고 무엇이 아카이브인지 구분이 안 된다. md/ 아래에 두면 "여기 있는 문서들은 프로젝트 내부 상태 관련"이라는 암묵적 컨벤션이 생긴다.
문서 관리에서 팀장이 신경 써야 하는 건 "문서를 누가 쓰느냐"가 아니라 "문서가 어디 있는지 모두가 아는 구조를 만드느냐"다. 내가 이번에 STATUS.md를 직접 만든 건, 이 패턴을 팀에 심기 위한 목적도 있다. 다음 마일스톤에서는 내가 아닌 다른 팀원이 자연스럽게 스냅샷 문서를 추가할 수 있도록.
13개 커밋, 5개 픽스. 숫자는 작지만 이 시점의 상태를 기록해두는 것 자체가 다음 사이클의 속도를 올린다. 그게 STATUS.md 한 파일의 역할이다.
다음엔 커밋이 더 쌓이기 전에 미리 찍어야겠다.
🛒 이 글과 어울리는 추천 상품
*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.
댓글 0
첫 댓글 달아줘.