프론트엔드 개발자로 프로젝트를 진행하면서, 기획, 디자인, QA, 백엔드와의 협업에서 반복적으로 마주치는 문제들이 있다. 이 문제들은 단순히 개인의 역량 부족이 아니라, 팀 간 소통과 시스템의 부재에서 비롯된 구조적인 한계로 느껴진다. 아래는 그동안 느꼈던 현황과 고민들이다.
변경 사항과 의도 공유의 부재
기획이나 디자인이 변경될 때, 그 내용과 의도가 팀 전체에 체계적으로 공유되지 않는다. 예를 들어, 디자이너가 UI를 수정했는데 프론트엔드 팀은 이를 뒤늦게 알아차리거나, 기획자가 추가한 요구사항이 개발자에게 전달되지 않는 경우가 종종 있다. 이로 인해 팀 간 지식 격차가 커지고, 나중에 문제를 발견했을 때 "왜 이렇게 된 거지?"라는 질문만 남는다.
변경 사항 관리 시스템의 공백
기획, 디자인, 개발 각 단계에서 발생하는 변경 사항을 체계적으로 추적하고 관리할 시스템이 없다. 현재는 피그마 코멘트, 메신저, 트렐로 댓글 등 정해진 수단없이 주고받는 식이라, 중요한 변경점이 묻히거나 누락되기 쉽다. 결국 프론트엔드에서 수정해야 할 부분을 놓치거나, 불필요한 중복 작업을 하게 된다.
프로젝트 가시성 부족
프로젝트 전반에 대한 가시성이 부족해서, 어떤 페이지가 업데이트되었고, 어떤 부분이 누락되었는지 한눈에 파악하기 어렵다. 예를 들어, 기획과 디자인이 바뀌었는데 개발이 안 된 페이지를 나중에 발견하거나, 반대로 개발은 끝났는데 QA에서 누락된 경우를 뒤늦게 알게 된다. 전체 그림을 볼 수 없으니 혼란만 가중된다.
기술적 결정과 설계 의도 기록의 부재
기술적인 결정이나 설계 의도를 기록한 문서가 없다. "왜 이 로직을 이렇게 짰지?"라는 질문이 생길 때, 당시의 맥락을 알 수 없어 문제 해결 방향을 잡기 힘들다. 팀원이 바뀌거나 시간이 지날수록 겪게될 혼란이 가중될 것 같다.
분산된 변경 기록
변경 기록이 메신저, 문서, 피그마 등에 흩어져 있어, 프로젝트 전체를 평가하거나 회고하기 어렵다. 어떤 기능이 언제, 왜 수정되었는지 추적하려면 퍼즐 조각을 맞추듯 시간을 들여야 한다.
QA 기준의 불명확함
개발시에 QA 기준이 명확히 정립되지 않아, 자동화 테스트 도입이나 관리가 어렵다. 어떤 기능을 어디까지 테스트해야 하는지 기준이 모호하다 보니, 수동으로 확인하다가 놓치는 경우도 많다. QA 과정에서 실수가 드러나도, 이를 빠르게 개선할 체계가 없어 반복되는 느낌이다.
수동 수정의 한계와 실수
기획, 디자인, 백엔드 API의 변경 사항을 대부분 수동으로 수정하다 보니, 누락이나 실수를 발견할 시스템이 없다. 예를 들어, API 응답 필드가 바뀌었는데 프론트엔드 코드에 반영되지 않거나, 디자인이 수정되었는데 반영 시점이 달라 충돌이 생긴다. 이런 실수를 찾는 데 드는 노력과 시간이 만만치 않다.
문서에 대한 신뢰의 위기
백엔드에서 제공하는 API가 실제로 의도대로 사용되고 있는지 검증할 방법이 마땅치 않다. API 문서의 내용과 실제 동작이 다른 경우가 잦다. 이런 상황에서는 API 호출을 테스트해보기 전까지 제대로 동작할지 알 수 없으니, 개발 과정에서 불필요한 시행착오가 늘어난다. 예를 들어, API의 요청 파라미터나 응답 필드가 문서와 달라서 디버깅에 시간을 쏟아야 했던 경험이 적지 않다. 이로 인해 프론트엔드 팀은 백엔드 팀과의 소통에 더 많은 에너지를 쓰게 되고, 개발 속도도 느려진다. 문서가 신뢰할 수 있는 기준이 되어주지 못하니, 결국 "직접 해보고 맞춰가는" 방식에 의존하게 되는 악순환이 반복된다.
이 문제를 해결하려면 근본적인 변화가 필요하다는 생각이 들었다. 단순히 문서를 더 잘 관리하자는 다짐으로는 한계가 있다. 그래서 떠오른 아이디어가 코드베이스 기반 문서 자동화 시스템이다.
- 자동 생성: API의 URI, 요청 파라미터, 응답 필드 같은 정보는 백엔드 코드베이스에서 자동으로 추출해 문서화한다. 이렇게 하면 코드와 문서 간의 불일치가 원천적으로 줄어든다.
- 자동 변경 기록: 코드가 수정될 때마다 변경사항과 기록이 자동으로 업데이트되며, 문서가 항상 최신 상태를 유지하도록 한다.이런 시스템을 도입하면, 프론트엔드 개발자로서 API 문서를 열 때마다 "이게 정말 맞나?"라는 의심을 덜 수 있을 것이다. 코드와 문서가 동기화된다는 확신만 있어도 작업 효율이 크게 올라갈 거라 기대한다.
자동화가 모든 걸 해결할 수는 없다는 점도 고려했다. 단순히 데이터를 뽑아내는 것만으로는 문서가 직관적이거나 이해하기 쉽게 되지 않을 수 있다. 그래서 역할 분담을 이렇게 나눠보았다.
- 자동화된 부분 (데이터 생성): API 문서의 기본 뼈대는 코드베이스에서 자동으로 생성한다. URI, 파라미터 구조, 응답 필드 같은 객관적 정보는 사람이 손대지 않아도 정확하게 반영된다.
- 사람이 하는 부분 (설명 추가 및 명명): 자동 생성된 데이터에 사람이 개입해 가독성을 높이는 작업을 한다. 예를 들어,
/api/users/{id}같은 URI에 "특정 사용자 정보 조회"라는 이름을 붙이거나, 요청 파라미터와 응답 필드에 "이 필드는 필수입니다" 같은 설명을 추가한다.이렇게 하면 프론트엔드 개발자가 문서를 보자마자 API의 목적과 사용법을 파악할 수 있어, 불필요한 질문이나 소통 비용이 줄어들 것이다.
궁극적으로 코드베이스에서 API 문서를 자동 생성하고, 사람이 핵심적인 설명과 명칭을 보완하는 체계를 만드는 것이다. 이를 통해 항상 최신화된 문서를 유지하고, API가 의도대로 사용되는지 검증할 수 있는 시스템을 구축하고 싶다. 하지만 이 과정에서 현실적인 고민도 든다. 이런 시스템을 도입하려면 백엔드 팀의 협조와 초기 설정 비용이 필요하다. 현재 팀의 우선순위나 리소스가 이런 변화를 뒷받침할 수 있을지 확신이 서지 않는다. 또한, 자동화 도구를 선택하고 유지보수하는 데도 노력이 들 것이다. 그렇지만 프론트엔드 개발자로서 더 나은 협업 환경을 만들기 위해 이런 방향성을 제안해보고 싶다. 작은 규모로라도 시범 적용을 해보며 설득력을 얻고, 점차 팀 전체로 확산시킬 수 있다면 좋겠다.
회고
돌이켜보면, 이 모든 문제의 근원은 체계의 부재와 소통의 단절이다. 프론트엔드 개발자로서 코드를 잘 짜는 것도 중요하지만, 그 코드를 둘러싼 환경이 뒷받침되지 않으면 효율과 품질이 떨어질 수밖에 없다. 기획이나 디자인과의 소통, 변경 관리 시스템 같은 문제는 팀 전체의 협력이 필요하다. 하지만 현재 팀 구조나 회사 문화에서는 이런 변화를 추진할 동력이 부족하다. "빨리빨리"를 외치며 급한 불을 끄는 데 치중하다 보니, 장기적인 개선은 뒷전이 되곤 했다.
마무리
현실적으로 모든 문제를 한 번에 해결하기는 어렵다. 회사의 우선순위와 리소스, 팀 간 협업 의지가 맞물려야 가능한 일들이 많기 때문이다. 그래도 프론트엔드 개발자로서 내가 맡은 영역에서 조금씩 개선을 시도하며, 더 나은 환경을 만들어가는 데 기여하고 싶다. 이번 회고를 통해 문제의 원인을 명확히 정리한 것만으로도 의미가 있었다. 이 고민이 단순한 푸념으로 끝나지 않도록, 작은 행동으로 옮겨보는 게 앞으로의 과제다. 혼란 속에서도 길을 찾아가는 개발자가 되고 싶다는 마음을 다시 한번 다잡는다.