코드보다 앞서야 할 것

ghflare는 GitHub Trending repo의 이슈 활동에서 이상 징후를 감지하는 도구다. 이슈 수 절대값이 아니라 평소 대비 얼마나 비정상적인지를 본다. 오늘 유독 시끄러운 repo가 어디인지 알고 싶은 사람을 위한 서비스다. (ghflare.vercel.app)

코드가 어려웠던 게 아니었다. 뭘 만들지, 화면이 어떻게 생겨야 하는지 — 그 전 단계들이 전부 어려웠다.

방향을 좁히는 방법

처음에 두 방향을 생각했다. 코드리뷰 플랫폼, 아니면 이슈 시각화. 둘 다 금방 걸렸다. 코드리뷰 플랫폼은 “GitHub이 이미 있는데 왜”라는 질문에 막혔고, 단순 시각화는 난이도가 낮다는 느낌이 들었다.

전환점은 내가 평소에 하던 행동을 설명하다가 왔다. “오늘 좀 이상하네 싶어서 이슈탭 들어가보면 유독 활발한 목록이 있다.” 이걸 말했을 때 방향이 잡혔다.

큐레이션 문제는 GitHub Trending으로 해결했다. GitHub이 “스타 많이 받은 repo”를 보여주면, 나는 “이슈에서 뭔가 일어나고 있는 repo”를 보여준다. 같은 데이터 소스, 다른 신호. 직접 큐레이션 없이 매일 새 데이터가 들어온다.

Claude가 코드부터 바꾸려 할 때 멈춰 세웠다

기능 구현이 끝나고 화면을 보니 flare한 디자인도 아니고 incident하지도 않고 대시보드같지도 않았다. 그때 Claude가 바로 RepoCard 컴포넌트 디자인을 바꾸려고 했다. 즉시 멈춰세웠다.

이게 LLM과 UI 작업할 때의 패턴이다. “디자인이 별로다”는 말에 방향을 물어보지 않고 자기 해석으로 코드를 바꾼다. 뭔가 바뀌긴 하는데 원하는 방향인지 알 수 없다.

그 후에도 세 번의 시도가 다 실패했다.

좌측 4px 보더 + tint 배경 — llm이 전형적으로 뽑아내는 디자인 패턴이다.
수평 바 차트 — 히스토리 데이터가 없어서 전부 100% 폭. 의미 없는 시각화.
SVG 스파크라인 — 데이터가 1개뿐이라 블록처럼 보였다.

잘못은 내가 한 거였다

세 번 실패하고 나서 인정했다. 디자인을 만들어두고 줬어야 했는데.

Claude는 확정된 시각 설계가 없으면 추측한다. 세 번의 실패 모두 “디자인이 별로다”는 말에 대한 Claude의 추측이었다. 내가 레퍼런스를 줬어도 그걸 해석하는 건 Claude였고, 해석이 틀렸다.

코드가 나오는 도구가 아니라 시각 설계 결과물이 필요했다. Figma Make를 선택했다.

디자인 스크린샷을 받고 나서 작업이 달라졌다. 추측이 없어졌다. 확정된 레이아웃을 구현하는 작업이 됐다.

기술 설계 문서는 7개나 썼다. 데이터 파이프라인, API 스펙, DB 스키마, 분석 알고리즘. “화면이 어떻게 생겨야 하는가”는 없었다. LLM과 UI 작업할 때 시각 설계가 먼저여야 한다는 걸 이번에 몸으로 배웠다.