HANDOVER.md에 꼭 들어가야 하는 항목들

문서화와 인수인계 시리즈 2/9

인수인계 문서를 쓰려고 하면 막막하다. 무엇을 어디까지 적어야 할지 애매하다. 너무 적으면 쓸모가 없고, 너무 많이 적으면 아무도 읽지 않는다.

운영 시스템의 HANDOVER는 목적이 분명해야 한다. 새 담당자가 시스템을 이해하고, 배포하고, 장애를 확인하고, 위험한 변경을 피할 수 있어야 한다.

이 글은 운영 콘솔을 정리하면서 사용한 HANDOVER 문서 구조를 일반화한 것이다.

1. 시스템 개요

문서의 시작은 기술 스택이 아니라 시스템의 목적이어야 한다.

예를 들어 다음 질문에 답한다.

• 이 시스템은 누구를 위한 것인가
• 어떤 업무를 처리하는가
• 내부 사용자만 쓰는가, 외부 사용자도 보는가
• 데이터 원천은 어디인가
• 운영상 가장 중요한 기능은 무엇인가

좋은 개요는 한 문단으로 시스템을 설명할 수 있어야 한다.

예시:

이 시스템은 내부 운영자가 리포트와 통계 데이터를 확인하고, 오래 걸리는 파일 생성 작업을 요청하는 운영 콘솔이다. 프론트엔드는 정적 SPA로 배포되며, 조회 API와 비동기 리포트 작업은 별도 백엔드로 분리되어 있다.

이 정도만 있어도 새 담당자는 전체 방향을 잡을 수 있다.

2. 핵심 특징

시스템마다 운영상 중요한 특징이 있다.

예를 들어 다음과 같은 항목이다.

• 정적 SPA와 CDN 기반 배포
• Lambda 기반 비동기 작업
• 상주 API 서버와 DB connection pool
• 외부 폼/스프레드시트를 데이터 원천으로 사용
• S3 JSON 파일을 캐시 저장소로 사용
• 사내 SSO 쿠키 기반 인증

핵심 특징은 "이 시스템을 이해할 때 놓치면 안 되는 것"이다. 기술 스택 표보다 먼저 있어도 좋다.

3. 기술 스택

기술 스택은 표로 정리하는 편이 좋다.

예시:

영역	기술
Frontend	React, React Router
Styling	Tailwind CSS 또는 Bootstrap
Backend	Lambda, Node.js Express
Storage	S3
Database	MySQL 또는 없음
CDN	CloudFront
Auth	SSO Cookie

기술 스택을 적을 때 중요한 것은 이름만 나열하지 않는 것이다. 가능하면 각 기술이 맡는 역할을 함께 적는다.

나쁜 예:

AWS, React, Lambda, S3, CloudFront

좋은 예:

S3는 정적 파일과 JSON 스냅샷 저장소로 사용하고, CloudFront는 HTTPS 종단과 캐시 정책을 담당한다.

4. 폴더 구조

폴더 구조는 전체를 다 펼칠 필요가 없다. 운영과 개발에 의미 있는 경계만 보여주면 된다.

예시:

project/
├── src/              # 프론트엔드 소스
├── backend/          # 상주 API 서버
├── scripts/          # 배포/운영 스크립트
├── lambda_function.py
├── deploy.sh
└── README.md

중요한 파일에는 짧은 설명을 붙인다.

• lambda_function.py: 서버리스 API 진입점
• deploy.sh: 정적 SPA 배포 스크립트
• backend/: 대시보드와 분석 API 서버
• scripts/: 배포와 설정 자동화 스크립트

새 담당자는 폴더 구조에서 "어디를 봐야 할지"를 알아야 한다.

5. 주요 기능

주요 기능은 화면 경로나 API 기준으로 정리한다.

예시:

경로	기능	설명
/	대시보드	핵심 지표 조회
/reports	리포트 생성	비동기 파일 생성 요청
/history	다운로드 이력	생성된 파일과 상태 조회
/settings	설정	운영 설정 관리

내부 경로가 너무 구체적이면 공개 문서에서는 일반화해야 한다. 하지만 내부 HANDOVER에서는 실제 경로를 적는 것이 좋다.

6. 환경 설정

환경 변수는 반드시 별도 섹션으로 정리한다.

단, 실제 비밀번호나 토큰 값을 문서에 직접 적으면 안 된다. 변수명과 역할을 적는다.

예시:

API_BASE_URL=API 서버 주소
S3_BUCKET=파일 저장소 버킷
DB_HOST=데이터베이스 호스트
DB_USER=데이터베이스 사용자
DB_PASSWORD=비밀 관리자에서 확인

환경 설정 섹션에는 다음 정보가 필요하다.

