프론트엔드 개발자로 프로젝트를 진행하다 보면, 단순히 화면을 구현하는 것만으로는 해결되지 않는 문제를 자주 마주친다.
기획, 디자인, QA, 백엔드와 협업하는 과정에서 반복적으로 발생하는 비효율은 개인의 역량 부족보다 팀 간 소통 방식과 시스템의 부재에서 비롯되는 경우가 많았다.
처음에는 이런 문제를 단순히 "커뮤니케이션이 아쉽다" 정도로 받아들였지만, 같은 이슈가 여러 프로젝트에서 반복되는 것을 보며 생각이 바뀌었다.
문제는 사람 개개인이 아니라, 변경 사항을 공유하고 추적하고 검증하는 체계가 부족한 환경 자체에 있었다.
이 글은 그동안 실무에서 반복적으로 겪은 문제를 정리하고, 그 안에서 내가 어떤 방식으로 개선을 시도했는지 돌아본 기록이다.
변경 사항은 생기는데, 공유는 일관되지 않았다
실무에서 가장 자주 겪은 문제 중 하나는 기획이나 디자인의 변경이 팀 전체에 같은 밀도로 전달되지 않는다는 점이었다.
예를 들어 디자이너가 피그마에서 UI를 수정했지만 개발자는 이를 늦게 인지하거나, 기획자가 요구사항을 추가했지만 일부 팀원만 알고 지나가는 일이 있었다.
이런 상황이 반복되면 팀 안에 정보 비대칭이 생기고, 나중에는 “왜 이렇게 구현됐지?”라는 질문만 남게 된다.
이 문제는 단순히 누군가가 꼼꼼하지 않아서가 아니라, 변경이 발생했을 때 어떤 채널로, 어떤 형식으로, 누구에게 공유할지에 대한 기준이 없기 때문이라고 느꼈다.
그래서 이후에는 내가 맡은 작업 범위 안에서라도 변경 사항을 놓치지 않기 위해 다음과 같은 방식으로 대응하려고 했다.
- 작업 시작 전 기획안, 디자인, API 문서를 한 번에 대조해 확인하기
- 구현 중 애매한 부분은 메신저 대화로 끝내지 않고 이슈 단위로 남기기
- 변경 사항이 확인되면 팀원들이 다시 확인할 수 있도록 링크와 맥락을 함께 정리하기
전사적인 시스템을 바꾸지는 못했지만, 최소한 내 작업 범위 안에서는 말로 들은 변경이 아니라 다시 찾아볼 수 있는 변경 기록을 남기려 했다.
변경 사항 관리 시스템이 없으면, 결국 프론트엔드에서 비용을 치르게 된다
기획, 디자인, 개발 단계에서 발생한 변경 사항이 피그마 코멘트, 메신저, 트렐로 댓글처럼 여러 채널에 흩어져 있으면 중요한 내용이 쉽게 묻힌다.
이 경우 프론트엔드는 이미 반영된 줄 알고 넘어가거나, 반대로 같은 내용을 여러 번 수정하는 비효율을 겪게 된다.
실제로 나는 이런 환경에서 다음과 같은 문제를 자주 경험했다.
- 이미 변경된 디자인을 뒤늦게 반영하며 재작업이 발생함
- API 응답 필드가 바뀌었는데 공유가 늦어 디버깅 시간이 늘어남
- QA에서 발견된 이슈가 다시 기획 변경과 섞이면서 우선순위가 흐려짐
이 과정을 겪으며 느낀 것은, 프론트엔드 개발자는 단순 구현자가 아니라 여러 시스템의 변경이 실제 제품에 반영되는 마지막 접점에 가깝다는 점이었다.
그래서 변경 관리 체계가 약할수록 그 비용은 뒤쪽 단계에 있는 프론트엔드와 QA에 크게 쏠린다.
전체 가시성이 부족하면, 문제는 늦게 발견된다
또 하나 크게 느낀 문제는 프로젝트 전체 상태를 한눈에 보기 어렵다는 점이었다.
어떤 페이지는 디자인은 바뀌었지만 개발이 반영되지 않았고, 어떤 기능은 개발은 끝났지만 QA 기준이 정리되지 않아 확인이 누락되기도 했다.
이런 상황에서는 각자 맡은 일은 하고 있지만, 프로젝트 전체로 보면 빠진 조각이 생긴다.
이 문제를 줄이기 위해 페이지나 기능 단위로라도 현재 상태를 구분해 보려는 시도를 했다.
예를 들어 작업 단위를 단순한 "진행 중 / 완료"가 아니라 아래처럼 좀 더 세분화해서 보려고 했다.
- 기획 확인 필요
- 디자인 반영 필요
- API 확인 필요
- 개발 완료
- QA 확인 필요
아주 정교한 시스템은 아니더라도, 상태를 더 명확히 나누는 것만으로도
무엇이 끝났는지보다 무엇이 아직 불확실한지를 드러내는 데 도움이 됐다.
기술적 결정과 설계 의도가 남지 않으면, 시간이 지날수록 비용이 커진다
개발을 하다 보면 나중에 꼭 다시 마주치는 질문이 있다.
"왜 이 로직을 이렇게 짰지?"
그런데 당시의 기술적 판단이나 설계 의도가 남아 있지 않으면, 코드를 다시 읽는 사람은 맥락 없이 결과만 보게 된다.
팀원이 바뀌거나 시간이 지나면 그 비용은 더 커진다.
이 문제를 크게 느낀 뒤에는 적어도 다음과 같은 내용은 남기려 했다.
- 왜 이 구조를 선택했는지
- 어떤 대안을 검토했는지
- 어떤 제약 때문에 지금 방식으로 갔는지
- 추후 변경 가능성이 있는 부분은 무엇인지
거창한 아키텍처 문서까지는 아니더라도, PR 설명이나 간단한 문서만 있어도 이후 유지보수 난이도는 분명히 달라진다고 느꼈다.
API 문서가 신뢰할 수 없으면, 협업 비용은 급격히 커진다
프론트엔드 입장에서 특히 크게 느낀 문제는 문서와 실제 API 동작이 일치하지 않는 상황이었다.
문서에는 특정 필드가 있다고 되어 있는데 실제 응답에는 없거나, 필수값처럼 보였던 값이 실제로는 선택값인 경우가 있었다.
이런 환경에서는 문서를 기준으로 개발할 수 없고, 결국 직접 호출해 보며 맞춰가는 방식에 의존하게 된다.
그 결과는 분명했다.
- 연동 전 예측 가능한 개발이 어려워짐
- 디버깅 시간이 길어짐
- 백엔드와 확인해야 할 질문이 많아짐
- 문서 자체에 대한 신뢰가 떨어짐
이 경험을 통해 나는 문서를 있으면 좋은 참고자료가 아니라, 팀이 공통으로 의존할 수 있는 기준점으로 만들어야 한다고 생각하게 됐다.
그래서 관심을 갖게 된 것이 Swagger 기반 문서 자동화였다
이 문제를 고민하면서 가장 현실적인 개선책으로 느꼈던 것은 Swagger(OpenAPI) 기반의 문서 자동화였다.
핵심은 단순했다.
문서를 사람이 따로 관리하는 방식으로 두면 코드와 문서는 계속 어긋날 수밖에 없다.
반대로 코드에서 문서를 생성하는 구조라면, 최소한 명세의 뼈대는 항상 최신 상태로 유지할 수 있다.
이 방식의 장점은 분명했다.
-
백엔드 코드에 작성된 어노테이션이나 데코레이터를 기반으로 API 명세가 생성되므로, 별도 문서를 수동으로 관리할 필요가 줄어든다.
문서 최신 여부를 확인하는 데 쓰이던 불필요한 커뮤니케이션 비용도 줄일 수 있다. -
Swagger UI를 통해 API를 직접 호출해 요청과 응답을 확인할 수 있다.
이건 단순히 보기 좋은 문서를 만드는 수준이 아니라, 문서에 대한 신뢰도를 높이는 데 큰 도움이 된다. -
URI, 메서드, 파라미터 타입, 필수 여부 같은 정형 정보는 자동화로 관리하고,
API의 목적, 예외 케이스, 응답 예시 같은 맥락 정보는 사람이 보완하는 방식으로 역할을 나눌 수 있다.
나는 이 구조가 “문서를 잘 쓰자”는 추상적인 구호보다 훨씬 현실적인 해결책이라고 봤다.
결국 중요한 것은 코드 자체가 문서의 기반이 되는 환경을 만드는 것이라고 생각했다.
다만, 툴만 도입한다고 문제가 해결되지는 않는다는 점도 분명히 느꼈다
실무에서는 어떤 도구든 도입 자체보다 운영 방식이 더 중요하다.
Swagger 역시 마찬가지다.
문서 자동화가 해결해 줄 수 있는 영역은 분명하지만, 다음과 같은 부분은 결국 팀 차원의 합의가 필요하다.
- 변경이 생겼을 때 어떤 방식으로 공유할 것인지
- 기획, 디자인, 개발 상태를 어디에서 관리할 것인지
- QA 기준을 어떤 수준까지 정의할 것인지
- API 설명에서 어떤 수준의 예시와 예외 케이스를 남길 것인지
즉, 자동화 도구는 기반을 만들어 줄 수는 있어도,
협업 문화를 대신 만들어 주지는 않는다.
그래서 이후에는 "좋은 툴을 찾는 것" 자체보다,
그 툴을 어떤 기준과 프로세스 위에서 굴릴 것인지를 더 중요하게 보게 됐다.
돌아보면, 내가 풀고 싶었던 문제는 코드 밖에도 있었다
이런 경험을 반복하면서 느낀 건 하나였다.
개발자가 해결해야 할 문제는 코드 안에만 있지 않다는 점이다.
실제 프로젝트에서는
- 변경이 어떻게 공유되는지
- 누가 어떤 기준으로 검수하는지
- 왜 이런 설계를 했는지가 남아 있는지
같은 요소들이 코드 품질만큼 결과물의 안정성에 큰 영향을 준다.
물론 내가 속했던 환경에서 이런 구조적 문제를 혼자 해결할 수는 없었다.
빠른 일정과 눈앞의 우선순위에 밀려 장기적인 개선은 자주 뒤로 밀렸다.
그럼에도 불구하고, 반복되는 문제를 그냥 불편함으로 넘기지 않고
작게라도 기록하고 정리하고 개선 방향을 고민해 본 경험은 분명 의미가 있었다.
마무리
이 글은 단순히 협업이 힘들었다는 푸념이 아니다.
실무에서 반복된 문제를 관찰하고, 원인을 구조적으로 해석하고,
내가 영향력을 가질 수 있는 범위 안에서 어떤 방식으로든 개선하려 했던 과정에 대한 기록이다.
아직 큰 시스템 변화를 만들어낸 것은 아닐 수 있다.
하지만 나는 이 경험을 통해 한 가지를 분명히 배웠다.
좋은 프론트엔드 개발자는 화면만 잘 만드는 사람이 아니라,
제품이 더 안정적으로 만들어질 수 있도록 협업 구조의 문제까지 함께 바라보는 사람이라고 생각한다.
개발자는 결국 문제 해결자다.
그리고 내가 지향하는 개발자는 코드뿐 아니라 팀의 협업 체계까지 더 나은 방향으로 바꾸기 위해 고민하는 사람이다.