#!markdown # 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개는 작성합니다. 1. 프로젝트 개요 2. 빌드 가이드 3. 아키텍처 설명 4. 핵심 모듈 설명 5. 기술 부채 목록 --- # 잘 작성하는 팁 - **왜 이렇게 설계했는가**를 반드시 기록 - 코드 복붙 금지 - 다이어그램 적극 활용 - 새로운 사람이 **3일 안에 이해 가능**해야 함 - PDF 한 파일보다 **Wiki 구조** 권장 ---- CategoryDocument