Show Cover Slide

커밋으로는 온보딩되지 않는다 — 스타트업에서 지식은 왜 사라지는가

1. 시작점: 지식 관리의 부재

스타트업에서 코드와 기능은 빠르게 쌓입니다.
하지만 지식은 어디에 쌓이고 있을까요?

문서화는 늘 다음 단계로 밀려납니다.
그리고 결국 누군가는 말합니다:

“이건 커밋으로 남겨뒀어요.”

이는 단순한 선택이 아닙니다.
사실은 지식을 구조화하고 전달할 방법을 갖추지 못했기 때문입니다.
Wiki는 방치되고, Notion은 산만해지며, Confluence는 무거워서 접근성이 떨어집니다.
결국 개발자들은 코드 커밋과 PR을 지식 저장소처럼 사용하기 시작합니다.

겉으로 보기엔 문제가 없어 보입니다.
어차피 코드는 가장 정확한 진실이고, 커밋은 모든 변경의 히스토리를 담고 있으니까요.

그러나 문제는 단순히 정보의 존재 여부가 아니라 정보의 접근성, 연결성, 그리고 문맥성에 있습니다.

커밋은 정보의 “물리적 저장”일 수는 있어도, 그 자체로는 지식 전달의 구조가 아닙니다.

지식은 결국 공유되어야 의미가 있습니다.
그리고 커밋은 공유되지 않는 정보를 양산하는 비의도적 아카이브에 불과할 수 있습니다.

2. 커밋은 저장이지만, 전달이 아니다

어떤 개발자는 커밋 메시지에 깊은 애정을 쏟습니다.
기능 변경의 배경, 시스템 간 영향, 테스트 결과, 심지어 비즈니스 도메인의 고민까지 담아냅니다.

refactor: reduce query overhead by rewriting join logic in report generation
context: this is due to S3 sync lag during Q2 load testing, see incident #241

이처럼 구조적이고 책임감 있는 커밋은 분명 훌륭한 기록입니다.
그러나 시간이 지나면, 이 기록은 아무도 찾지 않는 독백이 됩니다.

왜 그럴까요?

검색되지 않는다

커밋 메시지는 Git 내부의 로그로 남아 있지만, 일상적인 지식 검색 흐름에서는 노출되지 않습니다.
개발자는 Stack Overflow, Wiki, Notion, 슬랙을 먼저 찾지 git log부터 열람하진 않습니다.
즉, 커밋은 존재하되 발견되지 않습니다.

구조화되어 있지 않다

커밋은 시간 순서대로 나열됩니다.
하지만 지식은 맥락 순서로 접근되어야 의미가 있습니다.
특정 기능의 탄생, API 구조의 선택, 성능 최적화의 맥락은 주제 중심으로 구조화된 형태에서 비로소 전달력을 갖게 됩니다.

연결되지 않는다

커밋 메시지는 링크될 수 없습니다.
PR이나 Wiki, 문서에 하이퍼링크로 연결되지 않는 커밋은 그 자체로 고립된 기록입니다.
지식은 연결될 때 의미가 생기고, 흐름이 만들어질 때 온보딩과 회고가 가능해집니다.

해석되지 않는다

코드와 커밋은 진실이지만, 그 진실을 해석하는 사람이 없다면 의미가 없습니다.
“이 커밋은 왜 이렇게 작성되었을까?”를 설명해줄 사람 없이 남겨진 기록은, 결국 고립된 유산입니다.

커밋은 기술적으로는 완벽한 변경 이력을 담고 있지만, 지식 전달이라는 맥락에서는 기능하지 않습니다.

그 결과, 아무리 정성껏 쓴 커밋이라도 시간이 지나면 회복되지 않는 지식으로 사라집니다.

많은 개발자들이 커밋 메시지를 실용적으로 인식합니다.
저 역시 실무에서는 커밋 로그를 코드를 비교(diff)하기 위한 기준점, 즉 변경 지점을 빠르게 식별하기 위한 태그처럼 작성하고 있습니다.

이런 방식은 변경 추적에는 유용하지만, 지식의 맥락이나 설계 의도를 전달하기엔 명백한 한계가 있습니다.
그 자체로는 지식이 아니며, 구조화된 전달을 위한 추가 흐름이 필요합니다.

3. PR도 결국 같은 운명

PR(Pull Request)은 팀 내 협업의 핵심 도구입니다.
설계 의도와 구현 내용을 설명하고, 리뷰어와의 논의를 통해 품질을 높이며,
최종적으로는 변경을 공식화하는 과정입니다.

하지만 스타트업처럼 빠르게 변화하고 인력이 자주 교체되는 조직에서는
PR조차도 기록이 아닌 소모성 커뮤니케이션 도구로 전락하기 쉽습니다.

PR은 머지되면 잊힌다

많은 PR이 이렇게 마무리됩니다:

“LGTM”
“머지할게요!”
(그리고 끝)

