문서화 안 된 프로젝트 인수인계 받은 후기

개발자 현직자 솔직 경험담

문서화 안 된 프로젝트
인수인계 받은 후기

퇴사한 개발자의 흔적만 남은 코드베이스, README 한 줄 없이 시작한 3주.

이직한 회사에서 맡은 첫 프로젝트는, 담당 개발자가 인수인계 없이 갑자기 퇴사한 서비스였다. README는 "# my-project" 한 줄이 전부였고, 커밋 메시지는 대부분 "fix", "update", "asdf" 였다. 리드는 미안한 얼굴로 이렇게 말했다. "일단 코드 보면서 파악해봐야 할 것 같아요." 그렇게 3주간의 고고학 발굴이 시작됐다.

문서화 안 된 프로젝트 인수인계 받은 후기

0줄남아있던 문서화 분량

3주전체 구조 파악까지 걸린 기간

7개발견된 미신고 버그 수

1. 첫날 — 코드베이스를 열었을 때의 막막함

프로젝트 폴더를 열었을 때 가장 먼저 든 생각은 "어디서부터 시작해야 하지"였다. 폴더 구조부터 의도를 알 수 없었다.

📁 src/

📁 components/ // 200개 넘는 파일, 하위 폴더 구분 없음

📁 utils2/ // utils는 어디에?

📁 temp_final_real/ // 실제로 이 폴더가 프로덕션에서 쓰임

📄 index.js.bak

📄 README.md // 내용: "# my-project"

utils2 폴더를 보고 처음엔 웃음이 났는데, 실제로 utils 폴더는 어디에도 없었다. 나중에 알고 보니 예전에 utils를 완전히 리팩토링하다가 중간에 멈추고, 새로 만든 utils2만 실제로 쓰이고 있었다. 죽은 코드와 살아있는 코드가 뒤섞여 있어서, 어떤 게 진짜 쓰이는지조차 구분이 안 됐다.

⚠ 그때 느낀 것 문서가 없는 것보다 더 무서운 건, 죽은 코드가 살아있는 코드처럼 남아있는 상황이었다. 실제로 실행되는 코드가 어디인지부터 확인하는 데만 며칠이 걸렸다.

2. 탐정처럼 추적한 과정 — Git 로그가 유일한 단서였다

README도, 주석도 없으니 유일하게 믿을 수 있는 건 Git 커밋 히스토리였다. 커밋 메시지는 부실했지만, 날짜와 변경된 파일 목록을 조합하면 어느 정도 맥락이 보였다.

// git log로 추적한 과정 $ git log --follow --oneline src/utils2/paymentHelper.js a3f21c9 fix 9b12e40 asdf 1e88a02 결제 관련 로직 임시 수정 (급함) 7c40f31 Merge branch 'temp_final_real' into main // 커밋 시점의 이슈 트래커 연동 확인 -> 급하게 막은 버그 흔적 발견

"결제 관련 로직 임시 수정 (급함)"이라는 커밋 메시지 하나가 실마리가 됐다. 그 커밋 전후로 변경된 파일들을 추적하니, 당시 결제 실패 문제를 땜질식으로 막아둔 흔적을 발견할 수 있었다. Git 로그가 사실상 유일한 인수인계 문서였다.

리드 뭐 좀 파악되는 거 있어요?

나 일단 결제 로직 쪽에 급하게 막아둔 코드가 있는 것 같아요. 커밋 로그 보니까 "임시 수정 (급함)"이라고 되어 있어서, 원인까지는 아직 못 찾았어요.

3. 발견한 것들 — 살아있는 시한폭탄들

2주 차에 접어들면서 코드베이스 전체를 훑는 과정에서, 실제로 위험한 코드들을 여러 개 발견했다.

발견 1

결제 실패 시 재시도 로직이 무한 루프에 빠질 수 있는 조건문. 다행히 실제로 발생한 적은 없었지만 잠재적 위험이었다.

발견 2

환경변수로 관리해야 할 API 키가 코드에 하드코딩되어 있었음. 즉시 수정 및 키 재발급 진행.

발견 3

