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