# CTO로서의 역할에 대한 고찰 - v2: 기술 문서화 체계 설계

> 작성일: 2025-12-10
> 대상: 내부 팀원
> 시리즈: CTO 업무 정립 과정 2/10

## v1에서의 깨달음

v1에서 나는 "내가 내일 갑자기 사라져도 팀이 계속 돌아갈 수 있는가?"라는 질문을 던졌다. 그 답의 첫 번째 키워드가 **문서화**다.

문서화는 지루하다. 개발자들은 문서 쓰기를 싫어한다. 나도 그렇다. 코드 짜는 게 훨씬 재미있다. 하지만 문서가 없으면 지식은 휘발된다. 사람이 바뀌면 맥락이 사라진다.

그래서 문서화는 필수다. 하지만 **모든 것을 문서화할 수는 없다**. 그렇다면 무엇을 문서화해야 하는가?

## 문서화의 원칙

문서를 만들기 전에 원칙을 정해야 한다. 원칙 없이 만든 문서는 금방 낡아 쓸모없어진다.

### 원칙 1: 문서는 살아있어야 한다
한 번 쓰고 방치되는 문서는 거짓말이 된다. 코드가 바뀌었는데 문서가 안 바뀌면 오히려 혼란을 준다.
- **해결책**: 문서를 업데이트하는 프로세스를 만든다

### 원칙 2: 문서는 찾기 쉬워야 한다
좋은 문서도 못 찾으면 없는 것과 같다.
- **해결책**: 문서의 위치와 구조를 표준화한다

### 원칙 3: 문서는 목적이 명확해야 한다
"일단 써두자"는 문서는 아무도 안 읽는다.
- **해결책**: 각 문서의 독자와 목적을 명시한다

### 원칙 4: 완벽함보다 존재가 낫다
완벽한 문서를 만들려다 결국 안 만드는 것보다, 70% 문서라도 있는 게 낫다.
- **해결책**: 작은 문서부터 시작하고 점진적으로 개선한다

## 필수 문서 목록

우리 같은 작은 팀에 꼭 필요한 문서만 추린다면?

### 1. README.md (프로젝트 개요)
**목적**: 새로운 사람이 프로젝트를 이해하는 첫 문서
**포함 내용**:
- 프로젝트가 무엇인지
- 로컬에서 어떻게 실행하는지
- 주요 기술 스택
- 문서 위치 안내

**왜 필요한가**: 신규 팀원이 첫 날부터 혼자 환경을 셋업할 수 있어야 한다.

### 2. ARCHITECTURE.md (시스템 아키텍처)
**목적**: 시스템이 어떻게 구성되어 있는지 이해
**포함 내용**:
- 시스템 구성도
- 주요 컴포넌트와 역할
- 데이터 흐름
- 외부 서비스 연동

**왜 필요한가**: 새 기능을 어디에 추가해야 할지, 문제가 생기면 어디를 봐야 할지 알아야 한다.

### 3. DEPLOYMENT.md (배포 가이드)
**목적**: 배포를 일관되고 안전하게 수행
**포함 내용**:
- 배포 전 체크리스트
- 배포 절차 단계별 설명
- 롤백 방법
- 배포 후 검증 방법

**왜 필요한가**: 배포는 자주 하는 작업이고, 실수하면 장애로 이어진다.

### 4. TROUBLESHOOTING.md (장애 대응)
**목적**: 흔한 문제의 해결 방법 공유
**포함 내용**:
- 자주 발생하는 문제와 해결법
- 로그 확인 방법
- 긴급 연락처
- 과거 장애 이력

**왜 필요한가**: 같은 문제를 매번 처음부터 디버깅할 수는 없다.

### 5. DEVELOPMENT.md (개발 가이드)
**목적**: 일관된 코드 품질 유지
**포함 내용**:
- 코딩 컨벤션
- Git 브랜치 전략
- PR 작성 가이드
- 테스트 작성 규칙

**왜 필요한가**: 여러 사람이 협업할 때 일관성이 필요하다.

### 6. ONBOARDING.md (온보딩 체크리스트)
**목적**: 신규 팀원의 빠른 적응
**포함 내용**:
- 첫 주에 할 일 목록
- 필수 계정 발급 목록
- 읽어야 할 문서 순서
- 알아야 할 도메인 지식

**왜 필요한가**: 팀원 한 명 늘어날 때마다 같은 설명을 반복할 수는 없다.

## 문서 관리 전략

문서는 만드는 것보다 유지하는 게 어렵다. 어떻게 관리할 것인가?

### 위치: 코드와 함께
문서는 코드 저장소에 함께 둔다. 별도 위키나 Notion에 두면 점점 동기화가 안 된다.
```
/project-root
  ├── README.md
  ├── docs/
  │   ├── ARCHITECTURE.md
  │   ├── DEPLOYMENT.md
  │   ├── TROUBLESHOOTING.md
  │   ├── DEVELOPMENT.md
  │   └── ONBOARDING.md
  └── src/
```

### 업데이트: PR에 포함
코드를 바꾸면서 관련 문서도 함께 업데이트한다. PR 리뷰에 "문서 업데이트 했나요?" 체크 항목을 넣는다.

### 검토: 분기별 리뷰
3개월마다 문서가 최신 상태인지 검토한다. 오래된 내용은 수정하거나 삭제한다.

## 다음 단계: 실행 계획

이론은 충분하다. 이제 실행이다:

**1주차**: README.md 작성
- 각 프로젝트의 기본 정보 정리
- 로컬 실행 방법 문서화

**2주차**: DEPLOYMENT.md 작성
- 현재 배포 방법 정리
- 체크리스트화

**3주차**: ARCHITECTURE.md 작성
- 시스템 구성도 그리기
- 주요 컴포넌트 설명

**4주차**: 나머지 문서 작성
- TROUBLESHOOTING.md
- DEVELOPMENT.md
- ONBOARDING.md

한 번에 다 만들 필요 없다. 한 주에 하나씩, 실제로 필요한 순서대로 만든다.

## 다음 편 예고

v3에서는 **개발 프로세스 및 협업 방식**에 대해 고민할 것이다:
- Git 브랜치 전략은 어떻게?
- PR 리뷰는 어떻게 할 것인가?
- 코딩 컨벤션은?
- 테스트 전략은?

프로세스는 문서보다 더 중요하다. 프로세스가 있어야 문서도 살아있다.

## 마치며

문서화를 "나중에 할 일"로 미루면 영원히 안 한다. 지금 시작해야 한다. 완벽하지 않아도 된다. 있는 것과 없는 것의 차이가 크다.

다음 주부터 README.md 작성을 시작하겠다. 한 달 후면 기본적인 문서 체계가 갖춰질 것이다.

---

**글자 수**: 약 2,100자
**다음 편**: v3 - 개발 프로세스 및 협업 방식 정립