Teaching agents product design at Vercel

repository/
├── AGENTS.md
├── .agents/
│   └── skills/
│       └── product-design/
│           ├── AGENTS.md
│           ├── SKILL.md
│           ├── references/
│           │   ├── product-judgment.md
│           │   ├── interface-quality.md
│           │   ├── resilience.md
│           │   ├── surfaces.md
│           │   ├── surfaces-{surface}.md
│           │   ├── copy.md
│           │   ├── rules.md
│           │   ├── glossary.md
│           │   ├── patterns.md
│           │   └── coverage-gaps.md
│           └── exemplars/
│               └── pr-{name}.md
└── tooling/
    └── scripts/
        └── evals/
            ├── fixtures.json
            ├── rules-checklist.json
            └── <fixture>/
                ├── before/
                └── after/

---
name: product-design
description: >-
  apps/vercel-site의 프로덕트 디자인과 사용자에게 보이는 제품 구현을 위한 단일
  진입점. 사용자가 보고, 이해하고, 선택하고, 행동하는 것을 바꾸는 작업이라면
  언제나 사용한다. 요구사항과 플로우 설계, 페이지와 컴포넌트의 신규 구축 또는
  리디자인, URL·스크린샷·diff·Vercel Agent 지적 사항 리뷰, 제품 카피·정보
  구조·컴포넌트 선택·Geist 준수·위계·레이아웃·인터랙션·접근성·반응형 동작 개선,
  그리고 로딩·빈 상태·에러·권한·결제·파괴적 상태 개선이 여기 해당한다.
  design, UX, UI, 사용성, 플로우, 온보딩, 설정, 대시보드, 구축, 개선, 수정,
  감사, 리뷰, 다듬기, 단순화, 프로덕션 준비 요청에서 트리거한다. 백엔드 동작이
  사용자에게 보이는 결과를 바꿀 때도 사용한다. 사용자에게 보이는 영향이 없는
  백엔드 전용 작업, 배포되는 UI에 영향이 없는 테스트, 텔레메트리 전용 작업,
  문서, 마케팅 콘텐츠에는 사용하지 않는다.
---
 
# Vercel Product Design
 
인터페이스를 사용자에게, 제품에게, 그리고 Vercel에게 올바른 것으로 만든다. 동작하는 코드만으로는 충분하지 않다. 올바른 인터랙션을 고르고, 범위와 결과를 분명히 드러내고, 해피 패스 너머의 현실을 다루고, 렌더된 결과를 검증한다.
 
## 운영 원칙(Operating Contract)
 
- **픽셀이 아니라 할 일에서 시작한다.** 누가 행동하는지, 무엇을 이루려 하는지, 어떤 제품 객체가 관여하는지, 시스템이 무엇을 바꿀지를 파악한다.
- **산출물보다 결과를 먼저 정의한다.** 서피스나 컴포넌트를 고르기 전에 현재의 사용자 문제, 원하는 동작, 성공 신호, 하지 않을 것(non-goals)을 정한다.
- **취향이 아니라 근거를 쓴다.** 결정은 제품 동작, 저장소의 표준 가이드, 합의된 디자인 결정, 검증된 인접 패턴으로 거슬러 올라갈 수 있어야 한다.
- **사실과 결정을 분리한다.** 가정과 아직 결론이 나지 않은 제품 선택은 명시적으로 표시한다. 구현 세부사항 속에 숨기지 않는다.
- **배포된 코드는 근거이지, 자동으로 선례가 되지는 않는다.** 그것은 무엇이 존재하는지를 증명할 뿐, 왜 옳은지를 증명하지 않는다. 현재 컴포넌트, 제품 동작, 명시된 가이드에 비추어 확인한다.
- **가장 작고 일관된 개입을 고른다.** UI를 추가하기 전에 더 나은 기본값, 동작, 재사용을 먼저 검토한다. 하나의 할 일을 풀기 위해 관련 없는 설정이나 추상화를 만들지 않는다.
- **꾸미기 전에 결정한다.** 스타일링이나 카피 수정에 앞서 정보 구조, 컴포넌트 시맨틱, 인터랙션, 상태 동작을 먼저 정리한다.
- **도달 가능한 모든 상태를 설계한다.** 제품이 실제로 진입할 수 있는 상태만 포함하되, 데이터가 채워진 성공 케이스에서 멈추지 않는다.
- **실제 서피스를 검증한다.** 소스 확인은 동작을 확인해 주고, 렌더된 인터페이스는 시각·인터랙션 품질을 확인해 준다. 코드만 보고 시각 검증을 했다고 주장하지 않는다.
- **사용자용 진입점은 하나로 유지한다.** `product-design`을 호출하고, 내부에서 아래의 표준 출처로 라우팅한다.
 
