프로젝트 종료 후 흩어진 문서들을 한 곳으로 정리
목차
어떤 프로젝트가 일단락되거나 운영 단계로 접어들 때, 그 과정에서 쌓인 설계 문서, 연동 규격서, 검증 계획 같은 것들이 클라우드 저장소 곳곳에 흩어져 있는 경우가 많다. 이번 작업은 바로 그런 상황—404_pjt 라는 프로젝트의 잔여 문서들을 정리해서 체계적으로 아카이빙한 것이다.
문서가 흩어져 있을 때의 문제
실제로 팀 내에서 "그거 규격서 어디있었더라?", "이전에 이거 검토했는데 문서가 어딨더라?" 같은 질문이 자주 나온다. 특히 여러 서비스나 결제 플랫폼 같은 외부 연동이 들어가는 프로젝트일수록 API 문서, 검증 계획, 설계 산출물이 많아지는데, 이걸 제대로 정리하지 않으면:
- 같은 질문이 반복되고
- 신입이나 인수인계 과정에서 문서를 다시 찾는 데 시간이 낭비되고
- 프로젝트 종료 후 "혹시 나중에 필요한 거 아닐까?" 싶은 불안감 때문에 여러 곳에 백업을 남기게 된다
이번에 정리한 파일들을 보면:
- 결제 시스템 관련 설계, 검증 항목들 (.claude/docs/PRODUCT_SUPPLY_DESIGN.md, welcome-pay-confirmation-items.md)
- 쿠폰 시스템 설계 문서 (마스킹된 파일명)
- 외부 서비스 API 연동 규격서 (마스킹된 파일명)
- 모바일 QR 통합 계획 (zlgoon_mobile_qr_integration_plan.md)
- 테마 검증 계획 (theme-verification-plan.md)
이렇게 흩어져 있는 문서들을 한데 모으고, 각각의 상태에 맞게 분류하는 작업을 진행했다.
어떻게 정리했나
기본 전략은 간단하다—현재 활용 중인 문서는 docs 루트에, 더 이상 참고할 일이 없거나 레거시로 전환된 문서는 archive 폴더로 이동하는 것이다. 파일명 체계도 명확하게 유지해서, 나중에 grep이나 검색 기능으로 빠르게 찾을 수 있도록 했다.
특히 여러 서비스별로 폴더가 분리되어 있는데 (예: .claude/pdf/welcome/, .claude/pdf/zlgoon/), 각각의 폴더 안에 archive 서브폴더를 두고 관련 문서들을 정렬했다. 이렇게 하면:
- 서비스별 문서의 경계가 명확해지고
- 언제든지 "이 서비스의 이전 규격서가 뭐였더라" 하는 식으로 히스토리 추적이 가능하고
- archive에 있는 문서는 "참고용"이라는 신호가 폴더 경로 자체에서 드러난다
왜 이게 중요한가
문서 정리는 코드 리팩토링만큼 중요한데도, 종종 후순위로 밀린다. 하지만 실제로는 팀의 인지 부하(cognitive load) 를 크게 줄여준다. 누군가가 "A 기능이 어떻게 설계됐더라" 궁금할 때, 문서를 빠르게 찾을 수 있으면 슬랙 질문도 줄고, 혼자 코드로 역공학하느라 시간 쓰는 일도 없어진다.
또한 프로젝트 단계별로 문서를 정리해두면, 나중에 유사한 새 프로젝트를 시작할 때 템플릿 역할이 되기도 한다. "아, 이전에 결제 시스템 연동할 때는 이렇게 검증했구나" 하면서 체크리스트를 재활용할 수 있다.
회고
이번 경험에서 느낀 건, 문서 정리 타이밍이 정말 중요하다는 것이다. 프로젝트가 한창 진행 중일 때는 문서도 계속 변하니까 정리하기 어렵다. 하지만 프로젝트가 일단락되거나 운영 단계로 넘어가는 경계 시점에 이런 정리를 하면, 깔끔하게 마무리할 수 있다.
만약 이 정리를 나중에 미루었다면, 문서들이 더 여러 곳으로 흩어졌을 거고, 누가 어떤 버전을 참고했는지 혼동하는 상황이 생겼을 것이다. 그래서 프로젝트 마일스톤마다 "문서 정리" 작은 테스크라도 넣어두는 게 도움이 된다.
또한 이런 정리를 할 때는 단순히 폴더만 바꾸지 말고, 문서 자체를 한 번 훑어보면서 정리하는 게 좋다. 마크다운 파일의 헤더를 명확하게 쓰거나, 더 이상 유효하지 않은 정보를 주석 처리하거나, 필요하면 README를 추가하는 식으로 말이다. 그럼 아카이브 문서도 자산이 되고, 나중에 "이거 왜 이렇게 설계했더라" 할 때 빠르게 맥락을 잡을 수 있다.
🛒 이 글과 어울리는 추천 상품
*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.
댓글 0
첫 댓글 달아줘.