docs: 2026-05-25-fontend post

Author: TreeStone94

_posts/frontend/2026-05-25-frontend.md

@@ -0,0 +1,109 @@
+---
+title: "레거시 UI 빌드 개선기 (4) - 팀 전체를 터보로 이전하기"
+description: "팀 전체를 터보로 이전하는 과정 및 마무리"
+date: 2026-05-25 +00:00:00
+permalink: /posts/2026-05-25-frontend/
+mermaid: true
+categories: [Blogging,frontend]
+---
+
+<style>
+  .content .table-wrapper {
+    max-width: 100%;
+  }
+
+  .content .table-wrapper > table {
+    width: 100%;
+    table-layout: fixed;
+  }
+
+  .content .table-wrapper th,
+  .content .table-wrapper td {
+    white-space: normal;
+    word-break: keep-all;
+    overflow-wrap: anywhere;
+  }
+</style>
+
+빌드가 빨라졌고, 운영에 올릴 수 있는 상태도 갖췄습니다.
+
+하지만 이것만으로는 끝나지 않았습니다. 터보 레포에서 빌드가 잘 된다고 해서 팀 전체가 자연스럽게 터보로 옮겨오지는 않습니다. 레거시 레포에 익숙한 개발자들이 있고, 각자의 브랜치가 있고, 배포 파이프라인도 그대로였습니다.
+
+이제 남은 건 팀 전체가 실제로 터보를 쓰게 만드는 것이었습니다.
+
+## 경험 먼저, 강제 나중
+
+전환을 시작하는 방법에는 두 가지가 있습니다.
+
+첫째는 강제입니다. 레거시 레포 권한을 없애고 터보로만 작업하게 합니다. 빠르지만, 개발자가 아직 터보 워크플로우에 익숙하지 않은 상태에서 강제하면 거부감이 생깁니다. "왜 이걸 바꿔야 해?"라는 질문이 나오고, 그 질문에 답하는 시간이 필요해집니다.
+
+둘째는 먼저 써보게 하는 것입니다. 터보를 먼저 경험하게 하고, 차이를 직접 느끼게 합니다. 50분이 100초가 되는 것을 직접 써보면 굳이 설명하지 않아도 됩니다. 그다음에 강제하면 거부감이 훨씬 적습니다.
+
+그래서 이 순서로 진행했습니다. 개발 서버를 먼저 터보로 전환해 개발자가 빠른 빌드를 직접 경험하게 하고, 그다음에 컷포인트(전환 기준점)로 강제했습니다.
+
+## 단계별 전환 전략
+
+전환은 한 번에 하지 않았습니다.
+
+충격을 분산하기 위해 두 개의 컷포인트를 두고, 그 사이에 적응 기간을 뒀습니다.
+
+![image.png](/assets/img/frontend/2026-05-25-frontend-01.png)
+
+### 브랜치 보호가 필요한 이유
+
+준비 단계에서 터보 레포에 브랜치 보호를 먼저 건 데는 이유가 있습니다.
+
+auto-sync 파이프라인은 레거시 빌드가 성공하면 자동으로 터보 레포 servicedev 브랜치를 업데이트합니다. 개발자가 servicedev 브랜치에 직접 push하면 다음 sync가 그 변경을 덮어씁니다. 브랜치 보호가 없으면 이 실수가 반복됩니다.
+
+처음부터 MR 습관을 정착시키기 위해 준비 단계에 함께 적용했습니다.
+
+### 파일 종류별 변경 채널
+
+1차 컷포인트 이후에는 파일 종류에 따라 변경 경로를 나눴습니다.
+
+| 파일 | 변경 경로 |
+| --- | --- |
+| 비즈니스 소스 (`src/app/`, `src/www/`) | 터보 feature 브랜치 → sync 스크립트 → 레거시 MR |
+| 레거시 전용 파일 (`webpack.config.js`, `package.json` 등) | 레거시 레포 MR → 배포 담당자 머지 |
+
+레거시 전용 파일 변경 빈도는 낮기 때문에 담당자 경유 병목은 수용 가능한 수준이었습니다.
+
+## 어떤 플랫폼부터 올려야 할까
+
+여러 플랫폼에 동시에 올리는 것은 선택하지 않았습니다.
+
+한 번에 올리면 문제가 생겼을 때 어느 플랫폼이 원인인지 파악하기 어렵습니다. 동시에 여러 플랫폼에서 이슈가 터지면 대응도 느려집니다.
+
+그래서 트래픽이 적고 사용자 범위가 좁은 플랫폼부터 순차 적용했습니다. 실패해도 영향이 가장 작은 곳에서 먼저 검증하고, 안정이 확인되면 다음으로 넘어가는 방식입니다.
+
+```
+개발 서버 → 공공 플랫폼 → 의료 플랫폼 → 운영 플랫폼
+```
+
+공공 플랫폼은 트래픽이 가장 적어 첫 번째 검증 대상으로 적합했습니다. 여기서 이슈가 발견되면 다음 플랫폼에 올리기 전에 수정할 수 있습니다. 의료 플랫폼은 그다음으로 사용자가 많고, 운영 플랫폼은 가장 넓은 사용자를 가지고 있어 마지막에 배치했습니다.
+
+각 플랫폼의 배포는 3편에서 설명드린 병렬 빌드·검증 후 터보 빌드로 전환하는 시나리오를 기준으로 진행합니다. 자세한 배포 흐름은 [3편 링크](https://treestone94.github.io/posts/2026-05-24-frontend/#%EB%B3%91%EB%A0%AC-%EB%B9%8C%EB%93%9C-%EA%B8%B0%EB%B0%98-%EB%A1%A4%EB%B0%B1-%EA%B5%AC%EC%A1%B0)에서 확인할 수 있습니다.
+
+## 레거시 레포의 마지막
+
+2차 컷포인트는 운영 플랫폼 전환이 안정화된 뒤 실행했습니다.
+
+레거시 레포에서 개발자 멤버를 전원 제거하고 CI 봇 계정만 남겼습니다. auto-sync 파이프라인은 계속 동작해야 하기 때문에 봇 계정의 Maintainer 권한은 유지했습니다.
+
+이 시점 이후 레거시 전용 파일 변경이 필요하면 배포 담당자가 직접 처리합니다. 일반 개발자는 사내 메신저나 Jira로 요청하고, 담당자가 반영합니다.
+
+모든 플랫폼이 안정적으로 운영된 뒤 레거시 레포를 아카이브했습니다. read-only 상태로 히스토리만 남겨 더 이상 코드를 넣을 수 없게했습니다.
+
+## 마무리
+
+![스크린샷 2026-05-14 오후 4.28.31.png](/assets/img/frontend/2026-05-25-frontend-02.png)
+
+처음 이 프로젝트를 시작할 때는 “내가 신입 때부터 이어져 온 문제를 정말 고칠 수 있을까?”라는 막연한 두려움이 있었습니다.
+
+오랜 기간 관행처럼 유지되어 온 빌드 구조였고, 쉽게 바꾸기 어려운 문제라고 생각했습니다. 하지만 연차가 쌓이면서 문제를 바라보는 시야가 넓어졌고, 팀장이라는 역할을 맡으며 팀원들과 함께 개선 방향을 주도적으로 논의할 수 있었습니다.
+
+부족한 부분은 AI를 활용해 보완하고, 설계와 검증을 반복하면서 점진적으로 개선해 나갔습니다. 그 결과 단순히 빌드 시간을 줄이는 것을 넘어, 팀이 더 안정적으로 개발하고 배포할 수 있는 구조로 전환을 마무리할 수 있었습니다.
+
+AI가 빠르게 변화시키는 시대 속에서 개발자로서의 고민은 여전히 많습니다. 하지만 저는 개발자는 결국 **문제를 정의하고, 해결 방법을 찾아 끝까지 개선해 나가는 사람**이라고 생각합니다.
+
+이번 빌드 개선 역시 AI가 있었기 때문에 가능했던 부분도 있지만, 더 중요한 것은 오랫동안 당연하게 여겼던 문제를 다시 바라보고, 실제로 바꿔보려는 시도였습니다. 관행으로 남아 있던 문제도 결국 해결할 수 있다는 경험이, 이번 프로젝트에서 가장 큰 의미였습니다.