프론트엔드 개발자로 프로젝트를 진행하면서, 기획, 디자인, QA, 백엔드와의 협업에서 반복적으로 마주치는 문제들이 있다. 이 문제들은 단순히 개인의 역량 부족이 아니라, 팀 간 소통과 시스템의 부재에서 비롯된 구조적인 한계로 느껴진다. 아래는 그동안 느꼈던 현황과 고민들이다.
변경 사항과 의도 공유의 부재
기획이나 디자인이 변경될 때, 그 내용과 의도가 팀 전체에 체계적으로 공유되지 않는다. 예를 들어, 디자이너가 UI를 수정했는데 프론트엔드 팀은 이를 뒤늦게 알아차리거나, 기획자가 추가한 요구사항이 개발자에게 전달되지 않는 경우가 종종 있다. 이로 인해 팀 간 지식 격차가 커지고, 나중에 문제를 발견했을 때 "왜 이렇게 된 거지?"라는 질문만 남는다.
변경 사항 관리 시스템의 공백
기획, 디자인, 개발 각 단계에서 발생하는 변경 사항을 체계적으로 추적하고 관리할 시스템이 없다. 현재는 피그마 코멘트, 메신저, 트렐로 댓글 등 정해진 수단없이 주고받는 식이라, 중요한 변경점이 묻히거나 누락되기 쉽다. 결국 프론트엔드에서 수정해야 할 부분을 놓치거나, 불필요한 중복 작업을 하게 된다.
프로젝트 가시성 부족
프로젝트 전반에 대한 가시성이 부족해서, 어떤 페이지가 업데이트되었고, 어떤 부분이 누락되었는지 한눈에 파악하기 어렵다. 예를 들어, 기획과 디자인이 바뀌었는데 개발이 안 된 페이지를 나중에 발견하거나, 반대로 개발은 끝났는데 QA에서 누락된 경우를 뒤늦게 알게 된다. 전체 그림을 볼 수 없으니 혼란만 가중된다.
기술적 결정과 설계 의도 기록의 부재
기술적인 결정이나 설계 의도를 기록한 문서가 없다. "왜 이 로직을 이렇게 짰지?"라는 질문이 생길 때, 당시의 맥락을 알 수 없어 문제 해결 방향을 잡기 힘들다. 팀원이 바뀌거나 시간이 지날수록 겪게될 혼란이 가중될 것 같다.
분산된 변경 기록
변경 기록이 메신저, 문서, 피그마 등에 흩어져 있어, 프로젝트 전체를 평가하거나 회고하기 어렵다. 어떤 기능이 언제, 왜 수정되었는지 추적하려면 퍼즐 조각을 맞추듯 시간을 들여야 한다.
QA 기준의 불명확함
개발시에 QA 기준이 명확히 정립되지 않아, 자동화 테스트 도입이나 관리가 어렵다. 어떤 기능을 어디까지 테스트해야 하는지 기준이 모호하다 보니, 수동으로 확인하다가 놓치는 경우도 많다. QA 과정에서 실수가 드러나도, 이를 빠르게 개선할 체계가 없어 반복되는 느낌이다.
수동 수정의 한계와 실수
기획, 디자인, 백엔드 API의 변경 사항을 대부분 수동으로 수정하다 보니, 누락이나 실수를 발견할 시스템이 없다. 예를 들어, API 응답 필드가 바뀌었는데 프론트엔드 코드에 반영되지 않거나, 디자인이 수정되었는데 반영 시점이 달라 충돌이 생긴다. 이런 실수를 찾는 데 드는 노력과 시간이 만만치 않다.
문서에 대한 신뢰성 부족
API 문서와 실제 동작이 일치하지 않는 경우가 많다. 이런 상황에서는 API 호출을 테스트해보기 전까지 제대로 동작할지 알 수 없으니, 개발 과정에서 불필요한 시행착오가 늘어난다. 예를 들어, API의 요청과 응답이 문서와 달라서 디버깅에 시간을 쏟아야하는 경우가 많다. 이로 인해 프론트엔드 팀은 백엔드 팀과의 소통에 더 많은 에너지를 쓰게 되고, 개발 속도도 느려진다. 문서가 신뢰할 수 있는 기준이 되어주지 못하니, 결국 "직접 해보고 맞춰가는" 방식에 의존하게 되는 악순환이 반복된다.
해결 아이디어: Swagger(OpenAPI) 기반의 문서 자동화 도입
이 문제의 근본 원인은 '코드와 문서의 물리적 분리'에 있다. 단순히 "위키를 잘 쓰자"는 다짐으로는 해결되지 않는다. 이를 해결하기 위해 처음에는 거창한 자동화 시스템을 직접 구축해야 하나 고민했으나, 사실 이는 이미 업계 표준으로 자리 잡은 Swagger(OpenAPI)와 같은 문서 자동화 도구를 통해 가장 효율적으로 해결할 수 있는 문제였다.
백엔드 프레임워크에서 제공하는 Swagger 모듈을 적극적으로 도입한다면 다음과 같은 개선이 가능하다.
코드와 문서의 동기화
별도의 엑셀이나 노션 문서를 관리할 필요 없이, 백엔드 코드에 작성된 데코레이터나 어노테이션을 기반으로 API 명세서가 자동 생성된다.
코드가 수정되면 문서도 실시간으로 반영되므로, "이 문서 최신 버전 맞나요?"라는 불필요한 커뮤니케이션 비용을 획기적으로 줄일 수 있다.
실행 가능한 문서
Swagger UI를 통해 프론트엔드 개발자는 API를 연동하기 전에 요청과 응답을 직접 테스트해 볼 수 있다. 이는 문서에 대한 신뢰도를 높이고, 연동 시 발생할 수 있는 시행착오를 줄여준다.
물론 툴을 설치한다고 끝나는 것은 아니다. 자동화가 해결해 주는 영역과 사람이 챙겨야 할 영역을 명확히 해야 한다.
자동화 영역
URI, 메서드, 파라미터 타입, 필수 여부 등은 코드를 통해 100% 자동화하여 실수를 방지한다.
인간의 개입 영역
단순히 필드명만 나열해서는 의도를 알 수 없다. 백엔드 개발자가 코드 작성 시 API의 목적, 예외 케이스, 데이터 예시 등을 꼼꼼히 기재하도록 팀 내 컨센서스를 맞춰야 한다.
결국 핵심은 '코드 자체가 문서가 되게 하는 환경'을 구축하는 것이다. 이를 위해서는 백엔드 팀의 협조와 초기 설정 리소스가 필요하겠지만, 장기적으로 팀 전체의 커뮤니케이션 비용을 줄이고 개발 생산성을 높이는 가장 확실한 투자라고 생각한다.
회고
돌이켜보면 모든 문제의 근원은 소통의 단절과 체계의 부족이었다. 코드 품질만큼 중요한 건 코드를 둘러싼 협업 환경이다. 빠른 결과만 강조하다 보면 장기적인 개선은 뒤로 밀리고, 결국 같은 문제가 반복된다. 기획·디자인과의 소통 부족이나 변경 관리 시스템 같은 문제는 팀 전체의 협력이 필요하다. 그러나 현재 팀 구조나 회사 문화 속에서는 이런 변화를 추진할 동력이 부족하다. 늘 "빨리빨리"만 외치며 눈앞의 불만 끄다 보니, 정작 장기적인 개선은 뒷전이 되곤 했다.
마무리
이 글은 단순한 푸념이 아니라, 내가 직접 겪은 문제를 분석하고 실행 가능한 해결책을 고민한 결과다. 지난 시간 동안 작은 개선이라도 만들어보려고 꾸준히 시도해왔다. 하지만 같은 문제들이 다시 반복되는 경험을 피할 수 없었다.
그럼에도 불구하고 이 과정에서 얻은 통찰은 분명히 있었다. 혼자만의 영역에서 끝나는 게 아니라, 팀 전체의 협업 체계를 더 나은 방향으로 이끌고 싶다는 의지가 더 단단해졌다.
개발자는 결국 문제 해결자다. 코드뿐 아니라 팀의 협업 체계까지 문제 해결의 영역으로 확장하는 것이 내가 지향하는 개발자의 모습이다. 비록 지난 노력들이 당장 큰 변화를 만들지는 못했지만, 그 흔적과 고민이 쌓여 언젠가는 더 나은 환경으로 이어질 거라 믿는다.