프론트엔드 리딩을 맡고 처음 내린 결정들

이직한 회사에서 프론트엔드 리딩을 맡게 되었습니다. 프론트엔드 개발자는 저를 포함해 두 명이고, 그전까지는 프론트엔드를 전담하는 조직이 없었습니다. 저도 팀장 경험은 없어서, 처음에는 무엇부터 해야 할지 정하는 데 시간이 걸렸습니다.

코드 구조를 정리하고 개발 규칙을 맞추는 일도 필요했지만, 운영 중인 서비스에서 어떤 문제가 생기고 있는지부터 확인하고 싶었습니다. 코드와 커밋 히스토리를 살펴보고 동료들과 이야기하면서 에러 수집, 테스트와 리뷰, 저장소 구조를 우선 과제로 정했습니다. 아직 도입 과정에 있어서, 이번 글에는 현재까지 확인한 문제와 결정한 이유를 적어보려 합니다.

가입 과정에서 생기는 문제를 확인하기 어려웠다

회사는 통신사 부가서비스를 운영합니다. 기존 화면은 대부분 백엔드 개발자가 index.html로 작성했고, 필요한 화면을 복사해서 추가하는 방식으로 늘어나 있었습니다. 공통 폴더 구조나 컨벤션은 없었고, 작년부터 프론트엔드 개발자를 채용하면서 React와 Next.js로 옮기는 중이었습니다.

서비스 특성상 사용자는 한 번 가입하면 다시 방문할 일이 드뭅니다. UI와 UX 개선도 우선순위가 높지 않았습니다. 다만 재방문이 적다는 사실만으로 가입 화면에 문제가 없는지는 판단할 수 없었습니다. 사용자가 가입 중 어디에서 불편을 겪는지 확인할 수단이 부족했습니다.

에러 처리도 비슷했습니다. 에러를 콘솔에 남기거나 별다른 처리 없이 넘어가는 코드가 많았습니다. 커밋 히스토리에서는 에러가 발생한 뒤 일주일이 지나서야 고객센터 문의로 알게 된 기록을 찾았습니다. 그동안 같은 문제를 겪은 사용자가 얼마나 있었는지는 확인할 수 없었습니다.

이 기록을 보고 가입 흐름의 장애를 빨리 발견하는 일을 우선 과제로 잡았습니다. 코드 구조를 정리할 필요도 있었지만, 운영 중인 에러를 고객 문의가 들어올 때까지 모르는 상태부터 개선하고 싶었습니다.

고객 문의 전에 에러를 확인할 수 있도록 Sentry를 도입하기로 했다

에러 수집 도구를 제안했을 때는 고객센터를 통해서도 문제를 알 수 있는데 별도 도구가 필요한지, 콘솔 로그를 잘 남기면 되지 않는지에 대한 질문이 있었습니다.

고객 문의는 문제를 파악하는 데 도움이 되지만, 문의가 접수되기 전까지는 장애를 알기 어렵습니다. 브라우저 콘솔에만 남는 로그도 운영자가 모아서 확인할 수 없습니다. 실제 사용자 환경에서 발생한 에러를 수집할 방법이 필요했습니다.

Sentry를 선택한 데에는 이전 회사에서 사용한 경험도 영향을 줬습니다. 사용해 본 도구라 도입에 필요한 작업과 비용을 예상하기 수월했습니다.

수집 이후의 확인 과정도 함께 계획했습니다. AI가 에러와 관련 코드를 분석하고, 위험도를 기준으로 정리한 내용을 매일 아침 슬랙에 올리는 방식입니다. 에러 목록을 직접 살펴보기 전에 우선 확인할 항목을 파악하는 데 도움을 받으려는 목적입니다.

이전에 AI 분석 문서를 계속 쌓아두었다가 문서마다 설명이 달라져 판단 근거로 쓰지 않기로 한 경험이 있습니다. 이번에는 분석 보고서를 별도로 축적하지 않고, 그날 확인할 내용만 필요한 채널에 남기기로 했습니다. 자동 분석이 실제로 에러 확인에 얼마나 도움이 되는지는 도입 후에 확인해야 합니다.

테스트를 통과한 코드에서도 금액 표시 문제가 발견됐다

테스트 상황은 프로젝트마다 달랐습니다. 레거시 화면에는 테스트가 없었지만, React로 작성한 프로젝트에는 이미 800개가 넘는 단위 테스트가 있었습니다.

테스트를 모두 통과한 코드를 AI 에이전트로 다시 리뷰했을 때 수정이 필요한 문제가 나왔습니다. 그중에는 사용자에게 금액이 잘못 표시될 수 있는 경로도 있었습니다. 기존 테스트가 해당 경로를 검증하지 못하고 있었던 겁니다.

앞으로의 개발에는 테스트를 먼저 작성하는 방식을 적용하고, PR 단계의 리뷰도 추가하기로 했습니다. 테스트를 작성하면서 요구사항과 예상 동작을 먼저 정리하고, 리뷰에서는 빠뜨린 조건이나 잘못 해석한 요구사항을 다시 살펴보려 합니다.

이미 테스트가 많은데 TDD까지 적용하면 속도가 느려지지 않겠느냐는 질문도 있었습니다. 테스트를 먼저 작성한다고 이번과 같은 누락이 사라지는 것은 아닙니다. 다만 구현 전에 검증할 동작을 구체적으로 정리하는 과정이 필요하다고 판단했습니다. 기존 테스트를 통과했다는 사실만으로 리뷰를 생략하기는 어려웠습니다.

