에이전트에게 제품 디자인을 가르치는 방법 — Vercel의 접근

Vercel이 코딩 에이전트에게 제품 디자인 의사결정 맥락을 제공하는 product-design 스킬 시스템을 구축한 과정을 공개했다. 에이전트는 코드는 읽을 수 있지만 PR 댓글·설계 검토·Slack 토론에 담긴 결정 이유는 접근 불가 — 이 정보 격차를 스킬(컨텍스트 제공), 린터(규칙 자동 강제), 검토 루프(증거 수집)의 세 계층으로 해소한다. 에이전트가 사용 가능한 스킬을 호출하지 못한 비율이 56%였다는 내부 측정이 이 시스템 개발의 직접 계기가 됐다.

핵심 포인트

.agents/skills/product-design/ 아래 references/(판단 기준), exemplars/(PR 사례), copywriting-eval/(카피 테스트)로 나눠 에이전트가 파일로 설계 컨텍스트를 읽게 했다.
SKILL.md가 Shape(흐름 설계), Implement(빌드), Review(감시), Copy(카피 편집), Harden(엣지 케이스) 5가지 요청 모드를 정의해 에이전트 역할을 명확히 나눈다.
명확한 UI 규칙은 ESLint 린터로 코드화해 자동 강제한다 — "옵션 2~3개면 라디오 버튼", 중첩 모달 방지, 아이콘 버튼 접근성 이름 필수 등.
주간 증거 수집 루프: Slack·Figma·GitHub에서 raw 증거 수집 → 판사 에이전트가 검증·그룹화 → 인간 승인 후 가이드라인 병합.
의사결정 우선순위를 코드화: 사용자 명시 목표 → 검증된 증거 → 저장소 가이드 → 수용된 설계 결정 → 인접 패턴 → 일반 UI 휴리스틱 순.

상세 정리

문제: 에이전트가 과거 설계 결정의 이유를 알 수 없어 일관성 없는 UI를 생성하고, 왜 특정 패턴이 존재하는지 이해하지 못한다.
저장소 구조: .agents/skills/product-design/ 폴더에 references/(제품 판단·인터페이스 품질·복원력 기준), exemplars/(실제 PR 사례), copywriting-eval/(카피라이팅 테스트 케이스) 세 디렉터리로 분리.
요청 모드 설계: SKILL.md에서 모드별 진입점을 정의하고, 에이전트는 현재 작업에 맞는 모드를 선택해 해당 레퍼런스만 로드한다.
운영 원칙: "픽셀이 아닌 작업부터 시작", "증거 기반·취향 배제", "모든 도달 가능한 상태 설계", "코드 검사만으론 부족 — 실제 표면 검증", "단일 사용자 진입점 유지".
의사결정 계층: 사용자 명시 목표 우선, 그 다음 검증된 시스템 증거 → 저장소 가이드 → 수용된 결정 → 인접 패턴 → 일반 휴리스틱 순으로 에이전트가 판단.
린터 구현 예시: "옵션 2~3개 → 라디오 버튼" 규칙을 JavaScript ESLint 플러그인으로 구현. 동적 옵션 여부와 개수를 정적 분석으로 감지해 자동 경고.
린터 적용 가능 규칙: 중첩 모달 방지, 아이콘 버튼 접근성 이름 필수, 테마 기반 Material 클래스만 허용, 4px 그리드 준수 등 명확한 규칙을 코드 레벨에서 강제.
평가 프레임워크: "이전 상태 → 이후 상태" 픽스처로 에이전트 동작 검증. 배포 코드 기반 학습 픽스처와 일반화 측정용 holdout 세트를 분리 운영.
주간 파이프라인: 수집기가 Slack 메시지·Figma 링크·PR 댓글을 평가 없이 raw 수집 → 판사 에이전트가 검증·그룹화·미해결 질문 기록 → 검토 패킷(후보·거부 주제·커버리지 공백) 생성 → 인간 승인 후 병합.
구현 로드맵 5단계: 반복 결정 수집 → 명시적 로드 트리거 정의 → 라우팅·규칙·증거 분리 → 명확한 규칙은 린터로 코드화 → 소유권·업데이트 루프 할당.
핵심 수치: 에이전트가 사용 가능한 스킬을 호출하지 못한 경우 56% — 스킬 디스커버리와 트리거 명시성 개선이 남은 과제.