레거시 어드민 페이지를 Claude로 리디자인하며 배운 것들

금요일 아침, 업무 요청이 하나 들어왔다.

뷰어 제품과 같이 나가는 가벼운 어드민 페이지가 있는데, 디자인이 너무 올드해 보이니 현대적으로 바꿔줄 수 없냐는 것이었다. 따로 디자인 시안은 없고, "알아서 깔끔하고 센스있게 스타일링"해달라는 게 요구사항이었다.

전달 받은 페이지를 열어보니 디자인이 생각보다 더 올드했다.

HTML, CSS, JS로 짜인 페이지였고, CSS만 적당히 손보면 금방 끝날 것 같아서 하루 안에 끝낼 수 있다고 당차게 말씀 드렸다.

그땐 몰랐다. 내가 이 작업 때문에 야근까지 하게 될 줄은..

첫 번째 시도: 디자인 토큰 적용하기

가장 빠른 방법부터 시도했다. 회사에서 주로 쓰는 색상과 글자 크기 정보를 정리해 token.css를 새로 만들고, Claude Code에게 이 토큰을 기반으로 기존 페이지들의 스타일을 바꿔달라고 요청했다. 작업 전에 결과물을 미리 확인해야 하니, preview.html을 먼저 만들어 보여달라고도 덧붙였다.

결과는? 색상과 폰트는 분명 잘 반영이 되었으나, 올드한 디자인에 색상만 새로 입힌 느낌을 벗어나지 못했다. 헤더 버튼과 모달 버튼의 스타일이 서로 다른 것처럼, 컴포넌트 간 디자인 일관성도 부족해 보였다.

이전보다는 나아졌으나, 이 애매한 디자인으로 구현 시키기엔 내 성에 차지 않았다. (이때까지만 해도 '반나절 만에 이렇게 멋지게 업데이트했단 말이야?' 같은 반응을 들을 수 있을 줄 알았다.)

두 번째 시도: Claude Design한테 디자인을 맡기기

그래서 마침 내가 사이드 프로젝트에 자주 사용하고 있는 Claude Design을 사용해서 디자인을 다시 하기로 마음을 먹었다.

Claude Design은 프롬프트와 참고 이미지만으로 UI 디자인 시안을 만들어주는 Anthropic의 디자인 도구다.

Claude Code에게 먼저 페이지의 기능 스펙을 정리해달라고 요청하고, 그 스펙 문서와 화면 캡처 이미지, 토큰 파일을 Claude Design에 함께 전달했다. 기능은 그대로 유지하되 디자인만 새로 해달라는 요청이었다.

역시! 첫 번째 시도 때는 개발자가 억지로 디자인을 한 느낌이었다면, 이번엔 디자이너가 각잡고 만든 느낌이 들었다. 컴포넌트 간 일관성도 있었고 전체적으로 깔끔해졌다.

문제는, 여기서 내가 욕심을 냈다는 것이다.. 디자인이 괜찮아지니, 보기 불편하던 레이아웃까지 손대고 싶어졌다.

사용자 프로필이 왼쪽 사이드바에 위치 -> 상단 헤더 오른쪽에 위치하는게 더 자연스럽지 않나?
검색바가 툴바가 아닌 헤더 오른쪽에 고정 -> 검색바가 필요한 페이지에만 노출되는게 맞지 않을까?
설정 모달 내 활성화/비활성화 선택에 드롭다운 사용 -> 토글 컴포넌트가 더 직관적이지 않을까?

레이아웃-before-after

이런 구식 UX들을 자연스럽게 개선해달라고 추가로 요청했다. Claude Design은 요구사항에 맞게 결과물을 잘 뽑아줬고, 검토를 마친 뒤 압축 파일로 추출해 Claude Code에 넘겼다. 돌이켜보면, 디자인 개선과 UX 구조 변경을 한 번에 묶은 게 내 첫 번째 실수였다.

검토 체크포인트를 스스로 건너뛰다

Claude Code는 전달받은 디자인을 바탕으로 작업 플랜 문서를 만들었다. 하나의 Task를 6개 정도로 쪼개고, 각 Task가 끝날 때마다 검토받도록 설계된 플랜이었다. 문서 자체엔 문제가 없어 보여 작업을 승인했다.

문제는 그다음이었다. 오후에 다른 일이 몰려서 바빠진 나는, Task 3까지만 확인하고 이상이 없자 그 뒤로는 검토 없이 한 번에 진행하라고 지시해버렸다. 플랜에 검토 체크포인트를 넣어놓고 정작 나 스스로 그걸 지키지 않은 것, 이게 두 번째 실수였다.

작업을 완료했다는데..

작업이 끝났다는 알림을 받고 페이지를 열어봤다. 결과는 상당히 당황스러웠다.

