새로운 팀에서의 첫 2주 회고
온보딩 문서화부터 토큰 유출 대응, CI 힙 메모리 개선까지. 새 팀에 적응하며 보낸 2주를 돌아봅니다.
최근에 이직을 하고, 즐겁게 업무를 하며 지내고 있습니다. 입사한 지 2주 정도 지났고, 제가 작업한 코드가 처음으로 프로덕션에 나가는 기쁜 경험도 했습니다. 지난 2주 동안의 업무를 돌아보며 들었던 생각들을 정리해봅니다.
1. 문서화
저는 업무에 적응하는 과정을 기록해서 온보딩 프로세스를 문서로 남겼습니다. 회사에서 진행되는 공식 프로세스 이후 구두나 슬랙으로 전달받은 내용을 정리하고, 각 프로젝트는 claude의 eli5 스킬을 사용해 간략하게 학습했습니다. 예전과 달리 AI를 활용할 수 있으니, 개발자의 온보딩 프로세스도 이런 식으로 변해가는 게 좋겠다는 생각이 들었습니다.
기술 스택 버전처럼 너무 상세한 내용은 금방 낡아버려 관리되지 않기 때문에, 프로젝트에 대한 간략한 설명과 세팅 과정 위주로 문서화하고 그 내용을 바탕으로 저도 다시 복습했습니다. 프로젝트 전체를 처음부터 다시 분석하는 과정만 줄여줘도 꽤 큰 기여가 될 수 있겠네요.
이직하면서 가장 들이고 싶었던 습관이 바로 문서화였습니다. 이전 회사를 떠날 때 가장 마음에 걸렸던 건, 문서가 부족한 탓에 새로 오신 개발자분이 이슈의 맥락을 파악하기 어려웠다는 점이었거든요. 그리고 업무를 하거나 대화를 나눌 때 언제나 기록을 남기시던 두 시니어 개발자분의 모습을 닮고 싶기도 했습니다. (cc. 우노, 곤잘레스 감사합니다.)
2. 업무
팀마다 다르겠지만, 제가 속한 팀은 신규 입사자에게 특정한 업무를 바로 주지는 않았습니다. 팀원들은 모두 신규 피처 개발이나 이슈 대응을 하고 있어서, 저는 그 외적인 부분에 먼저 기여해보고 싶었습니다.
1. 보안
Git과 코드를 둘러보던 중 .npmrc에 PAT가 그대로 적혀 있는 것을 발견했습니다. 커밋 히스토리와 권한 범위를 먼저 확인한 뒤, 슬랙에 공유하고 폐기 및 교체를 요청드렸습니다. 최근 PAT 유출 사례가 뉴스에 나올 정도로 위험하기에 심각성도 함께 강조했습니다. 이 일을 계기로 “프론트엔드 기본 보안 가이드” 문서를 작성해 팀에 공유하기도 했습니다.
2. Git 브랜치 전략
Git 브랜치 전략은 팀마다 다양합니다. 현재 회사는 main → feature/* → release/* → main 순으로 관리되고, 각 feature/* 브랜치를 develop과 staging 브랜치에 로컬에서 머지하면 개발 서버와 스테이징 서버에 자동으로 배포되는 방식이었습니다.
신규 피처가 staging QA를 통과하고도 배포가 늦어지는 경우가 있고, 하루에 배포가 한두 번 이상 일어나는 환경이다 보니 나름대로 그에 맞게 운영되고 있었습니다. 하지만 여기엔 몇 가지 문제가 있습니다.
staging환경이 실제로 QA해야 하는 내용과 다를 수 있습니다.develop,staging브랜치에 관리되지 않는 피처가 계속 쌓입니다. 주기적으로 브랜치를 삭제하고 최신화하는 과정이 필요합니다.release브랜치가 정상적으로 동작한다는 확신이 없습니다.- PR 리뷰를
release에서main으로 머지할 때만 진행하다 보니, 피처 작업자와 PR 생성자가 달라 리뷰가 제대로 이뤄지지 않습니다.
위 내용을 대중적인 Git 브랜치 전략(Git Flow, Trunk Based Development)과 함께 문서로 정리해 팀에 공유했고, 점진적으로 우리 팀에 맞는 전략을 만들어가기로 했습니다.
3. 힙 메모리 개선
티켓을 둘러보던 중, CI에서 OOM(Out Of Memory)이 발생해 --max-old-space-size를 늘려 대응한 내용을 보게 되었습니다. 그래서 claude와 함께 원인 분석을 진행했습니다. 실제 코드를 수정해야 할 수도 있었기에, 최소한의 변경사항을 원칙으로 삼았습니다.
제가 작업한 내용을 팀원들도 함께 알아가면 좋을 것 같아서, 힙 메모리에 대해 간략히 공부하고 문서로 남기며 진행했습니다.
V8은 메모리를 ‘스택(stack)‘과 ‘힙(heap)‘으로 나누는데, 힙의 가용 메모리를 초과하면 JavaScript heap out of memory가 발생합니다.
V8의 GC(가비지 컬렉션)는 대부분의 객체는 금방 죽는다라는 가설 위에 설계되었습니다. 그래서 힙을 New Space와 Old Space로 나눠 최적화합니다. 위 이미지처럼 Old Space에는 New Space에서 살아남은 객체가 저장되는데, 이게 바로 --max-old-space-size에서 말하는 Old Space입니다. 원리를 알고 나니 옵션 하나도 달리 보이네요.
개선할 수 있는 지점은 크게 두 가지였습니다. 빌드 타임에 sharp로 저장소 내 .png 파일을 .webp로 변환하는 작업과, 빌드와 함께 동작하는 eslint였습니다.
먼저 이미지 변환 과정을 추가한 팀원에게 히스토리를 확인한 뒤, 이미지를 .webp로 미리 변환해두고 해당 변환 과정을 제거했습니다. 사용하지 않는 이미지도 찾아 함께 삭제했습니다. 그리고 빌드 과정에서 함께 돌던 eslint는 별도 프로세스로 분리했습니다.
개선을 진행하면서 알게 된 점은, CI에서 부족했던 건 힙 메모리와 머신 메모리 두 가지였고
.webp사전 변환은 그중 머신 메모리 개선에 기여한다는 것이었습니다.
결과적으로 힙 메모리는 27%, 머신 메모리는 34% 감소하여 최소한의 변경으로 문제를 개선할 수 있었습니다.
3. PR 리뷰 문화
요즘은 AI가 코드를 작성하고, AI가 PR을 올리고, AI가 코드 리뷰를 하고, AI가 그 리뷰를 검토해 머지까지 진행되는 경우가 흔합니다. 루프 엔지니어링을 통해 기획부터 개발, QA까지 AI가 진행하는 방법도 많이 쓰이고 있습니다. 시대가 빠르게 변하고 있어 ‘무엇이 정답이다’라고 딱 잘라 말하기는 어렵습니다. 하지만 한 가지 확실한 게 있다면, 개발자는 본인만의 기준이 있어야 한다는 점입니다.
위 이미지는 React Testing Library를 만든 개발자이자 리액트 교육자인 Kent C. Dodds의 트윗입니다. 저는 PR을 생성하고 리뷰를 요청하는 과정이 커뮤니케이션의 하나라고 생각합니다. 변경사항에 대한 검토를 요청하는 것이기도 하지만, 그 변경사항을 이해하고 기능을 학습하는 과정이기도 합니다. 팀원이 어떤 업무를 하고 있고 코드는 어떻게 작성하는지 등 다양한 맥락이 녹아 있습니다.
‘PR을 더 느리게 만들기 위한 고민’이라는 카카오페이의 글도 많이 공감되었습니다. 모두 중요한 내용이지만, 그중 PR 템플릿을 가져와보겠습니다.
# 해결하려는 문제가 무엇인가요?
# 왜 해야 하나요?
# 어떻게 해결했나요?
# 이 PR의 한계 & 트레이드오프
# 기존 기능에 미치는 영향
# Edge Case & 실패 시나리오
# 검토한 대안과 선택 이유
# 리뷰 포인트 (파일/영역별 Risk 🔴🟡🟢)특히 맨 앞의 ‘무엇을, 왜, 어떻게’를 묻는 세 항목이 인상적이었습니다. 코드를 보기 전에 PR의 맥락을 한 번에 파악할 수 있고, 사람이 아니라 AI가 작성하더라도 리뷰어가 이해하기 좋은 내용이 남게 됩니다.
팀원들과 함께 만들어가는 서비스인 만큼, 각 팀만의 PR 문화를 만들어가기 위해 노력해보면 좋겠습니다.