디자인 시스템을 아는 화면 생성 에이전트 설계하기

문제: "그럴듯한 화면" ≠ "우리 제품다운 화면"

v0·Lovable·Bolt 같은 바이브 코딩 도구는 빠르지만, 사내 디자인 시스템을 쓰는 팀에는 세 가지가 막힌다.

한계	왜 문제인가
자체 컴포넌트를 모른다	shadcn/Tailwind 같은 범용 UI가 나와서 실제 앱에 그대로 못 넣는다
패키지 맥락(아이콘·토큰)을 주입할 수 없다	hex 하드코딩, 엉뚱한 아이콘이 섞인다
결과물이 일회성이다	디자인 시스템이 바뀌어도 이미 만든 화면엔 반영되지 않는다

Figma AI 계열은 결과가 디자인 파일이라 결국 개발자가 다시 코드로 옮겨야 한다. 그래서 질문을 "AI가 화면을 그리게 할 것인가"에서 "디자인 시스템이 요구하는 수십 가지 결정(컴포넌트 선택, 토큰, 레이아웃, 카피 톤, 상태 처리) 중 무엇을 AI에게 맡길 것인가"로 바꾼다. 화면 생성 도구가 아니라 의사결정 자동화 도구로 정의하는 것이다.

왜 로컬 에이전트 루프인가

이런 도구는 흔히 세 단계를 거쳐 모양이 잡힌다. 각 단계의 벽이 다음 설계의 근거다.

형태	해결하는 것	남는 벽
웹 어드민	설치 없이 프롬프트→프리뷰→배포→모바일 확인(QR)	모든 팀에 같은 에이전트. 도메인별 규칙·로컬 코드를 주입할 수 없다
로컬 CLI (`npx` 한 줄로 에디터+에이전트 구동)	로컬 프로젝트 폴더·팀 컨벤션·기존 코드를 컨텍스트로 읽는다	프롬프트 품질에 결과가 좌우되고, 같은 프롬프트에도 결과가 들쑥날쑥하고, 세션이 바뀌면 교정 내용이 사라진다
에이전트 루프	생성 앞뒤에 구체화·검증·기억 단계를 더한다	여러 화면의 흐름, 팀 단위 결정 공유

CLI 단계의 세 문제는 원인이 같다. "생성" 앞뒤로 아무것도 없다. 구체화·검증·학습 단계 없이 "프롬프트 → 코드"로 한 번에 점프한다.

생성 앞뒤를 감싸는 6단계 루프

flowchart LR
  c["Clarify<br/>역질문"] --> mr["Memory Read<br/>과거 결정"] --> cs["Cases<br/>유사 레퍼런스"] --> g["Generate<br/>코드 생성"] --> v["Verify<br/>자동 채점"] --> mw["Memory Write<br/>결정 축적"]

단계	해결하는 문제
Clarify	모호한 프롬프트 → 에이전트가 먼저 되묻는다 ("에러 상태는 어떻게 보여줄까요?", "별점은 탭? 슬라이드?"). 사용자가 프롬프트를 잘 쓰는 대신 에이전트가 빠진 결정을 채운다
Memory Read / Write	세션마다 같은 교정을 반복하는 문제
Cases	백지에서 시작하지 않고 검증된 패턴을 참고
Verify	결과 품질 편차: 사람이 보기 전에 기계가 먼저 거른다

멀티 에이전트 대신 "하네스 + 외부 위임"

설계·코딩·지휘 에이전트를 따로 두고 협업시키는 구조는 통신 오버헤드가 크고, 에이전트 사이에서 의도의 뉘앙스가 손실된다. 대신 이렇게 나눈다.

설계·의사결정은 직접 통제하는 하네스 하나에 모은다
코드 작성처럼 이미 강력한 도구가 있는 일은 Claude Code에 위임한다. Claude Agent SDK의 query()로 로컬 claude를 띄워 실행하는 어댑터 도구(runCodingAgent)를 쓴다

위임할 때는 도구를 화이트리스트로 제한한다: Read/Edit/Write/Bash/Glob/Grep + 디자인 시스템 문서 MCP. 결과(파일 변경, 도구 호출 이벤트, 세션 ID)는 하네스로 다시 흘려보낸다.

// 개념 예시: 코딩은 Claude Code에 맡기고, 설계 맥락은 하네스가 쥔다
async function runCodingAgent(spec: DesignSpec) {
  for await (const event of query({
    prompt: renderImplementationPrompt(spec), // 스펙을 구현 지시로 변환
    options: {
      allowedTools: ["Read", "Edit", "Write", "Bash", "Glob", "Grep", "mcp__design-docs"],
    },
  })) {
    forwardToHarness(event); // 파일 변경·도구 호출을 상위 루프로 전달
  }
}

두 가지 모드: 합의용 / 실행용

모드	하는 일	핵심 장치
검토(Plan)	의도 구체화 → 스펙 저장 → `ask_user`로 승인 요청 후 멈춤	코딩 도구를 도구 목록에서 아예 빼서 코드를 만들 수 없게 함
실행(Orchestra, 기본값)	구체화 → 스펙 → 검증 → 코드 → 스펙 갱신을 한 번에	승인 후 넘어오면 앞단(Clarify·Cases)은 건너뛰고 검증부터

"이 모드에선 코드를 쓰지 마"라고 프롬프트로 부탁하는 대신 도구 자체를 제거하는 것이 확실한 가드레일이다. Claude Code의 Plan Mode와 같은 발상이다.

의도 라우팅