PR 본문에는 의도, 대안, 고려사항이 빼곡히 적혀 있었지만,
누구도 다시 그 PR을 열어보지 않습니다.

PR의 맥락은 보존되지 않는다

PR은 단기적인 검토와 피드백에는 탁월한 도구지만,
장기적인 온보딩이나 설계 회고에는 적합하지 않습니다.

• PR은 기능 단위로 나뉘고
• 리뷰는 해당 시점의 문맥에만 집중되며
• 기록은 문서화로 전환되지 않습니다

그 결과, 몇 달이 지나면 이 PR은 “무엇을 왜 이렇게 구현했는지”를 설명해주지 못하는
머지된 커밋 묶음 그 이상도 이하도 아닌 것이 됩니다.

리포지토리의 무주공산화

스타트업에서는 특정 리포지토리를 처음 만든 개발자가 팀을 떠나는 일이 잦습니다.
그 순간부터 해당 리포는 사실상 주인이 없는 공간이 됩니다.

• 남겨진 커밋과 PR은 아무도 해석하지 못하고
• 신규 팀원은 같은 문제를 다시 고민하고
• 기존 설계의 의도는 ‘알 수 없는 이유로 이렇게 된 것’으로 취급됩니다

결과적으로, PR로 저장한 지식은 살아있는 문서가 아니라, 방치된 고서가 되어버립니다.

PR은 지식의 전달 경로가 아닙니다.
PR은 잠깐의 리뷰 흐름이고, 지식을 전달하려면 그 이후의 구조화가 필수적입니다.

4. 지식의 구조가 없다면, 온보딩은 고통이다

스타트업에서 신규 개발자가 팀에 합류하면, 가장 먼저 부딪히는 벽은 문서의 부재입니다.
문서가 없으니, 커밋과 PR을 뒤져야 하고, 그것도 안 되면 사람을 찾아다니며 물어야 합니다.

결국 이렇게 됩니다:

“왜 이렇게 설계된 건가요?”
“흠… 4개월 전 PR 보시면 아마…”
“그거 쓴 사람 지금은 없어요.”

이건 온보딩이 아니라 디지털 고고학입니다.

온보딩 문서는 ‘경험’이 아니라 ‘탐험’이 된다

잘 구조화된 온보딩 문서는 지식의 입구가 되어야 합니다.

• 이 시스템은 왜 이렇게 만들어졌는가?
• 이 기능의 과거 히스토리는 어떤 맥락에서 결정되었는가?
• 어떤 선택지가 있었고, 왜 지금의 설계를 선택했는가?

하지만 이런 정보는 대부분 흩어져 있습니다.
PR, 커밋, 회의록, 슬랙 메시지…
의사결정의 흔적은 있지만, 연결된 흐름은 없습니다.

그래서 온보딩은 하나의 흐름이 아니라
산산이 흩어진 조각을 모아 조립하는 퍼즐 게임이 됩니다.

히스토리를 공유하지 않으면, 같은 결정을 반복한다

역사적 맥락을 공유받지 못한 신규 인원은,
이전 팀이 고민했던 똑같은 문제를 다시 고민하게 됩니다.

• 이미 포기한 구조를 다시 제안하고
• 이미 해결된 문제를 또다시 분석하며
• 이미 실패한 접근을 반복합니다

이는 곧 조직의 생산성 저하이자, 기술적 결정의 퇴보입니다.

온보딩의 고통은 문서화의 부재가 아니라,
지식이 구조화되어 있지 않기 때문에 발생합니다.

5. 지식은 왜 사라지는가

기록은 했습니다.
커밋 메시지에도, PR 설명에도, 간헐적인 회의록에도…
그런데, 시간이 지나면 아무도 그 내용을 기억하지 못합니다.

왜 우리는 지식을 저장했음에도, 그것을 잃어버리는 걸까요?

1. 지식은 ‘시간순’이 아니라 ‘문맥순’으로 접근된다

Git은 시간 순서대로 히스토리를 나열합니다.
그러나 사람은 그렇게 생각하지 않습니다.

• 나는 ‘이 기능이 왜 이렇게 되어 있는지’를 알고 싶은 것이지,
• ‘3개월 전 누가 어떤 커밋을 먼저 했는지’는 중요하지 않습니다.

지식은 기능 단위, 도메인 단위, 의사결정 단위로 엮여야 비로소 의미를 갖습니다.
시간은 저장의 기준일 뿐, 전달의 기준이 될 수 없습니다.

2. 지식은 ‘기록’이 아니라 ‘해석’되어야 한다

설령 커밋이나 PR에 기록이 남아 있다고 하더라도,
그것이 해석되지 않으면 지식이 아닙니다.

• 문서로 구조화되지 않았고
• 온보딩 가이드로 연결되지 않았으며
• 질문에 대한 답변으로 등장하지 않는다면

그 기록은 실질적으로 사라진 것과 다르지 않습니다.

3. 지식에는 ‘책임자’가 없다