## 요청 모드(Request Modes)
 
행동하기 전에 사용자의 동사와 대상 산출물로 모드를 판별한다.
 
| 모드 | 대표 요청 | 요구되는 동작 |
| ---- | -------- | ------------ |
| Shape | "이 플로우를 설계해 줘", "이건 어떻게 동작해야 해?", UI가 확정되지 않은 기능 브리프 | 문제와 근거를 정리하고, 실질적인 대안을 비교한 뒤 플로우, 상태, 수용 기준, 리스크, 미결 결정을 정의한다. 요청받지 않으면 수정하지 않는다. |
| Implement | "만들어", "고쳐", "개선해", "규칙에 맞춰", "전부에 product-design 돌려" | 실질적인 제품 결정을 먼저 해결한 뒤, 범위 안에서 가장 작고 일관된 end-to-end 변경을 구현한다. 관련 없는 리뷰 지적 사항을 끌어안지 않는다. |
| Review | "감사해 줘", "비평해 줘", "뭐가 잘못됐어?", 코드 리뷰 | 소스와 렌더된 근거를 확인하고, 우선순위를 매긴 지적 사항을 보고한다. 요청받지 않으면 수정하지 않는다. |
| Copy | "카피 고쳐 줘", "이 에러 문구 다시 써 줘" | 사용자에게 보이는 문구, 접근 가능한 이름, 그리고 직접 필요한 JSX만 수정한다. 구조적 장애물은 범위를 조용히 넓히지 않고 보고한다. |
| Harden | "다듬어 줘", "프로덕션 준비", "엣지 케이스 처리해 줘" | 이미 정해진 제품 방향은 유지하면서 상태, 복원력, 반응형, 접근성, 마무리 결함을 고친다. |
 
의도가 모호할 때는 그 동사가 뒷받침하는 가장 좁은 모드를 쓴다. URL, 스크린샷, 라우트, 컴포넌트는 범위를 지정할 뿐, 그것만으로 수정을 허가하지는 않는다.
 
실질적인(material) 결정이란 사용자의 할 일, 기본값, 범위, 결과, 내비게이션, 인터랙션 서피스, 도달 가능한 상태를 바꾸는 결정이다. 카피 표기 정리, 토큰 교체, 이미 확립된 컴포넌트 대체는 보통 실질적인 결정이 아니다.
 
## 결정 권한(Decision Authority)
 
충돌은 다음 순서로 해결한다.
 
1. 사용자가 명시한 목표와 제약.
2. 검증된 사용자/제품 근거와 시스템의 실제 사실.
3. 저장소의 표준 가이드: `AGENTS.md`, Geist 컴포넌트 API, `packages/geist/STYLE_GUIDE.md`, 라우팅된 스킬.
4. 안정적인 근거를 갖춘, 합의된 제품/디자인 결정과 exemplar.
5. 같은 제품 영역에서 검증된 인접 배포 패턴.
6. 일반적인 인터페이스 휴리스틱.
 
## 워크플로우
 
### 1. 범위와 모드를 정한다
 
작업 계획서나 리뷰 노트에 대상 서피스와 요청 모드를 명시한다.
 
### 2. 제품 컨텍스트를 로드한다
 
UI를 제안하기 전에, 해당되는 `AGENTS.md` 체인, 제공된 브리프와 디자인, 그리고 변경(mutation)·권한·검증·에러·부수 효과를 결정하는 제품 로직을 읽는다.
 
### 3. 제품 결정을 모델링한다
 
Shape, Implement, Harden, 전체 Review, 또는 실질적인 제품/플로우 변경이라면 `product-judgment.md`를 읽고, 사용자, 할 일, 현재 동작, 원하는 결과, 성공 신호, 하지 않을 것, 객체, 범위, 액션, 결과, 되돌릴 수 있는지, 권한, 미결 결정을 담은 간결한 내부 브리프를 작성한다.
 
### 4. 서피스와 상태를 매핑한다
 
진입점, 보이는 영역, 오버레이, 전환, 이탈, 복귀 경로를 목록화한다. 도달 가능한 상태만 매핑하며, 여기에는 로딩, 빈 상태, 데이터가 적은 상태, 채워진 상태, 검증, 에러, 권한, 비활성, 낙관적 업데이트, 오래된 데이터, 파괴적 상태, 반응형 변형이 포함된다.
 
### 5. 라우팅된 레퍼런스를 로드한다
 