• 프론트엔드 환경 변수
• Lambda 환경 변수
• Node 서버 환경 변수
• 외부 서비스 연동 값
• 비밀값을 확인하는 위치

비밀값은 문서에 쓰지 않고, 어디에서 확인해야 하는지만 적는다.

7. 배포 방법

배포 방법은 실제 명령어와 검증 방법을 함께 적는다.

예시:

npm run build
aws s3 sync build/ s3://static-assets-bucket/build/ --delete
aws cloudfront create-invalidation --distribution-id DISTRIBUTION_ID --paths "/*"

명령어만 있으면 부족하다. 다음도 함께 적어야 한다.

• 어느 디렉터리에서 실행하는가
• 배포 전에 확인할 것
• 배포 후 확인할 URL
• 캐시 무효화가 필요한지
• 데이터 파일을 덮어쓰면 안 되는지
• 실패하면 어떻게 롤백하는지

배포 가이드의 목적은 명령어를 복사하게 하는 것이 아니라 실수를 줄이는 것이다.

8. API와 데이터 저장소

운영 시스템은 데이터 흐름을 모르면 장애를 고치기 어렵다.

API는 최소한 다음처럼 정리한다.

Method	Path	용도
GET	/api/dashboard	대시보드 데이터 조회
POST	/api/reports	리포트 생성 요청
GET	/api/jobs/{id}	작업 상태 조회
POST	/api/sync	외부 데이터 동기화

데이터 저장소도 역할 중심으로 정리한다.

저장소	역할
RDB	원천 데이터와 작업 상태
S3	생성 파일과 JSON 스냅샷
Spreadsheet	외부 입력 데이터의 원천

중요한 것은 Source of Truth를 명확히 하는 것이다. 어떤 데이터가 원본이고 어떤 데이터가 캐시인지 모르면 운영 중 잘못된 곳을 수정하게 된다.

9. 트러블슈팅

트러블슈팅은 증상 중심으로 적는다.

예시:

증상	가능 원인	확인 위치	조치
화면 데이터가 갱신되지 않음	캐시 또는 동기화 실패	CDN, Lambda 로그	캐시 무효화 또는 재동기화
다운로드가 끝나지 않음	worker 실패	job table, Lambda 로그	실패 상태 확인 후 재시도
CORS 오류 발생	OPTIONS 설정 누락	API Gateway 설정	OPTIONS MOCK 확인
DB 연결 실패	보안그룹 또는 환경 변수	서버 로그	연결 정보 확인

장애 문서는 원인별보다 증상별이 좋다. 사용자는 원인을 모른 채 증상을 보고하기 때문이다.

10. 운영 주의사항

운영 주의사항은 문서에서 가장 현실적인 부분이다.

예시:

• 배포 시 데이터 경로를 덮어쓰지 않는다.
• Lambda Layer를 제거하면 파일 생성이 실패한다.
• 공개용 JSON에는 개인정보를 포함하지 않는다.
• 캐시 무효화 없이 배포하면 이전 화면이 보일 수 있다.
• 월말에는 리포트 생성 요청이 몰릴 수 있다.

이 섹션은 "왜 조심해야 하는지"까지 적는 것이 좋다. 금지 목록만 있으면 시간이 지나 이유가 사라진다.

11. 관련 문서

HANDOVER는 모든 내용을 담는 문서가 아니다. 대신 관련 문서로 연결해야 한다.

예시:

• 아키텍처 문서
• API 개발 가이드
• 배포 가이드
• CORS 해결 가이드
• Lambda 최적화 가이드
• 트러블슈팅 문서
• 용어집

관련 문서 목록은 인수인계의 네비게이션이다. 이 섹션이 없으면 문서가 흩어진다.

공개 글로 바꿀 때

HANDOVER는 내부 문서로는 구체적이어야 한다. 하지만 블로그 콘텐츠로 전환할 때는 다음을 제거한다.

• 실제 도메인
• 실제 버킷명
• 실제 API Gateway ID
• Lambda 함수명
• DB 호스트
• 쿠키명
• 내부 메뉴명
• 담당자 정보
• 실제 장애 날짜

대신 구조와 판단 기준을 남긴다.

정리

HANDOVER 문서의 목적은 새 담당자가 시스템을 이어받게 하는 것이다.

그래서 꼭 들어가야 하는 항목은 다음으로 압축된다.

• 이 시스템이 무엇인지
• 어디에 무엇이 있는지
• 어떻게 배포하는지
• 데이터는 어디서 오고 어디에 저장되는지
• 문제가 생기면 어디를 보는지
• 무엇을 조심해야 하는지

이 여섯 가지에 답할 수 있다면, HANDOVER는 단순 문서가 아니라 운영 가능한 지도에 가까워진다.

---

관련 자료: Ops Console Documentation Kit