들어온 메시지는 파일 읽기·탐색(바로 코딩 에이전트로), 화면 설계·수정(스펙 검증 후 코딩 에이전트), 디자인 시스템 질문(직접 답변), 모호한 요청으로 나눈다. 모호한 요청은 추측하지도 거절하지도 말고 ask_user로 선택지를 제시한다.

프롬프트와 코드 사이에 중간 표현(스펙) 두기

대부분의 도구는 프롬프트를 바로 코드로 바꾼다. 대신 설계 의도를 담은 JSON 스펙을 사이에 둔다.

{
  "screenType": "form",
  "domain": "중고거래",
  "tree": ["AppBar", "Content: [상대 정보, 별점 입력, 후기 입력]", "BottomCTA"],
  "components": [{ "name": "ActionButton", "props": { "variant": "brandSolid" } }],
  "tokens": { "color": ["bg.layerDefault"], "spacing": ["x4"] },
  "decisions": [
    { "topic": "별점 UI", "decision": "별 아이콘 탭", "rationale": "모바일 오탭이 적음" }
  ]
}

이점	설명
추적성	"왜 이 컴포넌트인가"가 `decisions`에 남는다: 코드만 봐선 알 수 없는 맥락
정밀한 수정	코드를 직접 고치지 않고 스펙을 고친 뒤 재생성. 근거(`rationale`)도 함께 갱신
시맨틱 토큰 강제	스펙에 `#FF6F0F` 대신 토큰 이름만 허용 → 브랜드 일관성이 구조적으로 보장
역공학	기존 코드 → 스펙 역생성(`reverseDesignFromCode`)으로 레거시 화면도 같은 루프에 태움

스펙은 저장 직후 규칙 검증 도구로 확인하고, 오류가 있으면 최대 2회 자가 수정 후 재검증한다. 코드 생성이 끝나면 스펙을 다시 저장해 코드와 동기화한다.

지식은 시스템 프롬프트가 아니라 온디맨드 스킬로

규칙을 시스템 프롬프트에 전부 넣으면 토큰이 낭비되고, 지금 맥락과 무관한 규칙이 노이즈가 된다. 그래서 디자인 지식을 마크다운 스킬 모듈로 쪼개 필요한 시점에만 로드한다.

스킬	담는 규칙(예)
spacing / radius / typography constraint	"카드 내부 패딩은 x4 이상", "한 화면의 타이포 단계는 4개 이내"
screen-patterns / writing-guide	폼 화면의 에러 표시 패턴, "CTA는 동사로 시작, 12자 이내"
self-check	코드 작성 후 셀프 점검 체크리스트

폼 화면을 설계할 땐 레이아웃·간격 스킬만, 카피를 정할 때 비로소 카피 스킬을 로드한다. 규칙이 바뀌면 스킬 파일만 고치면 된다. 스킬을 팀에 배포하는 방법은 Claude 스킬 만들기 가이드에 있다.

검증을 채점기(Eval)로 자동화하기

두 번째 결과가 첫 번째와 딴판이면 도구에 대한 신뢰가 깨진다. 생성 결과를 채점기로 점수화하고, 점수가 낮으면 어디가 문제인지 피드백을 받아 에이전트가 스스로 고친다.

채점 방식	검사 대상(예)
결정론적 검사 (정적 분석)	색상 토큰 사용(hex 하드코딩 금지), 타이포 단계, 레이아웃 컴포넌트 패턴, spacing 토큰, props 정합성, 아이콘·애니메이션 규칙
LLM 판정 (정성 평가)	UX 패턴 적합성, 인터랙션 흐름, 화면 간 플로우, 폼 상태 처리(에러·로딩·빈 상태)

셀 수 있는 건 코드로, 판단이 필요한 건 LLM으로 검사한다. 결정론적 검사를 먼저 두면 빠르고 싸다.

세션을 넘는 메모리: 결정 → 원칙 승격

"중고거래에선 CTA를 항상 brandSolid로" 같은 교정을 매 세션 반복하지 않도록 메모리를 두 층으로 나눈다. 한 번의 교정은 로그로만, 반복된 패턴만 규칙이 된다.

flowchart TB
  gen["생성마다 스펙의 decisions"] --> log["decision-log.jsonl (로그, raw)"]
  log -->|"같은 패턴이 임계치 이상 반복"| pr["principles.json (도메인별 원칙, curated)"]
  pr -->|"새 세션의 Memory Read 단계에서 자동 주입"| mr["Memory Read"]

정리: 내 작업에 적용할 체크리스트

문제는 픽셀이 아니라 결정이다. 디자인 시스템의 암묵적 규칙은 사용자가 프롬프트에 쓰지 않으므로 에이전트가 알고 있어야 하고, 아래 장치들은 화면 생성뿐 아니라 모든 에이전틱 코딩 작업에 옮겨 쓸 수 있다.

"한 번에 잘 만들어 줘" 대신 구체화 → 기억 → 참고 → 생성 → 검증 → 축적 루프가 있는가?
프롬프트 → 코드 사이에 스펙·계획 단계가 있는가? (Plan Mode, 설계 문서)
모호하면 추측 대신 되묻게 지시했는가?
"하지 마"를 프롬프트가 아니라 도구 권한으로 막았는가?
팀 규칙이 거대한 CLAUDE.md 하나가 아니라 필요할 때 로드되는 스킬로 쪼개져 있는가?
결과를 lint·타입 체크·커스텀 검사 스크립트로 자동 검증하고, 실패 시 재시도 루프가 있는가?
반복되는 교정을 메모리·규칙 파일로 승격하고 있는가?
이미 잘 만든 에이전트(Claude Code 등)가 있는 영역은 직접 만들지 말고 위임했는가?

버그 제보