문서화와 인수인계 시리즈 1/9
프로젝트를 넘겨줄 때 가장 먼저 떠올리는 문서는 보통 README다. 설치 방법, 실행 방법, 폴더 구조, 주요 명령어를 적는다. README는 중요하다. 하지만 실제 운영 중인 시스템을 넘겨줄 때 README만으로는 부족하다.
운영 중인 시스템에는 코드 밖의 정보가 많다. 어디에 배포되어 있는지, 어떤 API가 어떤 저장소를 보는지, 장애가 나면 어떤 로그를 봐야 하는지, 배포할 때 어떤 파일을 건드리면 안 되는지, 특정 기능이 느릴 때 어디부터 확인해야 하는지 같은 정보다.
이런 정보는 코드만 읽어서는 바로 알기 어렵다. 그래서 인수인계 문서는 코드 설명서가 아니라 운영 지도여야 한다.
문제 상황
운영 콘솔 두 개를 정리하면서 비슷한 문제가 보였다.
하나는 외부 입력과 공개 페이지가 있는 신청 관리 콘솔이었다. 데이터 원천은 폼과 스프레드시트였고, AWS는 데이터를 캐싱하고 화면에 제공하는 역할을 했다.
다른 하나는 내부 운영자가 매일 사용하는 리포트 콘솔이었다. 내부 데이터베이스를 조회하고, 오래 걸리는 엑셀 파일을 만들고, 작업 상태를 관리해야 했다.
두 시스템 모두 React로 만든 관리자 페이지처럼 보이지만, 운영 방식은 달랐다. 하나는 파일 기반 캐시와 외부 자동화 도구가 중요했고, 다른 하나는 데이터베이스, 인증, 비동기 작업, 다운로드 산출물이 중요했다.
이런 시스템을 단순히 "프론트는 여기 있고 백엔드는 여기 있다" 정도로 넘기면 다음 담당자는 운영을 이어받기 어렵다.
README와 HANDOVER는 다르다
README는 보통 개발자를 위한 첫 진입점이다.
- 로컬 실행 방법
- 의존성 설치 방법
- 프로젝트 구조
- 주요 명령어
- 개발 시 주의사항
반면 HANDOVER는 운영을 이어받을 사람을 위한 문서다.
- 이 시스템이 무슨 일을 하는가
- 사용자는 누구인가
- 어떤 외부 시스템과 연결되어 있는가
- 배포는 어떻게 하는가
- 장애가 나면 어디를 보는가
- 데이터 원천은 어디인가
- 운영 중 절대 바꾸면 안 되는 설정은 무엇인가
README가 "개발을 시작하는 문서"라면, HANDOVER는 "내일부터 운영할 수 있게 만드는 문서"다.
HANDOVER에 먼저 들어가야 하는 것
인수인계 문서는 기술 스택보다 시스템의 역할을 먼저 설명해야 한다.
예를 들어 다음 순서가 좋다.
- 시스템 개요
- 핵심 특징
- 기술 스택
- 폴더 구조
- 주요 기능
- 환경 설정
- 배포 방법
- API와 데이터 저장소
- 트러블슈팅
- 운영 주의사항
- 관련 문서
이 순서에는 이유가 있다.
처음 보는 사람은 기술 스택보다 "이게 무슨 시스템인지"가 먼저 필요하다. 그다음 어떤 부분이 프론트엔드이고, 어떤 부분이 백엔드이고, 어떤 데이터 저장소를 쓰는지 알아야 한다.
배포 방법과 장애 대응은 뒤에 있어도 되지만 반드시 있어야 한다. 운영 문서에서 가장 위험한 공백은 "문제는 났는데 어디를 봐야 할지 모르는 상태"다.
운영 지도라는 말의 의미
운영 지도에는 경로가 있어야 한다.
예를 들어 리포트 다운로드가 멈췄다면 다음 질문에 답할 수 있어야 한다.
- 사용자의 요청은 어느 API로 들어가는가
- 작업 상태는 어디에 저장되는가
- 파일은 어디에 생성되는가
- 실패 로그는 어디에 남는가
- 수동으로 확인할 수 있는 상태값은 무엇인가
신청 데이터가 화면에 반영되지 않는다면 다음 질문에 답할 수 있어야 한다.
- 원천 데이터는 어디인가
- 동기화는 어떤 스크립트가 수행하는가
- AWS에는 어떤 형태로 저장되는가
- 캐시 때문에 늦게 보이는 것인가
- 수동 재동기화 방법이 있는가
이 질문에 답할 수 있으면 문서는 운영 지도 역할을 한다. 답할 수 없다면 문서는 아직 코드 설명에 머물러 있다.
코드에 없는 정보를 문서에 남기기
코드는 진실의 중요한 일부지만 전부는 아니다.
코드에는 보통 이런 정보가 잘 남지 않는다.
- 왜 이 구조를 선택했는가
- 어떤 대안을 선택하지 않았는가
- 어떤 운영 사고를 겪고 설정이 바뀌었는가
- 특정 배포 스크립트에서 왜 일부 경로를 제외하는가
- 어떤 로그 그룹을 먼저 봐야 하는가
- 어떤 환경 변수는 삭제하면 안 되는가
이런 정보가 사라지면 다음 담당자는 같은 시행착오를 반복한다.
운영 문서의 가치는 바로 여기에 있다. 코드를 읽으면 "무엇을 하는지"는 알 수 있지만, 문서를 읽어야 "왜 이렇게 되어 있는지"와 "문제가 생기면 어떻게 움직여야 하는지"를 알 수 있다.
인수인계 문서의 좋은 기준
좋은 HANDOVER 문서는 다음 조건을 만족한다.
- 새 담당자가 시스템의 목적을 5분 안에 이해할 수 있다.
- 로컬 실행보다 운영 배포와 장애 대응 정보가 빠지지 않는다.
- 실제 리소스 위치와 로그 확인 위치가 내부 문서에는 정확히 적혀 있다.
- 보안상 공개하면 안 되는 값과 공개 가능한 구조 설명이 구분되어 있다.
- 관련 문서로 이동할 수 있는 링크가 있다.
- 지금 당장 수정하면 위험한 운영 주의사항이 명확하다.
특히 마지막 항목이 중요하다. 인수인계에서 가장 무서운 일은 새 담당자가 선의로 정리하다가 운영 데이터를 덮어쓰거나, 캐시 정책을 바꾸거나, 필수 레이어를 제거하는 일이다.
문서는 그런 실수를 줄여야 한다.
공개 글로 바꿀 때 주의할 점
내부 HANDOVER는 정확해야 한다. 실제 도메인, 함수명, 버킷명, 로그 그룹, 배포 명령어가 필요하다.
하지만 블로그 글로 바꿀 때는 반대로 식별 정보를 제거해야 한다.
예를 들어 다음처럼 바꾼다.
| 내부 문서 | 공개 글 |
|---|---|
| 실제 콘솔 이름 | 운영 콘솔 |
| 실제 도메인 | console.example.com |
| 실제 API URL | api.example.com |
| 실제 버킷명 | static-assets-bucket |
| 실제 쿠키명 | internal-auth-token |
| 실제 DB명 | operations_db |
중요한 것은 리소스 이름이 아니라 판단 기준이다. 공개 글에서는 "무엇을 썼다"보다 "왜 그렇게 나눴다"를 남기는 편이 안전하고 가치 있다.
다시 정리하면
인수인계 문서는 코드 설명서가 아니다.
코드는 시스템의 현재 상태를 보여준다. 하지만 운영 문서는 시스템을 어떻게 다뤄야 하는지 알려준다.
좋은 HANDOVER는 새 담당자에게 다음 세 가지를 준다.
- 시스템의 전체 지도
- 장애가 났을 때 확인할 경로
- 함부로 바꾸면 안 되는 운영 주의사항
프로젝트를 잘 마무리한다는 것은 코드를 끝내는 것만이 아니다. 누군가 이어받아도 같은 품질로 운영할 수 있게 만드는 것이다.
그 첫 문서가 HANDOVER다.