for my job/AI SW WAVE 복기

[AI 활용 기록] 하네스로 디자인 시스템과 프론트엔드를 이틀안에 개선하기

지그농 2026. 7. 12. 00:18

지난 시간에는 기획안과 디자인 시스템 문서를 넘기고 곧장 목업부터 만들었다. 4시간 만에 화면은 예상보다 빠르게 형태를 갖췄지만, 핵심 기능인 드래그앤드롭이 아예 동작하지 않고, 완료 체크를 하면 체크박스가 화이트톤에 묻혀 안 보이고, 상태 관리 코드 한 줄이 화면을 무한 루프에 빠뜨리는 결함들이 뒤늦게 드러났다.

 

 

[AI 활용 기록] 기획안을 문서화해서 AI에게 넘기면, 프론트 목업이 바로 나올까?

오늘의 시도기획에서 디자인, 디자인에서 코드로 이어지는 변환 과정을 AI가 각 단계마다 얼마나 메워주는지 보는 것을 목적으로 figma로 제작한 기획안을 마크다운 파일로 문서화하고, 그 문서

jignonne.tistory.com

 

 

이번엔 순서를 바꿨다 — 스택부터 다시 정하고, 디자인 시스템을 세우고, 그 위에 지켜야 할 규칙을 얹은 뒤에야 화면을 고치기 시작했다. 그 과정에서 무엇이 나아졌고, 어디서 많이 헤맸는지를 기록해보았따.


배경

