에이전트가 디자인 시스템 컴포넌트를 “제대로” 쓰게 만드는 방법

AI 에이전트가 Figma MCP로 디자인을 분석하고 코드를 생성할 때 단순한 컴포넌트는 잘 쓰지만, 조합이 필요하거나 사용 방법이 복잡한 컴포넌트는 엉뚱한 코드를 생성하거나 디자인 시스템을 사용하지 않고 직접 구현해버리는 문제가 반복된다. 여기어때 파트너웹개발팀이 사내 디자인 시스템을 새로 설계하며 에이전트 친화적 구조를 목표로 Code Connect와 Agent Docs 두 가지 정보 레이어를 도입한 과정을 공유한다.

핵심 포인트

문제 원인: 에이전트에게 제공되는 정보가 부족 — 컴포넌트의 올바른 선택·조합 방법을 알 수 없어 확률적으로 잘못된 코드 생성
Code Connect(Figma 기능): Figma 속성과 코드 props의 매핑을 개발자가 명시적으로 정의 → 에이전트가 MCP로 디자인 분석 시 매핑 정보 자동 전달 (예: `Size=Large` → `size="lg"`)
Agent Docs(`agent/*.md` + `README.md`): Code Connect로 전달하기 어려운 컴포넌트 조합 패턴·공통 규칙·상황별 예제를 마크다운 문서로 별도 제공
단순 컴포넌트(BoxButton 등)는 Code Connect만으로 충분, 복잡한 다중 컴포넌트 조합(DatePicker 등)은 Agent Docs 필요
Code Connect 한계: 단일 컴포넌트의 prop 매핑은 가능하지만 여러 컴포넌트를 함께 조합하는 맥락과 규칙은 전달 불가
핵심 원칙: 에이전트가 일관적으로 올바른 결과를 내려면 "어떤 정보를 어떤 형태로 제공하는가"가 관건

상세 정리

배경: Figma MCP로 에이전트에게 디자인 전달 → 화면 코드 생성 워크플로 도입, 단순 컴포넌트는 잘 동작하나 복잡한 경우 불일관성 발생
문제: 복잡한 컴포넌트나 조합이 필요한 경우 엉뚱한 구현, 디자인 시스템 미사용, 에이전틱 코딩의 확률적 특성으로 결과 불일관성
해결책: 두 개의 정보 레이어 — Code Connect(Figma 속성↔코드 props 매핑) + Agent Docs(사용법·조합 패턴)
Code Connect 역할: Figma 속성명(`Size=Large`)과 코드 prop(`size="lg"`)의 대응 관계를 개발자가 `figma.connect()` 로 직접 정의
Code Connect 작동: 에이전트가 Figma MCP로 디자인 분석 시 매핑 정보가 자동 포함 → 정확한 prop 값 변환 가능
Code Connect 한계 실험: DatePicker처럼 여러 컴포넌트 조합이 필요한 경우 Code Connect만으로는 올바른 조합 맥락 전달 불가 확인
Agent Docs 역할: `agent/*.md` + `README.md` 형식으로 컴포넌트 조합 패턴·공통 규칙·상황별 예제를 마크다운으로 제공
설계 목표: 에이전트가 참고하는 정보(Code Connect)와 에이전트를 위해 추가 제공하는 정보(Agent Docs)를 명확히 구분
실용적 판단: 단순 컴포넌트 → Code Connect, 복잡한 조합 컴포넌트 → Agent Docs 추가 작성으로 이중 보완

왜 읽나AI 에이전트가 디자인 시스템을 올바르고 일관되게 사용하도록 만들기 위한 실전 접근법을 코드 예제와 실험 결과와 함께 공개한다. Figma Code Connect 매핑 정의 방식과 Agent Docs 문서화 전략을 통해 에이전트 친화적 컴포넌트 라이브러리를 설계하는 방법을 확인할 수 있다.

여기어때 (GC컴퍼니) 블로그

원문은 여기서 이어서 읽을 수 있어요

원문 읽기

읽음 (0)

·takedown 요청

에이전트가 디자인 시스템 컴포넌트를 “제대로” 쓰게 만드는 방법

이 글과 비슷한

토스는 어떻게 광고 속에 게임을 넣었을까

RxJS로 우아하게 사이드 이펙트 통제하기

항공 프론트엔드 구축기 (7/10): 창구를 하나만 두었습니다