레거시 화면 전체를 수정해 이 방식을 소급 적용하지는 않기로 했습니다. 테스트가 없는 화면을 한꺼번에 변경하면 기존 동작을 깨뜨릴 위험이 있고, 지금 인원으로 감당할 작업 범위도 고려해야 했습니다.

공유할 UI는 적었지만 저장소를 합치기로 했다

운영 중인 프로젝트는 디자인과 컨벤션, 기술 스택이 서로 달랐습니다. 공통 디자인 시스템도 없었습니다. 모노레포를 검토할 때 가장 고민한 부분은 실제로 공유할 UI 컴포넌트가 많지 않다는 점이었습니다.

제가 통합하려고 했던 대상은 프로젝트별로 흩어진 도메인 지식과 개발 규칙이었습니다. 회사에서는 AI 도구 사용을 적극 권장하고 있었지만, 도입 초기라 활용 방식과 결과물의 차이가 컸습니다. 에이전트에 작업을 맡길 때도 각 프로젝트에서 어떤 규칙과 문서를 참고하게 할지 정할 필요가 있었습니다.

별도 지식 저장소를 두는 방법도 검토했습니다. 사내에 이미 그런 형태의 저장소가 있었지만, 규칙을 변경한 뒤 각 프로젝트에 반영됐는지 따로 확인해야 한다는 점이 걸렸습니다. 이번에는 규칙 문서와 앱 코드를 한 저장소에서 관리하고, 둘을 함께 변경할 수 있는 구조를 선택했습니다.

현재 잡은 구조는 다음과 같습니다.

monorepo/
├── apps/
│   ├── join-a  ┐
│   ├── join-b  ├─ 가입 서비스 3종 (통신사별)
│   ├── join-c  ┘
│   ├── service-a
│   └── service-b
├── packages/
│   ├── telecom         # 통신사 코드·분기
│   ├── api             # 서버 계약, 에러 코드
│   ├── legal           # 법정 고지 문구
│   ├── config          # 린트·타입·빌드 설정
│   └── webview-bridge  # 앱 웹뷰 통신
└── docs/               # 도메인 지식과 컨벤션

UI보다 먼저 공통으로 관리하려는 것은 통신사 코드, 서버 계약과 에러 코드, 법정 고지 문구, 개발 설정, 웹뷰 통신입니다. 화면 디자인이 달라도 여러 서비스가 함께 참조하는 항목들입니다. docs에는 도메인 지식과 컨벤션을 정리합니다.

문서의 위치와 적용 순서를 함께 정했다

문서를 한곳에 모으는 것과 작업할 때 참고하게 하는 것은 별개의 문제였습니다. 에이전트가 읽을 규칙 파일에서 어떤 문서를 참조할지, 앱마다 다른 규칙은 어디에 둘지 정했습니다.

docs/domain에는 통신사 코드 체계, 가입 흐름의 용어, 금액과 고지 표기 규칙을 둡니다. docs/conventions에는 폴더 구조, 네이밍, 상태 관리와 에러 처리 방식을 정리합니다. 브랜치 전략과 PR 양식, 머지 규칙은 docs/workflow에서 관리하고, 작업 기록을 남기는 형식은 docs/history에 둡니다.

최상위 에이전트 규칙 파일은 이 네 영역의 문서를 참조하도록 구성합니다. 각 앱에도 규칙 파일을 두되 공통 내용을 반복하지 않고 앱에 필요한 예외만 적습니다. 충돌하는 항목은 앱 규칙을 우선 적용하도록 정했습니다.

매 작업에서 읽게 할 문서는 짧게 유지하려 합니다. 규칙을 추가할 때는 모든 작업에 필요한 내용인지 먼저 확인하기로 했습니다. 원격 반영과 병합도 명시적인 요청이 있을 때만 수행하도록 적었습니다.

이 구조에서는 공통 규칙의 변경과 영향을 받는 앱 코드의 수정을 같은 PR에서 검토할 수 있습니다. 저장소를 합친다고 규칙이 자동으로 지켜지는 것은 아니지만, 문서와 코드를 따로 변경하고 반영 여부를 추적하는 부담은 줄일 수 있다고 봤습니다.

기존 저장소의 커밋 히스토리는 함께 옮기고, 원래 저장소는 보관 상태로 남길 예정입니다.

지금은 저장소를 옮기고 공통 규칙을 작성하고 있다

운영 에러를 빨리 확인하는 일을 우선 과제로 정했지만, 실제 구현은 모노레포 구성부터 시작했습니다. Sentry와 PR 리뷰를 여러 앱에 적용하기 전에 앱 구조와 공통 규칙을 먼저 정리하기로 했기 때문입니다. 에러 분석에서 참조할 코드와 문서, PR 리뷰에서 확인할 규칙을 이곳에 모으려 합니다.

Sentry 도입이나 PR 리뷰에 모노레포가 반드시 필요한 것은 아닙니다. 이번에는 저장소 통합도 진행할 계획이어서, 옮긴 구조에 맞춰 도입하는 순서를 선택했습니다. 그만큼 에러 수집 도입이 뒤로 밀리는 점은 남아 있습니다.

현재는 앱을 하나씩 옮기고 있습니다. 커밋 히스토리를 보존하며 이전하는 작업과 docs 초안을 작성하는 것이 이번 주 작업입니다. 이후 Sentry와 PR 리뷰를 적용할 예정입니다.

리딩을 맡은 지 아직 한 달이 되지 않았습니다. 지금까지 정한 방식이 맞았는지 말하기에는 이릅니다. 저장소 이전을 마친 뒤에는 에러를 더 빨리 발견할 수 있게 됐는지, 테스트와 리뷰가 놓치는 문제를 줄이는 데 도움이 됐는지 확인하고 싶습니다.