Claude Code는 코드를 잘 작성하지만,

디자인 방향이 결정되면, 저는 이를 DESIGN.md에 기록합니다.

DESIGN.md는 Google Stitch에서 오픈 소스로 공개한 형식을 따르며, Claude Code, Cursor, Copilot 및 기타 에이전트(Agents)들이 읽을 수 있습니다. 구조는 두 개의 레이어로 구성됩니다:

---
colors:
  primary: "#2563eb"
...

YAML 프론트매터(frontmatter)는 기계가 읽을 수 있는 토큰(color, font, spacing)을 보유합니다. 마크다운(Markdown) 본문은 각 값의 근거, 즉

처음부터 다크 모드 (dark mode)를 구축할지, 아니면 나중에 처리할지를 시작 단계에서 결정해야 합니다. 사후에 다크 모드를 요청하는 것은 하드코딩된 모든 라이트 모드 (light-mode) 값을 다시 작성해야 함을 의미합니다.

Tailwind의 dark: 클래스를 사용하여 다크 모드 지원을 추가해줘.
DESIGN.md의 CSS 변수에는 이미 라이트 모드와 다크 모드 정의가 모두 포함되어 있어. 그것들을 참조해.

피드백 루프 (Feedback loop)

컴포넌트가 작동하기 시작하면, 코드를 일일이 읽기보다는 스크린샷을 기반으로 피드백을 줍니다. 공식 베스트 프랙티스 (best practices) 가이드에서도 이 패턴을 다루고 있습니다. 즉, 스크린샷을 목표 디자인과 비교하고 그 지점부터 반복(iterate)하는 방식입니다.

저는 /run을 사용하여 서버를 시작한 다음, 피드백을 주기 전에 스크린샷 도구(frontend-design 스킬 또는 Playwright MCP)를 사용하여 화면을 캡처합니다.

현재 홈 화면의 스크린샷을 찍어줘.
헤더가 너무 높아. h-16으로 설정해줘.
네비게이션 폰트 크기를 text-sm으로 줄여줘.

한 번의 지시 사항에 너무 많은 변경 사항을 담으면 무엇이 바뀌었는지 확인하기 어렵습니다. 저는 한 라운드당 시각적으로 확인할 수 있는 변경 사항을 두세 개 정도로 유지하는 것을 목표로 합니다.

반응형 (Responsive) 체크도 동일한 흐름을 따릅니다.

모바일 너비(375px)에서 스크린샷을 찍어줘.
카드들이 아마 여전히 나란히 표시되고 있을 거야.
모바일에서는 수직으로 쌓이도록(stack vertically) 수정해줘.

회귀(Regressions)가 발생할 때

충분한 반복이 이루어지면, "하나를 고쳤더니 다른 것이 망가졌다"는 상황이 발생합니다. Claude Code에게 이전 스크린샷과 현재 상태를 비교하도록 요청하면 원인을 좁히는 데 도움이 됩니다.

이전 스크린샷과 현재 화면을 비교해줘.
의도치 않게 발생한 변경 사항을 나열해줘. 아직 수정은 하지 마.

수정을 적용하기 전에 원인을 이해하면 동일한 패치 사이클을 반복하는 것을 방지할 수 있습니다.

계속해서 문제가 되었던 부분들

드리프트(drift) 문제가 저를 가장 괴롭혔습니다. "헤더 폰트를 바꿔줘"라고 하면 레이아웃 전체가 재구성되어 돌아오곤 했습니다. 이제 저는 범위가 지정된(scoped) 변경 사항에 명시적인 경계를 추가합니다.

Header 컴포넌트의 폰트 크기만 변경해줘.
레이아웃이나 색상은 건드리지 마.

또한 한 번에 모든 컴포넌트를 생성하려고 몇 번 시도해 보았습니다. 코드가 빠르게 대량으로 생성되었지만, 그 기초 위에 모든 것이 이미 구축된 후에야 항상 구조적인 문제를 발견하게 되었습니다. 컴포넌트를 하나씩 만들고, 확인한 다음, 다음으로 넘어가는 방식이 체감상으로는 더 느리게 느껴졌음에도 불구하고 결과적으로는 전체 과정이 더 빨랐습니다.

모호한 피드백 또한 진행을 지체시키는 또 다른 요인입니다. "전체적인 균형이 맞지 않아"라는 말은 Claude Code가 실행할 수 있는 프롬프트가 아닙니다. 스크린샷을 찍고 구체적인 사항을 명시하는 것 — "오른쪽 열에 비해 왼쪽 열이 너무 넓어", "카드 간의 폰트 크기가 일관되지 않아 보여" — 가 실행 가능한 결과를 만들어냅니다.

전체 시퀀스는 다음과 같습니다:

1. Markdown 형식으로 명세(spec)를 가져옵니다.
2. 텍text 형식으로 컴포넌트 구조를 가져옵니다.
3. 디자인 시스템(tailwind.config / globals.css)을 구축합니다.
...

1단계부터 3단계를 건너뛰고 바로 구현(implementation) 단계로 뛰어드는 것은 일관되게 나중에 더 많은 재작업(rework)을 초래했습니다. 적어도 제 경험상, 코드를 작성하기 전에 구조를 제대로 잡는 것이 수정 횟수를 줄여주었습니다.