사용하지 않는 것처럼 보였던 temp_final_real 폴더가 실제로는 프로덕션 빌드에 포함되고 있었음. 삭제했다면 서비스 전체가 멈출 뻔했다.

발견 4~7

그 외 미신고 상태였던 자잘한 버그들(날짜 형식 불일치, 중복 API 호출 등)을 정리해서 이슈로 등록.

⚠ 가장 아찔했던 순간 이름만 보고 죽은 코드라고 판단해서 삭제할 뻔한 폴더가 실제로는 프로덕션에서 사용 중이었다. 문서가 없는 코드베이스에서는 "안 쓰는 것 같다"는 추측만으로 절대 삭제하면 안 된다는 걸 온몸으로 배웠다.

4. 3주 후 — 다음 사람을 위해 남긴 것들

구조를 어느 정도 파악한 뒤, 가장 먼저 한 일은 내가 겪은 막막함을 다음 사람은 겪지 않게 만드는 것이었다. 완벽한 문서를 만들기보다, 실제로 헤맸던 지점 위주로 최소한의 기록을 남겼다.

인수인계 받았을 때

README 한 줄

폴더 구조 의도 불명, 죽은 코드와 뒤섞임

3주 후 정리한 문서

아키텍처 다이어그램 + 위험 지점 목록

"여기는 위험하니 조심" 식의 실전형 노트

// 새로 만든 README.md 일부 ## ⚠️ 주의해서 다뤄야 할 부분 - `temp_final_real/` : 이름과 다르게 프로덕션에서 실제 사용 중. 삭제 금지. - `utils2/paymentHelper.js` : 결제 재시도 로직에 잠재적 무한 루프 가능성 있음 (이슈 #142 참고) - 환경변수 미적용 구간 전수 조사 완료, 하드코딩된 키 전량 교체함 (2026-03)

1주 차 — 코드 이해도2 / 10

 

2주 차 — 코드 이해도5.5 / 10

 

3주 차 — 코드 이해도8 / 10

 

3주 후 결론

문서화 없는 코드베이스를 파악하는 건 예상보다 훨씬 오래 걸렸고, 실제로 위험한 코드를 발견할 때마다 등골이 서늘했다. 하지만 이 경험 덕분에 "내가 떠난 뒤 남을 사람"을 항상 염두에 두고 코드를 짜는 습관이 확실히 생겼다.

💡 이후로 지키게 된 습관 아무리 사소한 변경이라도 "왜 이렇게 바꿨는지"를 커밋 메시지나 PR 설명에 한 줄이라도 남기려고 한다. 완벽한 문서가 아니어도, 최소한의 맥락만 있으면 나중에 인수인계 받는 사람의 시간을 몇 주 단위로 아껴줄 수 있다는 걸 직접 겪고 나서 알게 됐다.

"문서가 없다는 건, 다음 사람의 시간을 미리 빚지고 있다는 뜻이었다."

프로젝트 규모와 팀 문화에 따라 문서화 수준에 대한 기준은 다를 수 있다. 다만 최소한 "왜 이렇게 만들었는지"와 "건드리면 위험한 부분"만이라도 남겨두면, 인수인계 상황에서 겪는 어려움을 상당 부분 줄일 수 있다는 걸 이번 경험으로 확실히 느꼈다.

결론

문서화 없이 인수인계 받은 3주는 고고학 발굴에 가까웠다. Git 로그 하나에 의지해서 코드의 의도를 추적하고, 죽은 코드와 살아있는 코드를 구분해내는 과정은 힘들었지만, 그만큼 코드베이스를 깊이 이해하는 경험이 되기도 했다. 이 경험 이후로는 내가 짜는 코드에도 최소한의 맥락을 남기는 습관을 들이게 됐다. 비슷한 상황에 놓인 개발자가 있다면, 삭제하기 전에는 반드시 실제 사용 여부부터 검증하라는 말을 꼭 전하고 싶다.

여러분도 비슷한 인수인계 경험이 있으신가요?

문서화 안 된 프로젝트를 인수받으며 겪은 경험이나 노하우가 있다면 댓글로 공유해주세요. 비슷한 상황에 놓인 다른 개발자분들께 큰 도움이 될 것 같습니다.