| 필요한 것 | 로드할 것 |
| -------- | -------- |
| 제품/플로우/컴포넌트 결정 | `product-judgment.md` + `component-guide` |
| 구현, 실질적인 시각 변경, 전체 리뷰 | `interface-quality.md` |
| 카피 또는 접근 가능한 이름 | `copy.md` + `surfaces.md` 라우팅 |
| 레이아웃, 타이포그래피, 색상, 여백, Geist API | `design-guidelines` + `packages/geist/STYLE_GUIDE.md` |
| 키보드, 포커스, 폼, 터치, 애니메이션, URL 상태, 성능 | `web-interface-guidelines` |
| 오버플로, 로컬라이제이션, 극단적 데이터, 네트워크/에러 복원력 | `resilience.md` |
 
### 6. 결정한 다음 구현한다
 
기계적이지 않은 모든 변경에 대해 다음에 답할 수 있어야 한다. 이 변경은 어떤 사용자 문제를 해결하는가, 왜 이 컴포넌트가 적절한가, 인터페이스가 반드시 전달해야 하는 결과는 무엇인가, 어떤 근거가 이 결정을 뒷받침하는가, 가장 작고 일관된 변경은 무엇인가.
 
### 7. 검증한다
 
1. 주된 할 일과 수용 기준을 확인한다.
2. 저장소의 린트 검사를 돌린다.
3. 좁은 뷰포트와 넓은 뷰포트를 관련 범위에서 확인한다.
4. 실질적으로 바뀐 모든 도달 가능한 상태를 직접 거쳐 본다.
5. 키보드 순서, 포커스 이동, 로딩 동작, 포인터/터치 타깃을 검증한다.
6. 긴 콘텐츠, 큰 값, 제한된 너비, 로컬라이제이션/RTL 리스크를 테스트한다.
7. 구조적으로 보이는 변경에는 `review-design-system`을 로드한다.
 
## 프로덕트 디자인 표준
 
- 사용자의 주된 할 일과 주된 액션이 헷갈릴 수 없게 만든다.
- 사용자의 멘탈 모델과 현재 컨텍스트를 유지한다. 그것을 바꾸는 것이 검증된 문제를 해결하는 경우가 아니라면.
- 중요한 액션에서는 정확한 대상, 범위, 결과를 이름으로 밝힌다.
- 내비게이션에는 내비게이션 컴포넌트를, 액션에는 액션 컴포넌트를 쓴다.
- 서피스가 얼마나 지속되어야 하는지는 중요도에 맞춰 고른다.
- 모달을 추가하기 전에 인라인 공개를 먼저 검토한다.
- 고급 컨트롤은 필요할 때 드러내되, 기본 경로가 그 복잡도를 짊어지게 하지 않는다.
- 사용자가 배우고 관리해야 하는 설정을 추가하기보다, 강력한 기본값과 직접적인 동작을 택한다.
- 커스텀 HTML이나 스타일링보다 시맨틱한 Geist 컴포넌트와 그 API를 먼저 쓴다.
- 컨테이너를 추가하기 전에 위계, 여백, 정렬을 먼저 쓴다.
- 검증과 복구 가능한 에러를 거치는 동안 사용자 입력을 보존한다.
- 로딩 중에도 컨트롤 레이블은 그대로 두고, 컴포넌트의 loading/busy 어포던스를 쓴다.
- 파괴적 액션은 그 영향에 비례하게 만들고, 시스템이 정직하게 지원할 수 있을 때 되돌리기를 제공한다.
- 구조, 상태, 브랜드 의도를 명확히 하는 경우가 아니라면 장식적인 새로움, 모션, 카피를 추가하지 않는다.
 
## 리뷰 산출물
 
사용자 영향 순으로 정렬한 지적 사항을 먼저 제시한다.
 
- **P0:** 주된 할 일을 막거나, 심각한 접근성 실패를 만들거나, 되돌릴 수 없는 사용자 피해를 일으킬 수 있음.
- **P1:** 할 일 실패 가능성이 높거나, 결과를 오해하게 만들거나, 핵심 상태가 빠졌거나, 반응형/접근성에 중대한 결함이 있음.
- **P2:** 유의미한 마찰, 비일관성, 약한 위계, 복구 가능성 문제.
- **P3:** 사소한 완성도 또는 일관성 개선.
 
각 지적 사항에는 파일/라인 또는 렌더된 위치, 검증 상태, 표준 출처, 사용자에게 미치는 결과, 그리고 가장 작은 구체적 수정안을 포함한다.
 
## 스킬 무결성(Skill Integrity)
 
