에이전트용 제품 설계 기준 관리 체계
코드 에이전트가 제품 결정을 이해하고 따르도록 product-design 체계를 도입하는 방법을 설명합니다.
교안에 영향
기존에 제품 설계를 코드나 리뷰 메모에만 두고 있던 안내 글은 product-design, AGENTS.md, SKILL.md, coverage-gap, eval, lint rule 중심 설명으로 바뀌어 그대로는 맞지 않을 수 있습니다.
요약
- coding agents가 제품 스타일과 관례는 따라도 그 배경이 되는 이유는 이해하지 못한다는 문제를 짚습니다. - Vercel은 제품 결정을 코드처럼 저장·검토·배포하는 product-design 체계를 사용한다고 설명합니다. - product-design은 agent skill, linters, review loop의 세 부분으로 구성되며, 각 결정의 출처와 규칙을 추적 가능하게 만듭니다. - lint rule, eval, evidence-intake workflow, coverage-gap 관리로 기준을 최신 상태로 유지하는 방법을 제시합니다.
바뀐 것
새 기능
- product-design을 agent skill, linters, review loop의 세 부분으로 구성한다고 소개합니다.
개선
- SKILL.md가 shape, implement, review, copy, harden 같은 request mode를 먼저 판별해 audit과 edit, copy pass가 섞이지 않도록 합니다.
- backend-only work, telemetry, console errors, generated files, tests without shipped UI impact는 skill에서 건너뛰도록 합니다.
- linter로 신뢰성 있게 확인할 수 있는 규칙은 deterministic check로 빠르게 피드백하도록 권장합니다.
기타
- coding agents는 제품 스타일과 관례를 따라갈 수 있지만, 그 이유까지는 이해하지 못한다는 문제를 설명합니다.
- Vercel이 accepted product decisions를 코드처럼 저장하고 검토하는 product-design 방식을 사용한다고 밝힙니다.
- repository의 AGENTS.md, skill-local AGENTS.md, SKILL.md가 각각 로드 순서, 검증, 런타임 워크플로를 담당한다고 설명합니다.
- references/에는 product-judgment, interface-quality, resilience, copy, canonical product names, interaction patterns, surface-specific decisions를 보관한다고 안내합니다.
- exemplars/에는 shipped pull requests에서 반복할 결정과 피해야 할 실수를 기록하고, coverage-gaps.md로 아직 기준이 없는 영역을 관리합니다.
- copywriting-eval/은 copy와 interface-language 동작을 테스트하지만 전체 product-design 워크플로는 평가하지 않는다고 설명합니다.
- Component APIs, design-system rules, accessibility criteria, interaction guidance는 각 소유자의 canonical source에 남겨 둡니다.
- material changes, copy, component, layout, interaction, accessibility, resilience 작업마다 서로 다른 reference를 우선 로드하도록 라우팅합니다.
- modal에는 destructive-action patterns와 canonical verbs를, settings form에는 labels, validation, progressive disclosure, accessible-name guidance를 연결합니다.
- copy rules에 stable ID를 부여하고 canonical source와 연결해 추적 가능하게 합니다.
- Vercel Agent가 patch를 제안할 때 secure Vercel Sandbox에서 builds, tests, linters로 검증한 뒤 제안하도록 합니다.
- nested modals 방지, radio buttons 권장, accessible names 요구, className의 색상·radius·shadow 덮어쓰기 차단, Modal.Body 요구, Material 클래스 사용, 4px grid 이탈 spacing 경고 같은 lint rule 예시를 제시합니다.
- 각 rule은 문제가 되는 이유와 구체적인 수정안을 설명하고, 일부는 deprecated Tailwind utility name 치환 같은 안전한 autofix를 제공합니다.
- accepted decisions는 Geist component 옆의 human-readable guidance, product-design skill의 agent guidance, lint rule 등 여러 형태로 존재할 수 있다고 설명합니다.
- holdouts와 fixtures로 skill이 본 적 없는 인터페이스에서의 동작을 평가하고, shipped result와의 유사도보다 rule correctness를 따로 점수화합니다.
- 주간 evidence-intake workflow가 Slack, Figma, GitHub, preview 등의 증거를 모으고, collector와 judge를 분리해 검토 패킷을 만듭니다.
- human reviewer가 후보를 agent guidance, lint rule, example, eval, 또는 변경 없음으로 결정하며, 승인된 변경만 가장 좁은 관련 파일에 반영됩니다.
- destructive actions, error states, settings forms, empty states, navigation 같은 반복 결정부터 시작해 기준을 확장하는 방법을 제안합니다.
- trigger를 별도 평가하고, routing·rules·evidence를 분리하며, ownership과 update loop를 두는 운영 원칙을 제시합니다.