스타트업에서는 책임자가 자주 바뀌고,
리포지토리의 오너십이 흐려지기 쉽습니다.

그 결과:

• 설계를 누가 했는지, 왜 그렇게 했는지 아무도 모릅니다
• 이슈가 발생해도, 그 구조를 해석할 사람이 없습니다
• 남겨진 것은 해석 불가능한 기록뿐입니다

기록의 유실이 아니라, 해석자의 부재가
지식 소실의 본질적인 원인입니다.

지식은 단순히 어딘가에 ‘존재’한다고 해서 유효한 것이 아닙니다.
검색되고, 연결되고, 해석되어야
비로소 조직의 자산이 됩니다.

6. 우리는 무엇을 바꿔야 하는가

지식을 잃지 않으려면, 기록 방식뿐 아니라 기록 이후의 흐름과 구조를 바꿔야 합니다.
단순히 “문서화를 잘하자”는 이야기로는 바뀌지 않습니다.
지식이 조직 내에서 살아 움직일 수 있는 흐름을 설계해야 합니다.
다음 나오는 내용은 정답을 말하는 것은 아닙니다.
하나의 예시이며, 고민해야 하는 방향입니다.

A. 지식의 흐름을 만든다

지식은 한 번에 완성되지 않습니다.
커밋 → PR → 설계 기록(ADR) → Wiki → 온보딩 문서로 이어지는
다단계 흐름을 갖추는 것이 중요합니다.

각 단계는 다음과 같은 역할을 갖습니다:

• 커밋: 변경 사실의 저장
• PR: 변경의 의도와 논의
• ADR (Architecture Decision Record): 결정의 이유, 대안, 포기한 선택
• Wiki/Notion: 장기적 구조화된 전달
• 온보딩 문서: 초입에 서 있는 사람을 위한 경로

이 흐름은 완벽하지 않아도 됩니다.
중요한 건 “정보를 사용자에게 전달하기 위한 구조”가 존재하느냐입니다.

B. 구조화된 기록 문화를 도입한다

• PR 템플릿에 “설계 의도 / 대안 / 관련 링크”를 포함합니다.
• ADR (의사결정 기록)을 텍스트 기반으로 작성해두고, Wiki에 연결합니다.
• GPT 요약 도구나 자동 문서화 툴을 도입해 반복 비용을 줄입니다.

중요한 건 지식이 작성되기 쉽게 하는 구조를 고민하는 것 입니다.
장기적인 전달을 전제로 하지 않으면, 결국 아무도 문서화하지 않습니다.

C. 조직 차원의 책임자 또는 역할이 필요하다

“지식은 모두의 책임”이라는 말은 옳지만, 현실적이지 않습니다.
아무도 책임지지 않으면, 아무도 하지 않습니다.

따라서 다음과 같은 방식이 필요합니다:

• 리포지토리/도메인별 오너 지정 (설계/문서/온보딩 관리)
• 스프린트 종료 시 “지식 전달 확인” 단계 추가
• 분기마다 “설계 회고 / 문서 리팩토링 주간” 운영

이런 작업은 단기 성과로 이어지지 않지만,
지식의 누수를 막고, 팀의 지속가능성을 높이는 핵심 구조입니다.

스타트업은 빠르게 움직여야 합니다.
하지만 지식 없이 빠르게 움직이는 조직은, 결국 같은 실수를 반복하며 제자리걸음을 하게 됩니다.

지식의 속도는, 기록의 깊이가 결정합니다.

7. 마무리 메시지

우리는 바쁘다는 이유로,
아니면 이미 코드에 담았다는 이유로
지식의 구조화를 미룹니다.

하지만 지식은 단순히 기록되어 있다고 해서 전달되지 않습니다.
지식은 구조 속에 있어야 살아남습니다.
그 구조는 검색 가능하고, 연결 가능하며, 새로운 사람에게 해석 가능한 형태여야 합니다.

기억되지 않는 기록은, 없는 것과 같습니다

아무리 정성껏 작성한 커밋이라도,
아무리 논의가 활발했던 PR이라도,
시간이 지나면 모두 잊힙니다.

그 기록이 살아남으려면,
그 지식이 조직을 움직이게 하려면,
기록에서 구조로, 구조에서 흐름으로 이어져야 합니다.

기술 부채보다 더 위험한 것 — 지식 부채

기술 부채는 리팩토링으로 갚을 수 있습니다.
하지만 지식 부채는 기록이 사라지면 되돌릴 수 없습니다.

• 과거의 의도를 해석할 수 없어 동일한 논의를 반복하고
• 오너 없는 코드에 손대기 두려워하며
• 결국 개발 속도는 점점 늦어지고

이는 단순히 생산성 문제를 넘어
조직 전체의 학습 능력과 지속 가능성을 위협합니다.

커밋은 코드를 저장하지만, 지식은 구조가 저장합니다.
전달되지 않는 기록은, 결국 사라진 설계 의도일 뿐입니다.