README, 아키텍처 문서, HANDOVER는 역할이 다르다

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

프로젝트 문서를 정리하다 보면 모든 내용을 README에 넣고 싶어진다. 가장 눈에 잘 띄고, 새로 들어온 사람이 먼저 열어보는 파일이기 때문이다.

하지만 운영 중인 시스템에서는 README 하나로 충분하지 않다. 개발 시작을 돕는 문서, 시스템 구조를 설명하는 문서, 운영 인수인계를 위한 문서는 목적이 다르다.

문서가 목적별로 나뉘지 않으면 두 가지 문제가 생긴다.

첫째, README가 너무 길어져 아무도 끝까지 읽지 않는다.

둘째, 중요한 운영 정보가 개발 가이드 사이에 묻힌다.

세 문서의 차이

가장 단순하게 나누면 이렇다.

문서	주요 독자	답해야 하는 질문
README	처음 실행하는 개발자	어떻게 설치하고 실행하는가
아키텍처 문서	구조를 이해하려는 개발자	시스템이 어떻게 나뉘어 있고 왜 그런가
HANDOVER	운영을 이어받는 담당자	어떻게 배포하고 장애 때 어디를 보는가

세 문서는 겹치는 부분이 있다. 하지만 중심 질문이 다르다.

README는 시작점이다. 아키텍처 문서는 이해를 돕는 지도다. HANDOVER는 운영을 계속하기 위한 매뉴얼이다.

README가 해야 할 일

README는 프로젝트의 현관이다.

README에는 다음 정보가 적당하다.

• 프로젝트의 짧은 소개
• 로컬 실행 방법
• 의존성 설치
• 환경 변수 예시
• 기본 폴더 구조
• 테스트와 빌드 명령어
• 주요 문서 링크

README의 목적은 "이 프로젝트를 내 컴퓨터에서 실행할 수 있게 하는 것"이다.

따라서 README는 짧고 정확해야 한다. 모든 배포 절차, 모든 장애 대응, 모든 의사결정 기록을 README에 넣으면 오히려 시작하기 어렵다.

좋은 README는 끝에 이런 링크를 둔다.

## 관련 문서

- 시스템 아키텍처: `SYSTEM_ARCHITECTURE.md`
- 인수인계 문서: `HANDOVER.md`
- API 개발 가이드: `API_DEVELOPMENT_GUIDE.md`
- 트러블슈팅: `TROUBLESHOOTING.md`

README가 모든 것을 설명하지 않아도 된다. 대신 어디로 가야 할지 알려줘야 한다.

아키텍처 문서가 해야 할 일

아키텍처 문서는 시스템의 구조와 의사결정을 설명한다.

여기에는 다음 내용이 들어간다.

• 전체 구성도
• 주요 컴포넌트
• 데이터 흐름
• API 흐름
• 배포 구조
• 선택한 기술과 이유
• 선택하지 않은 대안
• 한계와 개선 로드맵

아키텍처 문서의 핵심은 "왜 이렇게 만들었는가"다.

예를 들어 단순히 Lambda를 사용한다고 적는 것은 부족하다. 다음처럼 적어야 한다.

리포트 생성 작업은 요청 빈도가 낮고 한 번 실행될 때 시간이 오래 걸리므로 상주 API 서버가 아니라 Lambda worker로 분리했다. 이렇게 하면 일반 조회 API와 무거운 파일 생성 작업의 장애 영향 범위를 나눌 수 있다.

이런 설명이 있어야 나중에 구조를 바꿀 때 판단 기준을 되살릴 수 있다.

HANDOVER가 해야 할 일

HANDOVER는 운영 지속성을 위한 문서다.

아키텍처 문서가 "왜 이렇게 생겼는가"를 설명한다면, HANDOVER는 "이제 어떻게 다루면 되는가"를 설명한다.

HANDOVER에는 다음 정보가 필요하다.

• 실제 배포 방법
• 운영 환경 변수
• 로그 확인 위치
• 주요 API
• 데이터 저장소
• 운영 주의사항
• 장애 증상별 확인 순서
• 관련 문서

HANDOVER는 추상적인 설명보다 실제 운영에 필요한 정확성이 중요하다.

내부 문서라면 실제 리소스 이름도 필요하다. 예를 들어 Lambda 함수명, S3 버킷명, CloudFront 배포 ID, API Gateway stage 같은 정보다.