1차 시도는 기획안과 디자인 시스템을 마크다운 문서로 정리해 Claude CLI(Pro 계정)에 넘기고, 스택 조합(React 19, TypeScript, 지난 시도는 기획안과 디자인 시스템 문서를 Claude CLI에 넘기고 곧장 목업 제작을 맡기는 방식이었다. 결과물은 빨리 나왔지만, 위에서 언급한 결함들은 "기획 문서가 부실해서"가 아니라 문서와 컨텍스트만으로는 애초에 커버되지 않는 영역에서 나왔다. 아키텍처와 기능 구현 속도는 보장되지만, 디자인 디테일이나 실행 시점의 문제는 자동으로 도는 검증 장치 없이는 발견 자체가 우연에 의존했다.

 

그래서 이번엔 순서를 바꿔보기로 했다.

스택부터 다시 정하고, 디자인 시스템을 세우고, 그 위에 지켜야 할 작업 규칙(CLAUDE.md, permission.deny 등)을 얹은 뒤에야 화면을 고친다. 

 

이번 시도는 교육 과정에서 배운 하네스 엔지니어링을 실제로 적용해보는 실습이었다. 설계를 먼저 탄탄하게 세워두면 이후 작업이 실행-검증-수정으로 이어지는 안정적인 루프 안에서 진행될 수 있다는 걸 확인하고 싶었다.


시도 0 — 스택 전환: React+TS에서 Vue+Quasar로

목적

1차 시도는 React 19 + TypeScript + Zustand 조합으로 진행됐지만, 이번 재작업을 시작하기 전에 기획을 재검토하여 스택 자체를 Vue + Quasar로 바꾸기로 결정했다.

 

서비스의 메인 기능인 계획-일정-회고 구조나 목표 태깅처럼 폼과 리스트 상태가 화면 곳곳에 얽혀 있는 화면이 많았는데, Zustand 셀렉터 패턴으로는 이런 화면마다 상태 연결 코드를 매번 손으로 짜야 했고, 그 과정에서 셀렉터 안에서 배열을 새로 만들어버리는 실수 하나가 화면 전체를 무한 루프에 빠뜨리는 걸 1차 시도에서 이미 겪었다.

daily부터 monthly까지 일정 확인 테스트

 

Vue의 데이터 바인딩으로 이 부분을 구조적으로 단순화하고, 동시에 Quasar가 제공하는 완성된 UI 컴포넌트 세트로 화면을 더 빠르게 조립하고 싶었다.

(해당 부분은 강사님의 조언으로 해당 기술 스택 조합을 조사하면서 선택하게 되었고, Vue.js를 오랜만에 해보면서 React랑 비교를 해보며 많이 배울 수 있었다!)

 

과정

프로젝트 전체를 Vue 기반으로 재작성했다. React, Zustand 시절의 컴포넌트 트리와 상태 로직을 화면 단위로 옮기면서, 폼, 리스트, 모달처럼 양방향 바인딩이 반복적으로 필요했던 부분부터 우선 정리했다.

 

1차 시도에서 전혀 동작하지 않았던 드래그앤드롭도 @dnd-kit을 그대로 옮기는 대신, Vue 생태계의 드래그앤드롭 방식으로 새로 구현하기로 했다 — 실제 동작 검증은 시도 3에서 다룬다. src/css/tokens.css에 있던 raw 토큰 값(색상·radius·그림자)은 프레임워크와 무관한 CSS 커스텀 프로퍼티였기 때문에 그대로 들고 왔고, 이후 Quasar 테마 변수에 매핑하는 작업으로 이어졌다 — 이 부분은 시도 1에서 다시 다룬다.

 

결과

이후 진행한 시도 1~3은 모두 이 Vue + Quasar 기반 위에서 이뤄졌다. 스택 전환을 디자인 시스템 정리보다 앞에 둔 건, 프레임워크가 바뀌면 컴포넌트 구조와 상태 관리 방식이 함께 바뀌기 때문에, 그 위에 얹는 디자인 토큰이나 작업 규칙을 먼저 정해봐야 스택이 다시 바뀌는 순간 무의미해질 거라고 판단해서였다.

 

부수적으로, 1차 시도를 가장 오래 붙잡았던 Zustand 셀렉터 무한 루프의 근본 원인(셀렉터 안에서 매번 새 배열을 만드는 패턴) 자체가 Vue의 반응형 시스템으로 넘어오면서 구조적으로 사라졌다. (이때 완전 유레카! 잊고 지냈던 Vue의 특장점을 생각해볼 수 있었다.)

 

다만 이 전환 자체에 대한 회귀 검증은 시도 3 이후 "아쉬운 점 B"에서 다루는 자동화 부재 문제와 같은 한계를 그대로 안고 진행됐다 — 화면 하나하나를 손으로 눌러보며 확인하는 방식 외에는 없었다.


시도 1 — 디자인 시스템 구축

목적

코드(src/css/tokens.css)에는 색상, radius, 그림자 값이 이미 있었지만, 그게 Figma로 문서화하는 과정에서 효율적으로 반영할 수 있는 방법을 찾고싶었다. 컴포넌트를 새로 만들 때마다 "이 색을 써도 되는지, 이 그림자가 맞는 레시피인지"를 매번 코드를 뒤져서 판단해야 했다. 코드와 디자인 표현이 따로 노는 상태를 먼저 정리하지 않으면, 화면을 아무리 고쳐도 일관성 없는 결과물이 반복될 거라고 판단했다.

과정

Figma MCP를 연결해 코드의 raw 토큰들을 Figma의 Variables, Effect Style, Text Style로 실제 생성하는 작업부터 시작했다. 색상 14개, radius 4개, 그림자(뉴모픽 이중 그림자 레시피) 5종, 타이포그래피 7단계까지는 순조롭게 Figma에 반영됐다.

MCP를 통해 Figma 페이지에 디자인 시스템 일부 반영

 

하지만 해당 Figma 프로젝트의 등급은 무료 버전이었기 때문에 MCP 호출이 월 6회로 제한되어, 완전한 작업 (프론트 코드→ Figma 디자인 컴포넌트 반영)을 진행하지는 못했다. 

 

여기서 방향을 바꿨다. Figma를 기다리는 대신, 코드를 마크다운 문서(tokens.md, components.md)에 같은 내용을 먼저 채워 넣는 쪽을 택했다. components.md는 특히 실제로 어떤 컴포넌트가 어떤 브랜드 컬러를 쓰는지 grep으로 확인한 결과를 그대로 옮긴 문서다 — 추측이 아니라 코드 근거를 남기고 싶어서였다.

완성된 Design System 문서화 작업

 

그리고 이번 세션에서는 한 걸음 더 나아가, Figma에서 막혔던 바로 그 시각화(색상 스와치, 그림자 레시피를 실제로 렌더링해서 보여주는 것, 컴포넌트×컬러 매핑 표)를 Claude의 Artifact 기능으로 만들어 직접 확인하는 방식도 시도했다. Figma 호출 한도라는 외부 제약이 막아선 지점을, 같은 목적을 가진 다른 도구로 우회해서 채운 셈이다. 동시에 시도 0에서 넘어온 tokens.css 값을 Quasar의 테마 변수($primary, $secondary 등)에 매핑하는 작업도 함께 진행했다.

 

Claude Artifact로 Figma로 인터랙션까지 구현하는 것 보다 훨씬 더 효율적이고 효과적으로 디자인 시스템을 확인할 수 있었다.

 

 

이 작업과 맞물려, PR 단위로는 별개였던 색상 슬롯 확장도 진행했다. 백엔드에서 카테고리 리소스가 최대 8개까지 지원한다는 걸 확인하고, 프론트엔드의 4개 고정 슬롯(rose/blue/green/lavender)을 amber/teal/plum/slate까지 더해 8개로 늘려 백엔드와 1:1로 맞췄다. (Claude의 agent-view로 동시에 최대한 효율적으로 작업할 수 있도록 집중했다.)

 

결과

frontend/design-system/ 아래의 tokens.md·components.md가 코드와 Figma 양쪽이 참조하는 실제 기준점이 됐다. Figma 쪽 색상·그림자·타이포는 이미 만들어져 있고, 좌석이 바뀌거나 월 한도가 리셋되면 정확히 어디서부터 이어가면 되는지도 문서에 남겨뒀다. Quasar 테마 변수도 같은 raw 토큰에서 매핑돼, 코드·Figma·Quasar 세 곳이 서로 다른 숫자를 갖는 상황은 일단 피했다 — 다만 이 매핑이 앞으로도 계속 수동으로 맞춰야 하는 구조인지, 자동으로 동기화할 방법이 있는지는 아직 확인하지 못했다. 색상 슬롯은 4개에서 8개로 확장돼 프론트-백엔드 간 데이터 모델 불일치가 해소됐다. 다만 Figma 안에서의 Foundations 시각화 자체는 여전히 미완성 상태로 남아 있다 — 이 부분은 뒤에서 다시 다룬다.


시도 2 — CLAUDE.md와 permission.deny로 하네스 만들기

목적

디자인 시스템이 "무엇을 써야 하는가"에 대한 규칙이라면, 이제 필요한 건 "어떻게 작업해야 하는가"에 대한 규칙이었다. 1차 시도에서 겪었던 문제 중 상당수는 사실 디자인 문제가 아니라 작업 절차의 문제였다 — 계획 없이 바로 코드를 고치고, 사용자 확인 없이 커밋하고, 위험한 명령을 실행할 수도 있는 상태로 매 세션을 시작하는 것 

반복되는 작업을 매번 대화로 다시 설명하는 대신 문서와 설정으로 고정해두고 싶었다.

과정

CLAUDE.mdArchitecture, Testing, Safety, Workflow 4개 섹션으로 나누고, 섹션당 3~4줄이라는 제약을 걸었다. 장황한 규칙 문서는 결국 안 읽는다는 전제로 작성하며, 한 번에 다 쓴 게 아니라 섹션별로 초안을 제시하고 확인받는 방식으로 채워나갔다.

 

문서만으로는 강제력이 없어서, 실제 위험한 동작은 .claude/settings.local.json의 permissions.deny로 한 번 더 막았다. 구체적으로는 force-push나 reset --hard 같은 되돌리기 힘든 git 명령, 프로덕션 배포 명령, .env 파일 접근을 막았다.

"deny": [
  "Bash(git push --force*)",
  "Bash(git push -f*)",
  "Bash(git reset --hard*)",
  "Bash(git clean -f*)",
  "Bash(git branch -D*)",
  "Bash(firebase deploy*)",
  "Bash(vercel --prod*)",
  "Bash(vercel deploy --prod*)",
  "Bash(netlify deploy --prod*)",
  "Bash(npm publish*)",
  "Read(**/.env)",
  "Read(**/.env.*)",
  "Write(**/.env)",
  "Write(**/.env.*)",
  "Edit(**/.env)",
  "Edit(**/.env.*)",
  "Bash(rm -rf*)"
]

 

 

Workflow 섹션에는 "수정 전 계획을 먼저 제시하고 승인받은 뒤 진행 → diff는 작게 → PR을 열기 전에 변경 내용을 먼저 공유하고 승인받은 뒤에만 push"라는 절차를 규칙으로 고정하였다. 해당 방식으로 진행하면 plan mode로 진행하지 않아도 원하는 절차로 먼저 제시하고 커밋 분기까지 처리할 수 있기 때문이다.

 

결과

이후 진행한 모든 화면 개선 작업이 실제로 "계획 제시 → 승인 → 작은 단위의 diff → 커밋 전 공유" 패턴을 따랐다. 규칙을 매번 다시 설명할 필요가 없어졌고, 위험한 git 명령이나 .env 접근을 사람이 매번 판단하지 않아도 되니 리뷰는 "이 변경이 맞는가"라는 본질적인 질문에만 집중할 수 있었다.


시도 3 — 화면별 UI/UX 반복 개선

디자인 시스템과 작업 규칙이 자리를 잡은 뒤에야 실제 화면 개선에 들어갔다. 열 건이 넘는 변경을 거쳤는데, 크게 다섯 갈래로 묶인다.

헤더 재구성

가장 먼저 손댄 건 상단 헤더였다. 날짜 이동 버튼과 사용자 아바타가 겹쳐 보이는 문제, 아바타가 왼쪽 내비게이션과 기능이 중복되는 문제가 눈에 띄었다. 전역 스타일 때문에 제목의 line-height가 버튼이나 테두리와 겹치는 버그도 함께 있었다.

(왼쪽)불필요한 정보가 포함된 변경 전 헤더 (오른쪽) UX 개선된 헤더

 

헤더를 오늘로 이동 / 날짜 이동(이전-날짜-다음) / 기간 토글(월간·주간·일간) 3분할 grid 구조로 다시 짰다. 라벨은 "오늘"→"today", "월간/주간/일간"→"monthly/weekly/daily"처럼 톤을 통일했다.

 

알림 버튼처럼 헤더에 남아 있던 불필요한 액션은 사이드바 하단으로 옮겼다.(기능 목적상 사이드바가 더 적합하다고 생각했다.)  결과적으로 헤더의 정보가 더 명확하게 하나의 구조로 정리됐고, 겹침 버그도 함께 사라졌다.

 

캘린더, 대시보드 재설계

월간 대시보드에서는 오늘이 속한 주를 테두리와 굵은 글씨로 강조하고, 그 라벨을 눌러 바로 해당 주간 대시보드로 이동할 수 있게 했다. 페이지와 캘린더 그리드를 flex로 연결해 뷰포트 높이에 맞춰 반응형으로 채워지도록 손봤다. 또한 목표를 설정할 때 카테고리 태그 목록 중 적합한 태그가 없는 시나리오를 반영하여 카테고리 추가 모달 연결 등 UX를 일부 개선하였다.

UX 개선된 월간 캘린더와 대시보드

 

 

가장 크게 손댄 곳은 주간 대시보드였다. 기존에는 요일별로 카드가 세로로 쌓여 있는 구조였는데, 이걸 06:00~24:00 시간축을 가진 타임라인 그리드로 완전히 새로 그렸다.

 

일정을 실제 시작 시각과 길이에 맞춰 위치와 높이로 배치하고, 카테고리 색을 틴트+테두리 블록으로 표시했다. 전체 폭에 걸친 현재 시각 표시선도 추가했다. 카드 스택 방식으로는 "지금 몇 시에 무슨 일정이 겹쳐 있는지"가 한눈에 안 들어왔는데, 시간축 기반으로 바꾸고 나니 하루의 밀도가 시각적으로 바로 읽히게 됐다.

 

(왼쪽) 불필요한 정보와 액션이 구현된 이전 작업 (오른쪽) UX 개선된 주간 대시보드

 

주간 목표 설정 UX 개선 화면 (월간 캘린더 목표와 연결)

 

이 타임라인을 다시 그리면서, 1차 시도에서 정상적으로 동작하지 않았던 드래그앤드롭도 함께 검증했다. 시도 0에서 Vue 생태계 방식으로 새로 짜둔 구현을 이 화면에 실제로 붙여, 블록을 끌어다 시작 시각을 바꾸는 동작이 눈으로 확인될 때까지 손으로 눌러가며 확인했다.

 

Quasar로 잘 구현되는 유연한 일정 변동 기능 (drag and drop)

데일리 저널 재구조화

'통합 기록'이라는 서비스 기능 이름부터 문제였다. 기획상으로는 계획-실행-회고를 한 화면에서 다루는, 노션과 다이어리를 대체하는 화면이었는데 '통합'이라는 단어가 그 의도를 전혀 드러내지 못했다. 이름을 '데일리 저널'로 바꾸는 것부터 시작해서, 화면 구조 자체를 계획-일정-회고 3단으로 다시 설계했다.

 

(왼쪽) 불분명한 서비스 기능과 화면 (오른쪽) 하루 계획-등록된 일정-회고 진행으로 UIUX 개선

 

체크리스트 형태였던 '계획' 영역은 오늘의 다짐을 텍스트로 적고 명시적으로 저장하는 방식으로 바꿨다 — 1차 시도에서 완료 체크 시 화이트톤에 묻혀 안 보이던 체크박스 문제가, 이 영역에서는 체크박스 자체를 없애면서 자연히 사라졌다.

 

'일정'은 시간순으로 정렬하고 완료 체크와 함께 연결된 목표를 드롭다운으로 태그할 수 있게 했는데, 여기 남겨둔 체크박스에서는 또 다른 문제가 새로 발견됐다 — 클릭하면 엉뚱하게 대시보드로 이동해버리는 버그였다. 체크박스의 시각적 표현을 담당하는 요소가 "클릭해도 다른 동작을 막아야 하는 대상" 목록에서 빠져 있었던 게 원인이었고, 이벤트가 발생한 요소에서 가장 가까운 조상 요소를 찾아 판단하는 방식으로 더 견고하게 고쳤다. '회고'는 AI가 제안하는 멘트를 상시 노출하다가, 사용자가 등록하면 모달에서 작성 후 주간 회고 페이지로 자연스럽게 넘어가도록 만들었다.

 

유연한 계획 수정과 AI의 회고 가이드 라인 (해당 부분은 AI 모델이 연결되어 추후 개인 맞춤화 멘트 제공 기대), 그리고 회고 작성 모달

 

특히 회고 입력 기능은 별도의 모달 형태로 설계하였다. 회고 작성 영역을 항상 화면에 노출하는 것은 사용 흐름상 불필요하다고 판단했기 때문이다. 회고는 하루를 마무리하는 과정에서 작성하는 기능인 만큼, 사용자가 그날 세운 목표와 완료한 일정, 완료하지 못한 일정을 모두 확인한 뒤 자연스럽게 작성할 수 있도록 UX를 구성하였다.

 

BX, 로고 개선

이 시점까지 Plango에는 별도의 로고 자산이 없어 헤더, 랜딩페이지, 인증 화면 등 주요 화면에서 모두 텍스트 형태의 "Plango"만 사용하고 있었다. 이에 직접 제작한 로고를 바탕으로 BX 개선 작업을 진행하였다.

기획안 작성시 만들었던 로고와 설명글

 

재사용 가능한 로고 컴포넌트를 제작하여 주요 화면의 텍스트 로고를 모두 이미지 로고로 교체하고, 새로운 로고에 맞춰 파비콘도 함께 제작하였다. 특히 랜딩페이지는 단순히 로고를 교체하는 것에 그치지 않고, 서비스의 첫인상을 강화할 수 있도록 로고의 배치와 크기, 시각적 균형을 여러 차례 검토하며 브랜딩 완성도를 높였다.

로고 반영 랜딩 페이지

 

또한  레이아웃을 다듬는 과정에서 섹션 간 간격을 조정하고 CSS 특이성으로 인해 section 스타일이 .wrap에 의해 덮어쓰이는 문제를 발견하여 section.wrap으로 수정하였다. 이를 통해 화면의 여백과 구조가 의도한 대로 적용되었고, 로고 개선과 함께 랜딩페이지 전반의 시각적 완성도를 높일 수 있었다.

(왼쪽) UI 레이아웃 수정 전 (오른쪽) UI 개선 후

설정 화면

마지막으로 설정 화면의 UI를 전반적으로 개선하였다. 기존 화면은 기획 단계에서 사용하던 번호 표기와 넓은 웹 화면에 맞지 않는 일정한 그리드 간격이 그대로 적용되어 있어 완성도가 다소 떨어졌다.

 

개선 전 - 여백 및 배치가 비효율적인 화면

이에 실제 서비스 화면을 기준으로 레이아웃과 여백, 정보 배치를 전면적으로 재구성하여 넓은 화면에서도 콘텐츠가 균형 있게 배치되도록 개선하고, 보다 직관적인 설정 화면을 구현하였다.

개선 후 - 화면 활용도 개선

 


이번 시도로 배운 점

스택 전환은 그 위에 아무것도 없을 때가 가장 비용이 저렴하다. 디자인 시스템이나 작업 규칙을 먼저 세워둔 뒤였다면, React에서 Vue로 넘어가면서 그 규칙들을 다시 검증하거나 새로 써야 했을 것이다. 아무것도 없는 상태에서 스택부터 바꾸고 그 위에 다른 결정들을 얹은 순서가 결과적으로 재작업을 줄였다.

 

때로는 하네스보다 근본 원인 제거가 더 효과적이다. 1차 시도의 Zustand 무한 루프는 원래대로라면 "셀렉터 안에서 배열을 새로 만들지 말 것" 같은 규칙을 하네스에 고정하고 지켜지는지 매번 검증하는 식으로 대응했을 문제다. 그런데 스택을 Vue로 바꾸면서 그 패턴 자체가 코드에서 사라졌다. 재발 방지 규칙을 만드는 것과, 그 규칙이 아예 필요 없어지는 조건을 만드는 것 중 후자가 가능하다면 그쪽이 더 근본적이라는 걸 확인했다.

 

문서를 코드에 종속시키면 외부 제약에도 작업이 끊기지 않는다. tokens.md를 소스 오브 트루스로 먼저 채워두고 Figma는 나중에 따라잡는 순서로 두니, 월 6회라는 호출 제한이 전체 작업의 발목을 잡지 못했다. Figma에서 막힌 시각화를 Artifact로 대신 만들어본 것도 같은 맥락이다 — 특정 도구가 막히면 그 도구가 아니라 "무엇을 보여주고 싶었는가"로 돌아가서 다른 방법을 찾는 게 더 빨랐다.

 

규칙은 짧아야 실제로 지켜진다. CLAUDE.md 섹션당 3~4줄이라는 제약을 스스로 부과하니, 이후 PR들에서 "계획 먼저 승인받기" 같은 워크플로우가 실제로 잘 작동이 됐다. 길게 쓴 규칙은 결국 다시 안 읽힌다는 걸 이번에 확인할 수 있었다.

 

permission.deny는 최후의 안전망이 아니라 판단을 아껴주는 장치다. force-push, rm -rf, .env 접근 같은 항목을 매번 사람이 판단하지 않고 하네스가 먼저 걸러주니, 실제 리뷰는 훨씬 더 본질적인 질문에만 집중할 수 있었다. (하지만 merge는 꼭 내가 직접! )

 

작은 스코프의 작업이 숨은 버그를 드러낸다. 체크박스 오동작도, CSS 특이성 버그도 모두 좁은 범위를 고치던 중 우연히 발견됐다. 화면 전체를 갈아엎는 큰 작업이었다면 이런 디테일은 그냥 묻혔을 가능성이 크다.

 


아쉬운 점과 다음 개선 방향

이번 시도 전체를 관통하는 비효율을 세 가지 축으로 정리했다. 셋 다 "가이드라인은 만들었지만 그 가이드라인이 못 막아준 지점"이라는 공통점이 있다.

A. 재작업 비용 — 사전 확인 없이 시작해서 되돌아간 지점들

CLAUDE.md 문서를 백엔드에 처음 만들 때, 이미 되돌려진 커밋 위에서 브랜치를 따는 바람에 diff가 하나도 없는 PR이 나와 처음부터 다시 작업해야 했다. 목표 태깅 UX를 검증할 때는 로컬 CORS 문제를 근본적으로 고치는 대신, 매번 그 작업 스코프 안에서 임시 목업으로 우회했다. 둘 다 작업을 시작하기 전에 5분만 확인했으면 피할 수 있었던 재작업이다.

 

다음 방향: 브랜치를 새로 만들 때는 기준 브랜치의 최신 지점인지부터 확인하는 걸 워크플로우 규칙에 한 줄 추가하고, CORS 문제는 이번처럼 우회하는 대신 개발 환경 설정 자체를 한 번 제대로 고치고 넘어간다.

B. 검증 비용 — 자동화되지 않아 매번 다시 지불한 비용

frontend 저장소엔 자동 테스트 프레임워크가 아예 없다. 정적 검증은 린트뿐이고, 기능 검증은 매번 개발 서버를 띄워 브라우저에서 손으로 눌러보는 방식에 의존했다. 화면 수가 늘어날수록 "이번 변경이 다른 화면을 깨뜨리지 않았는가"를 확인하는 시간이 계속 늘어나는 구조였고, 체크박스 오동작 버그도 회귀 테스트가 잡아준 게 아니라 우연히 발견한 것이었다.

 

1차 시도의 Zustand 무한 루프도 마찬가지였다 — 타입 체크·린트로 안 잡히는 런타임 문제라 브라우저 콘솔을 열어 재현할 때까지는 원인조차 알 수 없었다. 스택 전환 덕에 그 버그의 근본 원인은 사라졌지만, 새로 짠 드래그앤드롭처럼 같은 방식(손으로 화면을 눌러보는 것)으로만 검증된 기능이 이번에도 여전히 남아 있다는 점에서, 이 문제는 화면 개선 단계뿐 아니라 프로젝트 초반부터 반복돼 온 셈이다.

 

다음 방향: 전체 테스트 도입까지는 아니어도, 반복적으로 깨졌던 지점(체크박스 클릭 영역, 헤더 겹침류)만이라도 최소한 테스트로 고정해두면 매번 손으로 처음부터 재확인하는 비용을 줄일 수 있다. 프론트-백엔드 간 색상 슬롯 개수처럼 두 시스템이 같은 숫자를 가정해야 하는 지점, 그리고 tokens.css-Quasar 테마처럼 같은 값이 두 곳에 따로 존재하는 지점은 테스트로 따로 고정해두는 것도 검토할 만하다.

C. 추적 비용 — 진행 상황이 문서화되지 않아 매번 회고성으로 파악

기획안의 화면 목록 대비 무엇이 끝났고 무엇이 남았는지가 살아있는 체크리스트로 관리되지 않았다. 빈 상태 화면처럼 작업했는지 여부조차 세션이 끝난 뒤 과거 기록을 뒤져서야 확인할 수 있는 항목이 있었다 — "지금 기획의 어느 부분까지 작업을 했는가"를 물을 때마다 매번 조사 비용을 새로 지불하는 구조였다.

 

1차 시도에서 문서엔 있지만 실제로는 구현되지 않았던 설정 페이지가 정확히 이 유형의 사례였다 — 화면 목록이 실시간 확인할 수 있는 문서 구조였다면 "문서화됨 vs 구현됨"의 간극이 그 자리에서 바로 드러났을 것이다.

 

다음 방향: 화면 목록을 체크박스 형태의 살아있는 문서로 관리하고, 작업을 마무리할 때마다 해당 화면 항목을 체크하는 습관을 워크플로우 규칙에 추가한다.


참고

 

GitHub - jung-jinyoung/plango at frontend

목표를 세우는 순간부터 실행과 회고까지,
AI와 함께 성장의 흐름을 이어가는 웹 기반 개인 일정 플래너 - jung-jinyoung/plango

github.com

 

Plango 프로젝트의 프런트엔드 소스 코드입니다. 작성 시점 기준 저장소는 Public으로 공개되어 있습니다. (2026.07.12)