레이아웃이 전반적으로 깨져 있고
잘 동작하던 기능 일부가 동작하지 않으며
원래 있던 컴포넌트들이 보이지 않았다

아무래도 레이아웃이 깨진게 가장 먼저 눈에 띄니 원인을 찾으려 코드를 살펴보았다. 인라인 스타일을 동적으로 덧붙이는 jQuery 코드가 페이지 곳곳에 흩어져 있었다. 어떤 요소의 스타일이 어디서, 어떤 조건에 어떻게 바뀌는지 한 파일만 봐서는 알 수가 없는 구조였다.

Claude에게 버그 수정을 여러 차례 요청했지만, 한 곳을 고치면 다른 이벤트 핸들러가 덮어쓴 인라인 스타일 때문에 버그가 다른 자리에서 다시 터졌다. 상태와 스타일이 파일 전체에 흩어져 정적으로 추적하기 어려운 레거시 코드베이스 구조 자체가 원인이었다.

이 지점에서 리액트 같은 컴포넌트 기반 프레임워크가 왜 소중한지를 오랜만에 체감했다. 컴포넌트 단위로 짜다 보면 상태 로직과 그 상태를 그리는 UI 코드가 자연스럽게 가까운 곳에 붙어 있게 된다. jQuery처럼 이벤트 핸들러마다 스타일 조작 로직이 따로 흩어질 일이 없으니, 어떤 상태가 바뀌면 화면 어디가 영향받는지 코드 구조만 보고도 추적할 수 있다는 게 디버깅에 있어 얼마나 편리한건지 새삼 느꼈다.

세 번째 시도: 범위를 좁히고 다시 시작하기

퇴근 시간이 이미 지났는데도 수정 요청이 끝나지가 않았다. 이대로는 오늘 안에 절대 완료할 수 없겠다는 판단이 들어서, 지금까지의 변경 사항을 전부 stash하고 처음부터 다시 시작하기로 마음을 먹었다.

UX 변경과 디자인 개선을 분리하기

가장 먼저 한 일은 Claude Design에 기존 레이아웃 구조는 그대로 둔 채 디자인만 다시 수정해달라고 요청한 것이었다. 프로필 위치가 사이드바에서 헤더로 옮겨가는 등 구조 자체가 바뀌다 보니 코드 전반에 영향이 컸고, 이게 문제를 더 키우고 있었다. UX 개선은 디자인 작업이 끝난 뒤 별도 작업으로 진행하는 게 더 안전하다고 판단했다.

Task를 영역별로 더 잘게 쪼개기

Claude Code에게 다시 작업을 요청할 때는 세 가지를 바꿨다.

Task를 헤더, 사이드바, 툴바 등 화면 영역별로 더 세밀하게 나누기
각 Task를 시작하기 전, 해당 영역의 디자인 시안을 다시 한번 확인하고 구현 시작하도록 지시
각 Task가 끝나면 예외 없이 내게 검토를 받기

매 Task를 시작하기 전 디자인 시안을 다시 한번 짚고 넘어가니, 확실히 디자인 정확도가 눈에 띄게 올라갔다. 시안을 계속 곁에 두고 구현하니 세부적인 디테일을 놓치는 일이 훨씬 줄었다.

이번엔 Task가 끝날 때마다 기존 기능이 그대로 동작하는지 하나하나 확인했다. 몇 시간이면 끝날 줄 알았던 작업은 결국 밤 10시쯤에 마무리됐다.

레슨 런

처음엔 '그냥 HTML랑 CSS 파일 몇개 수정하는 건데 금방 끝나겠지'라고 가볍게 생각했다. 하지만 오히려 레거시 코드베이스라서 더 까다로웠다. 상태와 스타일이 여기저기 흩어진 구조는, 사람에게도 AI에게도 똑같이 추적하기 어려운 대상이었다.

이번 작업에서 내가 저지른 실수는, 변경 범위를 한 번에 너무 크게 묶고, 스스로 설계한 검토 체크포인트를 지키지 않은 것이었다. 디자인 개선과 UX 구조 변경을 동시에 요청하는 순간 변경 범위가 눈덩이처럼 불어났고, Task 사이 검토를 건너뛴 순간 문제를 빠르게 발견할 기회도 함께 사라졌다.

디자인 변경과 구조(UX) 변경 요청은 분리해서 요청하자.
Task는 화면 영역 단위로 잘게 쪼개자. Task가 커질수록 검토도 대충 하게 된다.
Task를 시작하기 전, 해당 영역의 디자인 시안을 다시 확인하도록 명시적으로 지시하자.
계획에 넣어둔 검토 체크포인트는 바쁘다는 이유로 건너뛰지 말자.

아무리 AI 성능이 뛰어나도, 결과물이 정확하게 나오려면 인간의 설계와 원칙 지키기가 얼마나 중요한지 다시 한번 체감했던 경험이었다.