물론 공개 글로 바꿀 때는 모두 제거해야 한다. 하지만 내부 인수인계 문서에서는 정확한 리소스명이 없으면 장애 대응 시간이 길어진다.

문서를 나누면 생기는 장점

문서를 목적별로 나누면 유지보수가 쉬워진다.

README는 로컬 실행 방법이 바뀔 때 수정한다.

아키텍처 문서는 구조나 의사결정이 바뀔 때 수정한다.

HANDOVER는 배포 절차, 운영 주의사항, 로그 위치가 바뀔 때 수정한다.

모든 내용을 한 파일에 넣으면 어떤 변경이 어느 섹션에 영향을 주는지 흐려진다. 반대로 문서의 역할이 분명하면 수정할 위치도 분명해진다.

문서가 너무 많아지는 문제

문서를 나누다 보면 반대로 너무 많아질 수 있다.

이 문제는 문서 이름과 인덱스로 해결한다.

추천 구조는 다음과 같다.

docs/
├── README.md
├── SYSTEM_ARCHITECTURE.md
├── HANDOVER.md
├── API_DEVELOPMENT_GUIDE.md
├── DEPLOYMENT_GUIDE.md
├── TROUBLESHOOTING.md
└── GLOSSARY.md

또는 루트 README에 문서 목록을 명확히 둔다.

## 문서 목록

처음 실행하려면 README를 봅니다.
시스템 구조를 이해하려면 SYSTEM_ARCHITECTURE를 봅니다.
운영을 넘겨받는다면 HANDOVER를 먼저 봅니다.
문제가 발생했다면 TROUBLESHOOTING을 봅니다.

문서가 많은 것이 문제가 아니라, 어디에 무엇이 있는지 모르는 것이 문제다.

중복은 어느 정도 허용한다

문서를 나누면 같은 내용이 조금씩 반복된다. 예를 들어 기술 스택은 README에도 있고, 아키텍처 문서에도 있고, HANDOVER에도 있을 수 있다.

이 정도 중복은 허용하는 편이 낫다.

각 문서가 독립적으로 읽힐 수 있어야 하기 때문이다.

다만 중복되는 정보의 상세 수준은 달라야 한다.

• README: React + Lambda + S3
• 아키텍처 문서: 각 컴포넌트가 왜 그렇게 나뉘었는지 설명
• HANDOVER: 실제 배포 경로, 환경 변수, 운영 주의사항

같은 정보를 같은 깊이로 반복하면 유지보수 비용이 커진다. 하지만 문맥에 맞는 짧은 반복은 독자를 돕는다.

좋은 문서 연결 방식

문서 간 링크는 단순히 목록으로 끝내지 않는 것이 좋다.

각 문서의 마지막에 "다음에 볼 문서"를 안내하면 좋다.

예시:

## 다음에 볼 문서

- 로컬 실행은 `README.md`
- 전체 구조는 `SYSTEM_ARCHITECTURE.md`
- 배포 절차는 `DEPLOYMENT_GUIDE.md`
- 장애 대응은 `TROUBLESHOOTING.md`

운영 문서의 독자는 보통 시간이 없다. 문제를 해결해야 하거나, 새로 맡은 시스템을 빨리 이해해야 한다. 링크 구조는 그 시간을 줄여준다.

공개 블로그로 바꿀 때

README, 아키텍처 문서, HANDOVER는 내부 문서다. 블로그 글로 바꿀 때는 문서의 목적 자체를 설명하는 방식이 좋다.

예를 들어 실제 문서 내용을 그대로 공개하지 않고 다음 주제로 바꿀 수 있다.

• README에 모든 것을 넣지 않는 이유
• 아키텍처 문서에 의사결정이 들어가야 하는 이유
• HANDOVER가 운영 지도 역할을 해야 하는 이유
• 트러블슈팅 문서를 증상 중심으로 쓰는 이유

내부 정보는 제거하고, 문서화 원칙을 남기는 것이다.

정리

README, 아키텍처 문서, HANDOVER는 비슷해 보이지만 역할이 다르다.

README는 시작을 돕는다.

아키텍처 문서는 구조와 이유를 설명한다.

HANDOVER는 운영을 이어가게 한다.

문서가 제 역할을 하면 프로젝트는 코드만 남는 것이 아니라, 이해하고 운영하고 바꿀 수 있는 상태로 남는다.

---

관련 자료: Ops Console Documentation Kit