"이거 누가 만든 거야?"

9주간 개발했다. RAG 시스템, Knowledge Graph, 멀티 에이전트, QLoRA 파인튜닝까지. 팀장님 앞에서 데모도 성공적으로 보여드렸다.

그런데 두 달 뒤, 후임자가 배정됐다.

"이 시스템 인수인계 부탁해. 김 대리가 이어받을 거야."

김 대리가 코드를 열었다.

프로젝트 폴더 구조:
├── main.py           (1,200줄, 주석 0줄)
├── utils.py          (800줄, 함수명: do_stuff, process_data, run)
├── model.py          (600줄)
├── test.py           (빈 파일)
├── requirements.txt  (없음)
└── README.md         (# 프로젝트 ← 한 줄)

김 대리의 반응:

"이거... 어떻게 실행하는 건가요?" "환경변수는 뭐가 필요한 거예요?" "이 함수가 뭘 하는 건지 모르겠는데요."

3일 후, 김 대리는 처음부터 다시 만들기로 했다.

9주간의 코드가 쓰레기통에 들어갔다. 코드가 나빠서가 아니다. 문서가 없어서다.

---

문서 없는 프로젝트의 통계

상황	결과
README 없음	신규 인원 온보딩 평균 2주 지연
API 문서 없음	프론트엔드 개발자와 매일 30분 회의 추가
아키텍처 문서 없음	시스템 장애 시 복구 시간 3배 증가
설치 가이드 없음	환경 세팅에 반나절 소모

문서는 코드의 보험이다. 코드는 6개월 후에 "남의 코드"가 된다. 심지어 내가 짠 코드도.

---

제조 AI 프로젝트, 문서가 더 중요한 이유

일반 웹 서비스와 다르다. 제조 AI는 도메인 지식이 코드 안에 녹아있다.

왜 이 온도 임계값이 85도인가?
→ "KOSHA 안전 기준서 제3장 2절에 의거"

왜 이 센서 데이터를 5분 간격으로 수집하는가?
→ "CNC 가공 사이클 타임이 평균 4.5분이므로"

왜 이 에러 코드에 이 조치를 매핑했는가?
→ "2024년 하반기 고장 이력 분석 결과"

이런 **이유(Why)**가 문서에 없으면, 후임자는 코드가 뭘 하는지는 알아도 왜 그렇게 하는지 모른다.

---

오늘 만들 문서들

문서	독자	목적
README.md	모든 사람	프로젝트 첫인상
API 문서	개발자	엔드포인트 사용법
아키텍처 문서	아키텍트/리드	시스템 구조 이해
운영 매뉴얼	운영자	배포/모니터링 절차
도메인 지식 문서	후임자	왜 이렇게 만들었는가

코드를 넘어 이야기를 남기자. 코드는 "무엇을(What)" 말하고, 문서는 "왜(Why)"를 말한다.