“아름다운 코드는 결국 아름다운 시스템을 만든다.” Claude Code와 함께 11개의 핵심 기능을 POC로 단숨에 완성한 뒤,
개발자가 아닌 사용자의 시각으로 시스템을 다시 바라보았다.
기능은 어느정도 돌아가는 정도는 되었지만, 페이지마다 개성이 너무 뚜렷하여 눈의 피로를 유발하는 어두운 테이블, 그리고 에러 발생 시의 불친절한 피드백들이 눈에 띄었다.
오늘의 미션 : 디자인 시스템을 정립하고, 브랜드 일관성을 확보하기!
철저한 테스트 케이스(TC)를 통해 프로덕션 환경에서도 흔들리지 않는 품질 관리(QC)를 완성하는 것을 추가 목표로 잡았고 AI와 티키타가 하면서 4시간 동안 진행된 이 ‘품질 마라톤’을 진행 했다.
1. 디자인 시스템 – ‘Indigo’의 우아함으로 통일하다
먼저 해결할 과제는 디자인의 파편화였습니다. 프로젝트 전체를 조사한 결과, 무려 17개의 서로 다른 파란색 계열이 혼용되고 있었고, 이는 개성이 뚜렷한 하울의 움직이는 성 같았다.
ㄱ. 컬러 팔레트와 디자인 토큰 설계
우리는 브랜드 일관성을 위해 Soft Indigo 테마를 중심에 두었고, 여러 컬러를 선택 하면서 테스트 해보니 부드러운 인디고 계열을 사용하면 장시간 시스템을 사용하는 번역가들의 눈 피로도를 대폭 낮출 수 있겠다 싶었습니다.(일단… 내 눈 부터 보호를…!)
1. 메인 컬러(Primary): Indigo 400(#818CF8)을 메인으로, 호버 시에는 Indigo 500(#6366F1)을 사용하도록 CSS 변수를 중앙 집중화
2. 배경 및 텍스트: 순수 검정 대신 부드러운 다크 그레이(#2C3E50)를 사용하고, 배경은 눈이 편안한 오프 화이트(#FAFAFA) 채택
3. 그림자 토큰: 단순한 검은색 그림자가 아닌, Indigo 계열이 섞인 부드러운 그림자(rgba(129, 140, 248, 0.1))를 사용하여 UI에 깊이감을 더함
4. 라운드 토큰: 12px(sm)부터 24px(xl)까지 정교한 라운드 값을 정의하여 모던하고 신뢰감 있는 인상주기
ㄴ. 테이블 디자인의 혁신
기존의 어두운 테이블 헤더는 밝은 배경과 이질감이 심해 장시간 사용 시 눈이 아팠다. 이를 해결하기 위해 Light Indigo 그라데이션 테마 적용
1. Sticky Header: 헤더를 상단에 고정하고 Indigo 테두리를 둘러 가독성을 높임
2. Hover Effect: 행(Row)에 마우스를 올리면 연한 인디고 배경이 깔리며 살짝 떠오르는 효과를 주어, 어떤 데이터를 보고 있는지 직관적으로 개선
2. 품질 관리(QC) – 테스트 없는 배포는 없다
“테스트 없이 배포하는 것은 낙하산 없이 비행기에서 뛰어내리는 것과 같다.”
그래서, 3계층 테스트 피라미드 전략을 세우고, 핵심 경로(Critical Path)에 대해 철저한 검증을 수행했다.
ㄱ. API 통합 테스트 (Integration Tests)
Claude Code와 함께 작성한 주요 테스트 시나리오는 아래와 같다
1. 자동 매칭 검증
: 원문을 입력했을 때 용어집(Glossary)에 등록된 단어가 있으면 AI를 거치지 않고 자동으로 채워지는지, 그리고 재사용 횟수(Hit Count)가 정상적으로 증가하는지 확인
2. 동시성 충돌 테스트
: 두 사용자가 동시에 같은 문장을 수정할 때, 시스템이 타임스탬프를 대조하여 정확히 충돌(409 Conflict)을 감지하고 데이터 덮어쓰기를 방지하는지 시뮬레이션 진행
3. 보안 필터링
: 4.5MB 이상의 대용량 파일이나 악성 확장자(.php,.exe등) 업로드 시 시스템이 보안 수칙에 따라 안전하게 거부하는지 검증
ㄴ. 전체 품질 보증 (TQC)
단순 기능 테스트를 넘어 전체 시스템의 안정성을 점검했다.
1. 데이터 일관성: 부모 레코드가 삭제되었을 때 남겨진 고아 레코드(Orphan Record)가 없는지 SQL 쿼리로 전수 조사
2. 성능 프로파일링: API별 응답 시간을 측정하여, 벌크 생성 API처럼 1초 이상 소요되는 엔드포인트를 찾아 최적화 우선순위를 정함
3. 에러율 모니터링: 총 1,247회의 호출 중 99% 이상의 성공률을 확인했으며, 미세한 서버 에러(500) 1건까지 원인 추적
3. 실전 디버깅 마라톤 – 무한 루프 탈출기
개발 막바지, React의 ‘Maximum update depth exceeded’ 에러, 즉 무한 루프 지옥에 빠지는 순간왔다.
1. 원인: 제품 선택 시 기본 언어를 자동 설정하는 로직에서, 매번 새로운 배열을 생성하여 상태를 업데이트함으로써
useEffect가 무한히 재실행되고
2. 해결:setSelectedLanguages함수를 의존성 배열에서 제거하고, 불필요한 배열 생성을 방지하여 렌더링 성능 안정화
3. 교훈: AI가 코드를 생성해주더라도, 상태 관리의 기본 원칙을 지키는 것은 여전히 인간 개발자의 중요한 역량임을 깨달음
4. 숫자로 증명하는 프로젝트 완성도
1. 성능 점수(Lighthouse): 접근성 96점, 베스트 프랙티스 100점, SEO 90점 획득
2. 테스트 커버리지: 비즈니스 핵심 경로 100%, 전체 API 85% 완료.
3. 디자인 일관성: Indigo 단일 팔레트 및 8px 그리드 시스템 전면 적용
4. 코드 품질: ESLint 및 TypeScript 에러 0건 달성
5. 1차 5일간의 여정을 마치며!
AI는 최고의 도구이자 파트너였다.
Day 1 아키텍처 설계부터 Day 5 품질 완성까지, 5일 만에 엔터프라이즈급 번역 관리 시스템을 1차 완료 하였다.
고도화 할 것은 많이 남았지만, 이렇게 돌아갈 수 있다고 명시적으로 볼 수 있었다.
AI가 아니였다면, 불가능했을 속도였다.
하지만 더 중요한 교훈은 AI는 강력한 도구일 뿐, 최종 완성도는 인간의 영역이라는 점을 느꼈다.
그 이유는 색상의 미세한 톤을 고르는 감각, 사용자의 동선을 배려하는 UX 직관, 그리고 “어디까지 테스트할 것인가”를 결정하는 품질 기준은 오직 인간만이 정할 수 있었다.
“완벽한 코드는 없지만, 완벽을 향해 나아가는 과정이 AI가 나를 성장 시킨 것 같았다.”
이번 프로젝트를 통해 얻은 디자인 시스템과 자동화된 품질 관리 노하우는, 앞으로 우리가 마주할 수많은 프로젝트의 견고한 밑거름이 될 것이다.