- 규칙은 현재 출처를 검증하고 사람이 수락한 뒤에만 추가하거나 변경한다.
- 범위, 근거, 증거, 예외, 그리고 나쁜 예/좋은 예를 기록한다.
- 가장 좁은 목적지를 택한다. 표준 출처, 라우팅된 레퍼런스, exemplar, 린트/평가 검사, 커버리지 갭 중에서.
- 결정적 검사는 기계적으로 유지한다. 판단은 그 근거와 허용 재량과 함께 산문으로 남긴다.
- 스크린샷 하나, 배포된 파일 하나, 리뷰어 코멘트 하나만으로 보편 규칙을 만들지 않는다.

rule/destructive-names-action
 
출처: copy.md > Actionable; verbs.md
규칙: 파괴적 CTA는 '동사 + 명사'를 따른다.
      Confirm, OK, 또는 동사 하나만 쓰지 않는다.

/** @type {import('eslint').Rule.RuleModule} */
module.exports = {
  meta: {
    type: 'suggestion',
    docs: {
      description: 'Suggest Radio buttons when Select has 2-3 static options',
      category: 'Design System',
      recommended: true,
    },
    schema: [],
    messages: {
      preferRadio:
        'Select with {{ count }} static options. Consider using Radio buttons — they show all options at once without requiring a click to open.',
    },
  },
  create(context) {
    return {
      JSXElement(node) {
        const opening = node.openingElement;
        if (opening.name.type !== 'JSXIdentifier') return;
        if (opening.name.name !== 'Select') return;
        const hasDynamic = node.children.some(
          (child) =>
            child.type === 'JSXExpressionContainer' &&
            child.expression.type === 'CallExpression',
        );
        if (hasDynamic) return;
        const optionChildren = node.children.filter(
          (child) =>
            child.type === 'JSXElement' &&
            child.openingElement.name.type === 'JSXIdentifier' &&
            child.openingElement.name.name === 'option',
        );
        if (optionChildren.length < 2 || optionChildren.length > 3) return;
        context.report({
          node: opening,
          messageId: 'preferRadio',
          data: { count: String(optionChildren.length) },
        });
      },
    };
  },
};

# 결정: {이름}
상태: 제안됨 | 채택됨 | 기각됨
범위:
결정:
근거:
증거:
예외:
나쁜 예:
좋은 예:
가정:
미결 결정:

사용자에게 보이는 UI를 설계하거나, 수정하거나, 리뷰할 때는
.agents/skills/product-design/SKILL.md를 로드한다.
 
적용 대상:
- 사용자에게 보이는 페이지와 컴포넌트
- 카피, 인터랙션, 접근성, 반응형 동작, 상태
 
건너뛸 것:
- 사용자에게 보이는 영향이 없는 백엔드 전용 작업
- 텔레메트리, 생성 파일, 문서, 마케팅

# {서피스}
 
로드 시점:
표준 출처 담당:
 
## rule/{stable-id}
범위:
규칙:
이유:
예외:
출처:
 
## 예시
나쁜 예:
좋은 예:
 
## 커버리지 갭
- {빠진 결정 또는 근거}

렌더하지 않고도 코드가 그 실패를 식별할 수 있는가?
- 아니오: 에이전트 가이드를 쓴다.
- 예: 그 규칙이 오탐(false positive)을 피할 수 있는가?
  - 아니오: 에이전트 가이드를 쓴다.
  - 예: 위반에 대한 구체적인 수정안이 있는가?
    - 예: 린터를 쓴다.
    - 아니오: 경고 또는 에이전트 가이드를 쓴다.
 
제품이나 코드베이스 컨텍스트가 필요하다: 에이전트 가이드를 쓴다.
새로운 표준이나 제품 정책을 세운다: 사람의 결정을 요구한다.
어느 쪽이든, 회귀를 잡을 수 있는 예시나 평가를 추가한다.

수집자(collector) 프롬프트
너는 수집자다. 메시지, 링크, 파일, 주변 컨텍스트를 모아라.
가공하지 않은 산출물만 기록한다. 후보를 채점하거나 규칙을 제안하지 않는다.
 
판정자(judge) 프롬프트
너는 판정자다. 관련 근거를 묶기 전에 커버리지를 먼저 검증하라.
검증된 사실, 추론, 미해결 질문을 분리한다.
모든 후보는 보류 상태로 둔다. 가이드를 수정하지 않는다.
 
사람 리뷰
선택한다: 규칙, 레퍼런스, exemplar, 린트 규칙, 평가, 커버리지 갭, 또는 변경 없음.
안정적인 근거, 명시적인 범위와 예외, 그리고 승인자를 요구한다.