에이전트 스킬(agent skills), 린트 규칙(lint rules), Vercel Agent 코드 리뷰, 평가(evals), 사람 주도의 업데이트 루프를 활용해 Vercel이 에이전트에게 자사의 제품 설계 원칙을 학습시키는 방식을 소개합니다.
코딩 에이전트는 동작하는 UI를 빠르게 만들어낼 수 있습니다. 하지만 진짜 어려운 부분은 따로 있습니다. 에이전트는 제품의 스타일을 그대로 따라 하고, 패턴을 맞추고, 기존 관례를 지키려고 노력합니다. 그러나 그 패턴들이 왜 존재하는지는 이해하지 못합니다. 코드는 에이전트에게 무엇이 배포됐는지는 알려주지만, 특정 컴포넌트나 문구, 인터랙션이 어떻게 표준이 됐는지는 알려주지 않습니다. 그 맥락은 디자인 리뷰, PR 코멘트, Slack 스레드, 그리고 그 자리에 있었던 사람들의 머릿속에 담겨 있습니다. 에이전트에게는 코드베이스에 없는 맥락이란 존재하지 않는 것과 마찬가지입니다.
Vercel은 에이전트 중심으로 움직이는 팀입니다. 저희는 제품 결정 사항을 코드처럼 다룹니다. 저장소에 보관하고, 변경사항을 검토하며, 해당 저장소에서 작업하는 모든 에이전트가 참조할 수 있도록 합니다.
이를 구현하는 방법이 바로 product-design입니다. 이 시스템은 세 가지 요소로 구성됩니다.
제품이나 코드베이스에 대한 판단이 필요한 결정의 배경을 코딩 에이전트에게 제공하는 에이전트 스킬
명확한 규칙을 자동으로 강제하는 린트 규칙
Slack, Figma, GitHub에서 근거를 수집해 가이드라인 업데이트 안을 검토용으로 준비하는 리뷰 루프
어떤 팀이든 자신들의 기준에 맞게 같은 구조를 구축할 수 있습니다.
이 스킬은 관할하는 코드와 함께 저장소 안에 위치합니다. 구조를 단순화하면 다음과 같습니다.
저장소의 AGENTS.md는 코딩 에이전트에게 스킬을 언제 로드할지 알려줍니다. 스킬 내부의 AGENTS.md는 로드 순서, 유효성 검증, 거버넌스를 정의합니다. SKILL.md는 런타임 워크플로우를 담당합니다.
references/에는 제품 판단 기준, 인터페이스 품질, 복원력, 카피, 공식 제품 명칭, 인터랙션 패턴, 그리고 화면별 결정 사항이 담겨 있습니다.
exemplars/에는 배포된 풀 리퀘스트에서 참고할 만한 결정과 피해야 할 실수들이 기록됩니다. coverage-gaps.md에는 아직 표준이 정해지지 않은 영역이 나열됩니다.
copywriting-eval/는 카피와 인터페이스 언어 동작을 테스트합니다. 전반적인 제품 설계 워크플로우를 평가하지는 않습니다.
SKILL.md는 먼저 요청 모드를 파악합니다. shape, implement, review, copy, harden 중 하나로 분류해, 감사(audit)가 편집으로 번지거나 카피 검토가 전면 재설계로 확장되는 것을 막습니다. 백엔드 전용 작업, 텔레메트리, 콘솔 에러, 자동 생성 파일, 그리고 UI에 영향을 주지 않는 테스트는 건너뜁니다.
스킬은 내용을 중복 저장하는 대신 원본 출처로 라우팅합니다. 컴포넌트 API, 디자인 시스템 규칙, 접근성 기준, 인터랙션 가이드는 각각의 담당 영역에서 관리됩니다.
라우팅은 작업 유형과 화면(surface) 모두에 따라 구체적으로 분기됩니다. 실질적인 변경 사항에는 제품 판단 기준과 인터페이스 품질이 가장 먼저 로드됩니다. 카피, 컴포넌트, 레이아웃, 인터랙션, 접근성, 복원력 작업은 각각 관련 참조 자료로 라우팅됩니다. 모달에는 파괴적 동작 패턴과 공식 동사가 로드되고, 설정 폼에는 레이블, 유효성 검증, 점진적 공개(progressive disclosure), 접근성 이름 가이드가 로드됩니다.
아래의 단순화된 구조를 출발점으로 삼아, 경로와 기준을 팀 상황에 맞게 교체해 사용할 수 있습니다.
라우팅은 스킬을 유용하게 만드는 요소 중 하나일 뿐입니다. 나머지 하나는 스킬이 결과물을 생성한 이후, 발견 사항을 추적 가능한 상태로 유지하는 방식입니다.
카피 규칙에는 고정 ID가 부여되며, 해당 원본 출처로 연결됩니다.
Vercel Agent가 패치를 제안할 때, 제안을 올리기 전에 저장소의 빌드, 테스트, 린터가 갖춰진 Vercel 샌드박스 환경에서 변경 사항을 먼저 검증합니다.
린터로 규칙을 안정적으로 강제할 수 있다면, 저희는 결정론적 검사를 선호합니다. 린터는 실행 비용이 낮고 속도가 빠르기 때문에, 개발자와 코딩 에이전트 모두 나중에 리뷰를 기다리지 않고 작업 중에 바로 피드백을 받을 수 있습니다.
선택지가 두세 개의 정적 옵션이라면 코드로 판단할 수 있으므로 린터가 라디오 버튼을 권장할 수 있습니다. 반면 파괴적 동작에 적합한 대상과 결과를 명확히 지정하려면 제품 맥락이 필요하기 때문에 스킬이 처리합니다.
코드베이스에 적용된 린트 규칙의 예시는 다음과 같습니다.
포커스 관리, 키보드 내비게이션, 레이어 구조를 망가뜨리는 중첩 모달 방지
두세 개의 정적 옵션에서는 선택지가 항상 눈에 보이도록 셀렉트 대신 라디오 버튼 권장
아이콘 버튼과 폼 컨트롤에 접근성 이름 필수 지정, 공유 포커스 토큰을 우회하는 커스텀 포커스 링 금지
레이아웃 클래스는 허용하되, className가 디자인 시스템 컴포넌트의 색상, 테두리 반경, 그림자를 덮어쓰는 것 방지
긴 콘텐츠가 올바르게 스크롤되고 헤더와 푸터가 고정 상태를 유지하도록 Modal.Body 필수 적용
날것의 그림자를 테마 인식 Material 클래스로 교체하고, Material에 내장된 테두리 처리를 중복 적용하는 border 금지
4px 그리드를 벗어나는 임의 간격에 플래그를 달고, 해당하는 표준 유틸리티가 있으면 제안
각 규칙에는 해당 패턴이 문제인 이유와 구체적인 수정 방법이 명시됩니다. 일부 규칙은 안전한 마이그레이션, 예를 들어 deprecated된 Tailwind 유틸리티 이름 교체 같은 경우는 자동으로 수정합니다.
승인된 결정 사항은 다양한 형태를 가집니다.
Checkbox 모범 사례처럼 관련 Geist 컴포넌트 옆에 위치한 사람이 읽기 쉬운 가이드
product-design 스킬 내의 에이전트 가이드
코드로 안정적으로 검사할 수 있는 경우의 린트 규칙
아래의 린트 규칙은 하나의 제품 가이드라인이 어떻게 결정론적 검사로 구현되는지를 보여줍니다.
이러한 규칙들은 각각의 유형에 속하는 실수를 자동으로 잡아내므로, 코드 리뷰는 실제로 판단이 필요한 결정에만 집중할 수 있습니다.
린트 규칙은 결정론적이지만 에이전트의 동작은 달라질 수 있으므로, 스킬이 한 번도 본 적 없는 인터페이스를 대상으로 테스트합니다.
에이전트가 이전 상태를 편집하면, 판정 모델(judge)이 루브릭에 따라 결과를 검토합니다.
평가는 스킬에 기록된 배포 사례에서 가져옵니다. 홀드아웃(holdout) 사례는 예상 편집 내용을 숨겨, 가이드가 얼마나 잘 일반화되는지를 테스트합니다. 스킬 없이도 픽스처를 실행해 스킬이 에이전트 동작에 실제로 영향을 미쳤는지 측정합니다.
규칙 준수 여부는 배포된 결과물과의 유사성과 별도로 채점합니다. 배포된 코드에 결함이 있다면, 에이전트는 이를 그대로 재현하는 대신 개선해야 하기 때문입니다.
제품 표준은 컴포넌트, 명칭, 워크플로우, 실패 상태가 변하면서 함께 달라지며, 모든 업데이트에는 근거와 사람의 검토가 필요합니다.
저희의 주간 근거 수집 워크플로우는 product-design을 개선할 수 있는 디자인 피드백을 모읍니다. Slack 대화를 검색하고, Figma 파일, 풀 리퀘스트, 리뷰 코멘트, 프리뷰 링크를 근거로 보존합니다. 근거가 불충분할 때는 검증에 필요한 코드나 커밋을 기록해 둡니다.
이 워크플로우는 수집과 판단을 명확히 분리합니다.
수집 담당은 규칙 제안 없이 메시지, 링크, 주변 맥락만 모읍니다.
별도의 판정 담당이 근거를 그룹화하고, 출처를 검증하며, 미해결 질문을 기록합니다.
작업이 완료되면 후보 항목, 기각된 주제, 후속 요청, 커버리지 공백이 담긴 리뷰 패킷이 생성됩니다.
모든 후보 항목은 출처에 연결되며 보류 상태로 유지됩니다. 경험 많은 검토자의 코멘트가 우선순위를 높일 수는 있지만, 모든 후보 항목은 여전히 근거가 필요합니다.
자동화는 리뷰 패킷 생성에서 끝납니다. 후보 항목을 에이전트 가이드, 린트 규칙, 예시, 평가, 또는 변경 없음 중 어느 것으로 처리할지는 사람이 결정합니다. 승인된 변경 사항은 가장 좁은 범위의 관련 파일에 반영하고, 병합 전에 관련 검사를 통과해야 합니다.
저희의 설정은 Vercel의 제품, 컴포넌트, 리뷰 이력을 반영하고 있지만, 다른 팀도 이 구조를 자신들의 기준에 맞게 응용할 수 있습니다.
같은 리뷰 코멘트가 반복되는 제품 화면 하나를 골라 시작하세요. 파괴적 동작, 에러 상태, 설정 폼, 빈 상태, 내비게이션 등이 좋은 출발점입니다. 배포된 코드와 실제 리뷰에서 사례를 수집하고, 결정 내용과 그 이유, 예외 사항, 출처를 기록하세요.
clear, polished, intuitive처럼 폭넓은 형용사로 시작하지 마세요. 에이전트에게는 관찰 가능한 결정이 필요합니다. Destructive actions use Verb + Noun는 활용할 수 있지만, Buttons should be clear는 그렇지 않습니다.
다른 화면으로 확장하기 전에, 현재 화면에 특화된 항목들을 먼저 채워 넣으세요.
저장소의 영구 지침에 스킬을 언제 로드할지 명시하고, 스킬이 다루는 파일과 화면, 그리고 반드시 건너뛰어야 할 영역을 정의하세요. 별도로 진행한 Next.js 평가에서 에이전트가 사용 가능한 스킬을 호출하지 않은 경우가 56%에 달했습니다. 트리거는 가이드와 별개로 테스트하세요. 스킬 로드 실패와 규칙 미준수는 서로 다른 문제이기 때문입니다.
에이전트에게 어떤 화면과 참조 자료를 로드했는지 보고하도록 요청하고, 발견 사항이 해당 출처를 인용하는지 확인하세요.
짧은 진입점을 두어 화면을 파악하고 관련 참조 자료를 로드하세요. 세부 내용은 검토자들이 이미 논의하는 영역 중심으로 구성하세요. 폼, 모달, 내비게이션, 제품 어휘, 워크플로우 상태, 화면 간 공통 패턴 등이 해당됩니다.
규칙에는 고정 ID를 부여하고 예시와 출처에 연결하세요. 배포 사례는 유용한 결정과 알려진 결함을 모두 포함해 기록하고, 가이드가 없는 영역은 커버리지 공백 목록에 명시적으로 남겨두세요.
커버리지 공백 목록은 가이드가 없는 영역을 명시적으로 드러냅니다.
린터가 문제를 안정적으로 감지할 수 있다면, 그 규칙은 린터에 맡기세요. 제품이나 코드베이스 맥락이 필요한 결정에는 에이전트 가이드를 활용하세요. 새로운 표준, 정책 결정, 해결되지 않은 제품 관련 결정은 사람이 관장하도록 하세요.
기록된 사례로 훈련 픽스처를 구성하고, 스킬에 등장하지 않는 인터페이스의 예상 편집 내용으로 홀드아웃을 만드세요. 검색과 적용은 별도로 테스트하세요. 에이전트가 스킬을 로드했는지와 규칙을 따랐는지는 별개의 질문이기 때문입니다.
예외가 너무 많아져 규칙의 신뢰성을 유지하기 어렵다면, 에이전트 가이드로 되돌리세요.
새로운 근거를 정기적으로 검토하되, 가이드나 검사 항목을 변경할 때는 반드시 사람의 승인을 거치세요. 무엇이 언제, 왜 바뀌었는지, 어떤 근거가 뒷받침됐는지를 기록하는 결정 로그를 유지하세요. 새 규칙은 제품 변경과 동일하게 취급해 각각 검토하고 테스트하며, 더 이상 도움이 되지 않는 규칙은 제거하세요.
화면 하나, 그리고 팀이 이미 반복하는 결정에서 시작하세요. 그 결정들을 코드를 작성하고 검토하는 곳에 두고, 무엇이 표준이 될지에 대한 책임은 사람이 지도록 하세요.
가장 어려운 부분은 첫 번째 화면을 고르는 것입니다. 어느 팀이든 코드로 담아낼 만한 결정이 있습니다. 문제는 그것이 누군가의 머릿속에만 있는지, 아니면 에이전트가 찾을 수 있는 곳에 있는지입니다. 이 패턴을 활용해 무언가를 만들었거나 설정 방식에 대해 궁금한 점이 있다면 알려주세요.
