1. 프로젝트 개요 문서 (Overview)
목적
- 이 프로젝트가 무엇을 해결하는지
- 어디에 쓰이는지
- 어떤 제약이 있는지
포함 내용
- 프로젝트 목적 / 비즈니스 배경
- 주요 기능 요약
- 현재 버전 및 릴리즈 이력
- 전체 아키텍처 다이어그램
- 외부 의존성 (라이브러리, SDK, OS 등)
- 지원 플랫폼 (Windows, Linux, macOS 등)
- 주요 제약 사항 (성능, ABI, 메모리, 실시간성 등)
이 문서는 전체 그림을 이해시키는 역할을 합니다.
2. 빌드 & 개발 환경 문서
목적
포함 내용
- 필수 개발 환경
- 컴파일러 (MSVC 19.xx, GCC xx, Clang xx)
- C++ 표준 (C++17, C++20 등)
- 필수 패키지 / 외부 라이브러리 버전
- CMake 옵션 / 빌드 스크립트 설명
- Debug / Release 차이
- ABI 옵션 (wchar_t, STL, 런타임 등)
- 빌드 시 자주 발생하는 문제와 해결법
- CI/CD 구조 설명
이 문서가 없으면 인수인계는 실패합니다.
3. 디렉터리 구조 설명서
목적
예시:
/core → 핵심 엔진
/ui → UI 레이어
/platform → OS별 구현
/instrument → 내부 디버깅 / 로깅
/tests → 테스트 코드
각 디렉터리의 역할을 간결히 설명합니다.
4. 아키텍처 설계 문서 (중요)
포함 내용
- 전체 레이어 구조
- 주요 클래스 관계도 (UML 권장)
- 핵심 설계 패턴
- Observer
- Command
- Factory
- PImpl
- 객체 생명주기
- 메모리 소유권 구조
- 스레딩 모델
- 이벤트 흐름
특히 C++은 소유권과 lifetime 설명이 없으면 유지보수자가 고통받습니다.
5. 핵심 모듈 상세 설명
모든 파일 설명은 필요 없습니다.
대신 다음을 설명합니다.
- 시스템의 중심 클래스
- 변경 위험이 큰 부분
- 이해하기 어려운 알고리즘
- 역사적 이유로 남아있는 코드
예시:
MatrixTransform.cpp의 역할- Editor Read-only 모드 구조
- UTF 변환 처리 구조
- 플랫폼별 분기 로직
6. API / 인터페이스 문서
외부에서 사용하는 API가 있다면 다음을 포함합니다.
- 공개 헤더 설명
- 파라미터 의미
- 예외 처리 정책
- Thread-safe 여부
- ABI 주의사항
가능하면 Doxygen 스타일로 자동 생성 가능하게 작성합니다.
7. 테스트 전략 문서
- 유닛 테스트 범위
- 통합 테스트 방법
- 수동 테스트 시나리오
- 성능 테스트 방법
- 재현 방법이 필요한 주요 버그 목록
8. 운영 / 배포 문서
- 배포 프로세스
- 버전 관리 전략
- 브랜치 전략 (Git flow 등)
- 릴리즈 체크리스트
- 핫픽스 절차
9. 리스크 & 기술 부채 문서 (매우 중요)
인수인계에서 가장 가치 있는 문서입니다.
- 리팩토링 필요 영역
- 위험한 코드
- 구조적 한계
- 언젠가 문제가 될 수 있는 부분
- 제거 예정 레거시
이 문서가 없으면 다음 사람이 지뢰를 밟습니다.
10. FAQ / 트러블슈팅
- 빌드 실패 원인 Top 5
- 특정 환경에서만 발생하는 문제
- 플랫폼별 주의점
- 자주 하는 질문
최소 세트 (시간 없을 때)
시간이 부족하다면 최소한 다음 5개는 작성합니다.
- 프로젝트 개요
- 빌드 가이드
- 아키텍처 설명
- 핵심 모듈 설명
- 기술 부채 목록
잘 작성하는 팁
- 왜 이렇게 설계했는가를 반드시 기록
- 코드 복붙 금지
- 다이어그램 적극 활용
- 새로운 사람이 3일 안에 이해 가능해야 함
- PDF 한 파일보다 Wiki 구조 권장
CategoryDocument