게임 개발자를 위한 Markdown 파이프라인과 기술 문서화 노하우
기획부터 빌드, QA, 라이브 운영까지 흩어지기 쉬운 게임 개발 지식을 Markdown 중심으로 정리하는 방법을 소개합니다. 저장소와 함께 관리할 수 있는 문서 구조, 검토 흐름, 실전 템플릿을 다룹니다.
왜 게임 개발 문서는 쉽게 낡을까
게임 프로젝트에는 기획서, 밸런스 표, 씬 구성, 에셋 규칙, 빌드 절차, 버그 재현 방법처럼 서로 다른 성격의 정보가 빠르게 쌓입니다. 문서가 특정 메신저 대화나 개인 노트에 남으면 새 팀원이 맥락을 찾기 어렵고 코드와 문서의 변경 시점도 분리됩니다.
Markdown은 이 문제를 모두 해결하는 도구는 아니지만 텍스트 기반이라 변경 이력을 추적하기 쉽고 Git 저장소와 함께 관리하기 좋습니다. 코드 리뷰와 비슷한 방식으로 문서 변경도 검토할 수 있다는 점이 특히 유용합니다.
문서의 기준점을 저장소 가까이에 둔다
문서가 코드와 강하게 연결된다면 같은 저장소의 docs/ 디렉터리에 두는 편이 효과적입니다. 반대로 세계관 원문, 대규모 내러티브 자료, 외부 협력사와 공유하는 계약 문서는 접근 권한과 편집 방식이 다른 경우가 많으므로 별도 문서 시스템에 두고 링크만 연결하는 편이 안전합니다.
다음처럼 목적별로 나누면 문서를 찾는 비용을 줄일 수 있습니다.
/docs
/architecture # 시스템 구조와 기술 결정 기록
/gameplay # 게임플레이 규칙과 구현 메모
/production # 빌드, 배포, 에셋 제출 절차
/qa # 테스트 계획과 재현 절차
/decisions # ADR(Architecture Decision Record)
README.md # 문서 진입점과 색인중요한 원칙은 폴더 수를 늘리는 일이 아니라 진입점을 명확히 만드는 일입니다. docs/README.md에는 새 구성원이 가장 먼저 읽어야 할 문서, 현재 사용하는 빌드 절차, 문서 작성 규칙을 짧게 연결해 두는 것이 좋습니다.
문서도 변경 흐름에 포함한다
코드 변경이 게임의 동작이나 작업 절차를 바꾼다면 해당 변경에는 문서 갱신 여부를 확인하는 항목이 필요합니다. 이를 PR 템플릿이나 작업 완료 기준에 넣으면 문서화가 프로젝트 막바지의 별도 업무가 되는 일을 줄일 수 있습니다.
flowchart LR
A[이슈 또는 작업 카드] --> B[구현과 문서 초안]
B --> C[PR 또는 변경 검토]
C --> D{동작·절차가 바뀌었는가?}
D -- 예 --> E[관련 Markdown 갱신]
D -- 아니오 --> F[변경 사유 기록]
E --> G[병합과 배포]
F --> G이 흐름에서 핵심은 모든 변경에 긴 문서를 요구하지 않는 것입니다. 예를 들어 내부 함수 이름만 바뀌었다면 관련 문서가 없음을 확인하는 것으로 충분합니다. 반면 세이브 데이터 형식, 조작 방식, 콘텐츠 제작 절차가 바뀌었다면 사용자가 따라 할 수 있는 문서까지 함께 수정해야 합니다.
게임 개발에 잘 맞는 문서 유형
기술 결정 기록: 짧고 되돌아볼 수 있게
ADR은 “무엇을 선택했는가”보다 “왜 이 선택을 했는가”를 남기는 데 적합합니다. 엔진 플러그인, 네트워크 방식, 데이터 포맷처럼 나중에 다시 논의될 가능성이 큰 주제에 사용하면 좋습니다.
# ADR-012: 퀘스트 데이터에 JSON을 사용한다
## 상태
채택
## 맥락
퀘스트 작성자는 프로그래머 외에도 있으며 로컬 도구와 CI에서 데이터를 검증해야 한다.
## 결정
런타임 로딩용 퀘스트 데이터는 JSON으로 저장하고 스키마 검증을 CI에 추가한다.
## 대안
- ScriptableObject: Unity 편집 경험은 좋지만 외부 검증과 차이 비교가 불편하다.
- CSV: 단순 표에는 적합하지만 분기와 중첩 조건 표현이 제한적이다.
## 결과
콘텐츠 작성 도구에서 JSON 생성과 검증 오류 표시를 지원해야 한다.ADR은 결정을 뒤집을 수 없게 만드는 문서가 아닙니다. 이전 결정이 현재 조건과 맞지 않으면 새 ADR로 대체하고 기존 문서에는 대체된 기록을 남기면 됩니다.
재현 가능한 작업 절차: 사람이 아닌 조건을 쓴다
빌드나 버그 재현 문서에는 “에디터에서 실행한다” 같은 표현보다 버전, 대상 플랫폼, 필요한 권한, 기대 결과를 적는 편이 좋습니다. 다른 사람이 같은 결과에 도달할 수 있어야 절차 문서가 됩니다.
## Android 개발 빌드 생성
### 사전 조건
- Unity Hub에 프로젝트에서 요구하는 Unity 버전이 설치되어 있다.
- Android SDK, NDK, OpenJDK 경로가 Unity 설정에 등록되어 있다.
- `keystore.properties`가 로컬 보안 저장소의 값을 가리킨다.
### 절차
1. `Build/Development` 프리셋을 선택한다.
2. Scripting Backend가 IL2CPP인지 확인한다.
3. Build 버튼을 누르고 `Artifacts/Android/`에 APK를 생성한다.
### 확인
설치 후 시작 화면의 버전 문자열이 빌드 번호와 일치해야 한다.비밀 키, 계정 정보, 실제 토큰은 Markdown에 넣지 않습니다. 대신 필요한 권한을 얻는 위치와 비밀 값이 주입되는 방식만 설명합니다.
링크와 코드 조각을 오래 유지하는 방법
문서의 링크는 시간이 지날수록 깨지기 쉽습니다. 저장소 안의 문서는 상대 경로를 우선 사용하고 외부 도구나 위키 링크는 문서의 문맥상 꼭 필요한 경우에만 넣는 편이 관리하기 쉽습니다. 코드 조각은 복사해 실행할 수 있는 수준으로 유지하거나 그렇지 않다면 의사 코드임을 분명히 표시해야 합니다.
또한 파일명에는 날짜보다 주제를 사용하세요. 2026-07-build-guide.md보다 android-development-build.md가 검색과 재사용에 유리합니다. 날짜는 변경 이력과 문서 상단의 상태 정보로 충분히 관리할 수 있습니다.
검토 가능한 문서 템플릿
새 문서를 만들 때 아래 틀을 사용하면 목적과 최신성을 빠르게 확인할 수 있습니다.
## 목적
이 문서가 해결하는 질문을 한 문장으로 적는다.
## 대상 독자
이 문서를 읽고 작업할 사람과 전제 지식을 적는다.
## 사전 조건
도구, 권한, 설정, 입력 데이터를 적는다.
## 절차 또는 규칙
실행 순서와 예외 조건을 적는다.
## 검증 방법
성공과 실패를 판단할 수 있는 결과를 적는다.
## 관련 자료
코드 경로, 이슈, ADR, 외부 문서 링크를 적는다.
## 마지막 확인
YYYY-MM-DD — 확인한 사람 또는 팀마지막 확인 항목은 형식적인 서명이 아니라 신뢰도 표시입니다. 오래된 문서도 삭제하기보다 현재 검증되지 않았음을 표시하면 팀은 내용을 맹신하지 않고 필요한 부분을 갱신할 수 있습니다.
작게 시작하는 운영 규칙
처음부터 모든 정보를 Markdown으로 옮길 필요는 없습니다. 다음 세 가지만 정해도 파이프라인이 작동하기 시작합니다.
- 빌드와 배포 절차는 저장소 가까이에 둔다.
- 기술적 선택은 ADR로 남긴다.
- PR 검토 때 동작 또는 절차 변경에 따른 문서 갱신을 확인한다.
문서화의 목표는 기록량을 늘리는 것이 아니라 필요한 사람이 필요한 순간에 믿을 수 있는 답을 찾게 하는 것입니다. 게임이 커질수록 좋은 Markdown 문서는 단순한 메모가 아니라 팀의 개발 속도와 온보딩 품질을 지키는 기반이 됩니다.
