프론트엔드 개발자로 프로젝트를 하다 보면, 화면을 구현하는 일만으로는 끝나지 않는 문제가 꽤 자주 생긴다.
기획이 바뀌고, 디자인이 수정되고, API 응답이 달라지고, QA에서 새로운 이슈가 나온다.
하나하나 보면 자연스러운 일인데, 문제는 이런 변화가 팀 안에서 항상 같은 방식으로 공유되지는 않는다는 점이었다.
처음에는 그냥 커뮤니케이션이 조금 아쉽다고 생각했다.
그런데 비슷한 상황이 여러 프로젝트에서 반복되다 보니, 이건 누가 말을 잘하고 못하고의 문제가 아니라는 생각이 들었다. 변경 사항을 공유하고, 추적하고, 나중에 다시 확인할 수 있는 체계가 부족한 환경에서는 같은 문제가 계속 생길 수밖에 없었다.
이 글은 그동안 실무에서 겪었던 협업상의 불편함과, 그 안에서 내가 조금이라도 개선해보려고 했던 것들을 정리한 기록이다.
변경 사항은 생기는데, 공유는 일관되지 않았다
실무에서 가장 자주 겪었던 문제 중 하나는 기획이나 디자인 변경이 팀 전체에 같은 밀도로 전달되지 않는 일이었다.
예를 들어 디자이너가 피그마에서 UI를 수정했는데 개발자는 그 사실을 뒤늦게 알게 되거나, 기획자가 요구사항을 추가했지만 일부 팀원만 알고 넘어가는 경우가 있었다.
그 순간에는 작은 누락처럼 보이지만, 이런 일이 쌓이면 나중에는 “왜 이렇게 구현됐지?”라는 질문만 남는다.
이 문제는 누군가가 일부러 공유를 안 해서 생긴다기보다, 변경이 생겼을 때 어떤 채널에, 어떤 형식으로, 누구에게 남겨야 하는지 기준이 명확하지 않아서 생기는 경우가 많았다.
그래서 이후에는 내가 맡은 범위 안에서라도 변경 사항을 놓치지 않기 위해 몇 가지 방식을 신경 쓰기 시작했다.
- 작업을 시작하기 전에 기획안, 디자인, API 문서를 한 번에 대조해보기
- 구현 중 애매한 부분은 메신저 대화로만 끝내지 않고 이슈나 코멘트로 남기기
- 변경 사항을 확인하면 관련 링크와 맥락을 같이 정리해두기
팀 전체의 시스템을 바꿀 수 있었던 것은 아니지만, 적어도 내 작업 범위 안에서는 말로만 들은 변경이 아니라 나중에 다시 찾아볼 수 있는 기록을 남기려고 했다.
변경 사항 관리가 약하면, 결국 뒤쪽 단계에서 비용을 치른다
기획, 디자인, 개발 과정에서 나온 변경 사항이 피그마 코멘트, 메신저, 트렐로 댓글 같은 여러 채널에 흩어져 있으면 중요한 내용이 쉽게 묻힌다.
프론트엔드 입장에서는 이미 반영된 줄 알고 넘어가거나, 반대로 같은 부분을 여러 번 수정하는 일이 생긴다. 실제로 이런 환경에서 꽤 자주 겪었던 일이 있었다.
- 이미 바뀐 디자인을 뒤늦게 확인하고 다시 수정함
- API 응답 필드가 바뀌었는데 공유가 늦어 디버깅 시간이 길어짐
- QA에서 나온 이슈가 기획 변경과 섞이면서 우선순위가 흐려짐
이런 경험을 하면서 프론트엔드 개발자는 단순히 화면을 만드는 사람이 아니라, 기획과 디자인, API의 변경이 실제 제품에 반영되는 마지막 접점에 가깝다는 생각을 하게 됐다.
그래서 변경 관리가 약한 팀일수록 그 비용은 자연스럽게 프론트엔드와 QA 쪽으로 몰린다.
앞단에서 정리되지 않은 내용은 결국 구현 단계나 검수 단계에서 다시 드러나기 때문이다.
전체 상태가 잘 보이지 않으면, 문제는 늦게 발견된다
또 하나 불편했던 점은 프로젝트 전체 상태를 한눈에 보기 어렵다는 것이었다.
어떤 페이지는 디자인은 수정됐지만 개발에는 아직 반영되지 않았고, 어떤 기능은 개발은 끝났지만 QA 기준이 정리되지 않아 확인이 빠지기도 했다.
각자 맡은 일은 하고 있는데, 프로젝트 전체로 보면 빠진 조각이 생기는 식이었다.
이 문제를 줄이기 위해 페이지나 기능 단위로 상태를 조금 더 나눠서 보려고 했다.
처음에는 단순히 “진행 중 / 완료” 정도로만 구분했지만, 실제로는 그 정도로는 부족했다. 그래서 상황에 따라 이런 식으로 상태를 나눠보는 편이 더 도움이 됐다.
- 기획 확인 필요
- 디자인 반영 필요
- API 확인 필요
- 개발 완료
- QA 확인 필요
대단한 시스템은 아니었다.
하지만 상태를 조금 더 구체적으로 나누는 것만으로도, 무엇이 끝났는지보다 무엇이 아직 불확실한지를 확인하는 데 도움이 됐다.
기술적 결정과 설계 의도가 남지 않으면, 나중에 다시 비용이 된다
개발을 하다 보면 시간이 지나서 꼭 다시 마주치는 질문이 있다.
“이 로직 왜 이렇게 짰지?”
당시에 어떤 이유로 그런 구조를 선택했는지 남아 있지 않으면, 나중에 코드를 보는 사람은 결과만 보게 된다.
팀원이 바뀌거나 시간이 많이 지난 뒤에는 그 비용이 더 커진다.
이 문제를 겪은 뒤로는 적어도 이런 내용은 남기려고 했다.
- 왜 이 구조를 선택했는지
- 어떤 대안을 생각했는지
- 어떤 제약 때문에 지금 방식으로 구현했는지
- 나중에 변경될 가능성이 있는 부분은 어디인지
거창한 아키텍처 문서까지는 아니어도 된다.
PR 설명이나 짧은 메모만 남아 있어도, 나중에 다시 코드를 볼 때 부담이 훨씬 줄어든다.
특히 일정이 급한 프로젝트일수록 “일단 구현하고 넘어가자”가 반복되기 쉬운데, 그런 결정들이 아무 기록 없이 쌓이면 나중에는 작은 수정 하나도 조심스러워진다.
API 문서가 믿기 어려우면, 협업 비용은 바로 늘어난다
프론트엔드 입장에서 특히 크게 느꼈던 문제는 API 문서와 실제 동작이 다를 때였다.
문서에는 특정 필드가 있다고 되어 있는데 실제 응답에는 없거나, 필수값처럼 보였던 값이 실제로는 선택값인 경우가 있었다.
반대로 문서에는 없던 값이 응답에 포함되어 있거나, 타입이 다르게 내려오는 경우도 있었다.
이런 환경에서는 문서를 기준으로 개발하기 어렵다.
결국 직접 호출해보고, 응답을 확인하고, 백엔드에 다시 물어보면서 맞춰가는 방식이 된다.
실제로 개발 과정에서는 이런 일이 계속 이어졌다.
- 연동 전에 어느 정도까지 구현할 수 있을지 예측하기 어려움
- 디버깅 시간이 예상보다 길어짐
- 백엔드에 확인해야 할 질문이 많아짐
- 문서 자체를 그대로 신뢰하기 어려워짐
이 경험을 하면서 API 문서는 그냥 참고용 자료가 아니라, 프론트엔드와 백엔드가 같이 믿고 볼 수 있는 기준에 가까워야 한다고 느꼈다.
그래서 Swagger 기반 문서 자동화에 관심을 갖게 됐다
이 문제를 겪으면서 자연스럽게 떠올랐던 것이 Swagger(OpenAPI) 기반의 문서 자동화였다.
사실 Swagger 기반 API 문서는 특별히 새로운 방식은 아니라고 생각한다.
요즘은 API 명세를 관리할 때 흔히 쓰는 방식이고, 프론트엔드 입장에서도 Swagger UI에서 요청과 응답을 직접 확인할 수 있어서 익숙한 편이다.
아쉬웠던 점은 당시에는 API 문서를 엑셀에 수기로 정리하는 방식에 가까웠다는 것이다.
처음에는 단순히 문서 양식의 차이라고 생각했지만, 실제로 개발을 하다 보니 코드와 문서가 따로 관리되는 구조 자체가 계속 문제로 이어졌다.
코드는 바뀌었는데 문서는 그대로인 경우가 있었고, 문서가 최신인지 확인하는 일에도 계속 커뮤니케이션 비용이 들었다.
그러다 보니 문서를 보고 개발하기보다, 직접 API를 호출해보며 맞춰가는 시간이 많아졌다.
이런 상황에서는 Swagger 기반 문서 자동화가 훨씬 현실적인 개선 방향이라고 느꼈다.
URI, 메서드, 파라미터 타입, 필수 여부 같은 기본 명세는 코드와 함께 관리되도록 하고, API의 목적이나 예외 케이스, 응답 예시처럼 맥락이 필요한 부분은 사람이 보완하는 방식이 더 적절하다고 봤다.
이렇게 하면 문서를 사람이 전부 수기로 관리하는 부담도 줄고, 프론트엔드 입장에서는 최소한 기본 명세를 믿고 개발할 수 있다.
문서가 단순히 보기 좋은 자료가 아니라, 실제로 호출해보고 검증할 수 있는 도구가 된다는 점도 중요했다.
결국 내가 아쉬웠던 건 “문서를 더 열심히 쓰자”는 문제가 아니었다.
코드와 문서가 따로 움직이는 구조를 줄이고, 문서가 실제 개발 흐름 안에서 같이 관리되는 환경이 필요하다고 느꼈다.
물론 툴만 도입한다고 문제가 해결되지는 않는다
다만 Swagger 같은 도구를 도입한다고 해서 협업 문제가 자동으로 해결되는 것은 아니라고 생각한다.
실무에서는 도구 자체보다 그 도구를 어떻게 운영하느냐가 더 중요했다.
문서 자동화가 기본 명세를 맞춰주는 데는 도움이 되지만, 모든 문제를 대신 해결해주지는 않는다.
예를 들어 이런 부분은 여전히 팀 안에서 기준을 정해야 한다.
- 변경이 생겼을 때 어디에 어떻게 공유할 것인지
- 기획, 디자인, 개발 상태를 어디에서 관리할 것인지
- QA 기준을 어느 정도까지 정리할 것인지
- API 설명에 어떤 수준의 예시와 예외 케이스를 남길 것인지
자동화 도구는 기반을 만들어줄 수는 있지만, 협업 방식을 대신 정해주지는 않는다.
그래서 이후에는 좋은 툴을 찾는 것보다, 그 툴을 어떤 기준과 프로세스 위에서 사용할 것인지를 더 중요하게 보게 됐다.
돌아보면, 내가 신경 쓰고 싶었던 문제는 코드 밖에도 있었다
이런 경험을 반복하면서 느낀 것은 개발자가 마주하는 문제가 코드 안에만 있지는 않다는 점이었다.
실제 프로젝트에서는 코드 품질만큼이나 이런 것들이 결과물의 안정성에 영향을 줬다.
- 변경 사항이 어떻게 공유되는지
- 누가 어떤 기준으로 검수하는지
- 왜 이런 설계를 했는지가 남아 있는지
- 문서와 실제 동작이 얼마나 일치하는지
물론 내가 속했던 환경에서 이런 문제를 혼자 전부 해결할 수는 없었다.
일정은 항상 빠듯했고, 눈앞의 우선순위에 밀려 장기적인 개선은 자주 뒤로 밀렸다.
그래도 반복되는 불편함을 그냥 넘기지 않고, 내가 할 수 있는 범위에서 기록하고 정리하려고 했던 경험은 의미가 있었다.
작은 메모 하나, 변경 사항 링크 하나, PR 설명 한 줄이 당장은 별것 아닌 것처럼 보여도 나중에는 분명 도움이 되는 경우가 있었다.
마무리
이 글은 협업이 힘들었다는 이야기를 하려는 글은 아니다.
실무에서 반복해서 마주친 문제를 보면서, 왜 이런 일이 생기는지 생각해보고, 내가 손댈 수 있는 범위 안에서 조금이라도 개선해보려고 했던 과정을 정리한 글에 가깝다.
큰 시스템을 바꿨다고 말하기는 어렵다.
하지만 이 경험을 통해 프론트엔드 개발자로서 신경 써야 할 범위가 화면 구현에만 머물지는 않는다는 것을 배웠다.
좋은 프론트엔드 개발자는 화면을 잘 만드는 사람이어야 한다.
하지만 거기서 끝나지 않고, 제품이 더 안정적으로 만들어질 수 있도록 협업 과정에서 생기는 문제도 같이 볼 수 있어야 한다고 생각한다.
내가 앞으로 지향하는 개발자도 그런 쪽에 가깝다.
코드를 잘 짜는 것뿐 아니라, 팀이 더 덜 헤매고 더 안정적으로 일할 수 있는 방향을 함께 고민하는 개발자.