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, 사용성, 플로우, 온보딩, 설정, 대시보드, build, improve,
  fix, audit, review, polish, simplify, production-ready 요청에서 트리거된다. 백엔드
  동작이 사용자에게 보이는 결과를 바꿀 때도 사용한다. 사용자에게 보이는 효과가 없는 백엔드
  전용 작업, 출시 UI에 영향이 없는 테스트, 텔레메트리 전용 작업, 문서, 마케팅 콘텐츠에는
  사용하지 않는다.
---

# Vercel 제품 디자인

사용자와 제품, 그리고 Vercel 모두에게 올바른 인터페이스를 만든다. 동작하는 코드만으로는 충분하지 않다: 올바른 인터랙션을 고르고, 범위와 결과를 명확히 하며, 정상 경로(happy path) 너머의 현실까지 다루고, 렌더링된 결과를 검증한다.

## 운영 원칙(Operating Contract)

- **픽셀이 아니라 할 일에서 시작한다.** 누가 행동하는지, 무엇을 달성하려 하는지, 관련된 제품 객체가 무엇인지, 시스템이 무엇을 바꿀지를 파악한다.
- **산출물보다 결과를 먼저 정의한다.** 화면이나 컴포넌트를 고르기 전에 현재 사용자 문제, 원하는 동작, 성공 신호, 그리고 비목표(non-goals)를 확정한다.
- **취향이 아니라 근거를 사용한다.** 의사결정을 제품 동작, 표준 저장소 가이드, 확정된 디자인 결정, 또는 검증된 인접 패턴에 근거를 두고 추적한다.
- **사실과 결정을 분리한다.** 가정과 아직 결정되지 않은 제품 선택을 명시적으로 표시한다. 구현 세부사항 안에 숨기지 않는다.
- **출시된 코드는 자동적인 선례가 아니라 근거로 다룬다.** 무엇이 존재하는지는 증명하지만, 왜 그것이 옳은지는 증명하지 않는다. 현재 컴포넌트, 제품 동작, 명시적 가이드에 비추어 확인한다.
- **가장 작고 일관된 개입을 선택한다.** UI를 추가하기 전에 더 나은 기본값, 동작, 또는 재사용을 먼저 고려한다. 하나의 일을 해결하려고 관련 없는 설정이나 추상화를 만들지 않는다.
- **꾸미기 전에 결정한다.** 스타일링이나 카피 수정에 앞서 정보 구조, 컴포넌트 의미, 인터랙션, 상태 동작을 먼저 정한다.
- **도달 가능한 모든 상태를 설계한다.** 제품이 실제로 진입할 수 있는 상태만 포함하되, 데이터가 채워진 성공 케이스에서 멈추지 않는다.
- **실제 화면을 검증한다.** 소스 점검은 동작을 확인해 주고, 렌더링된 인터페이스는 시각적·인터랙션 품질을 확인해 준다. 코드만으로 시각적 검증을 했다고 주장하지 않는다.
`product-design`

## 요청 모드(Request Modes)

행동하기 전에 사용자의 동사와 산출물로부터 모드를 판별한다.

| 모드      | 일반적 요청                                                                    | 요구되는 행동                                                                                                                                                      |
| --------- | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Shape     | "이 플로우를 디자인해줘", "이건 어떻게 동작해야 해?", UI가 확정되지 않은 기능 브리프      | 문제와 근거를 정리하고, 중대한 대안들을 비교한 뒤, 플로우·상태·수용 기준·위험·미해결 결정을 정의한다. 요청받지 않는 한 수정하지 않는다. |
| Implement | "구축", "수정", "개선", "규정 준수", 또는 "전체에 product-design 적용" | 중대한 제품 의사결정을 정리한 뒤, 범위 내에서 가장 작고 일관된 종단 간(end-to-end) 변경을 구현한다. 관련 없는 리뷰 발견 사항을 끌어들이지 않는다.                      |
| Review    | "점검", "비평", "뭐가 문제야?", 코드 리뷰                                  | 소스와 렌더링된 근거를 점검한 뒤, 우선순위가 매겨진 발견 사항을 보고한다. 요청받지 않는 한 수정하지 않는다.                                                                      |
| Copy      | "카피 수정해줘", "이 오류 메시지 다시 써줘"                                             | 사용자 대면 문구, 접근 가능한 이름, 그리고 직접적으로 필요한 JSX만 수정한다. 구조적 장애물은 조용히 범위를 넓히지 말고 보고한다.                             |
| Harden    | "다듬기", "프로덕션 준비", "엣지 케이스 처리"                                           | 확정된 제품 방향을 유지하면서 상태, 복원력, 반응형, 접근성, 마감 결함을 수정한다.                                              |

의도가 모호할 때는 동사가 뒷받침하는 가장 좁은 모드를 사용한다. URL, 스크린샷, 라우트, 컴포넌트는 범위를 특정해 줄 뿐, 그 자체로 수정을 허가하지는 않는다.

중대한 결정이란 사용자의 작업, 기본값, 범위, 결과, 내비게이션, 인터랙션 화면, 또는 도달 가능한 상태를 바꾸는 것이다. 카피의 기계적 처리, 토큰 치환, 확립된 컴포넌트 교체는 대개 중대하지 않다.

## 결정 권한(Decision Authority)

충돌은 다음 순서로 해소한다:

1. 사용자의 명시적 목표와 제약.
2. 검증된 사용자/제품 근거와 시스템의 사실.
`AGENTS.md`
4. 안정적인 근거를 갖춘, 확정된 제품/디자인 결정과 예시(exemplar).
5. 동일 제품 영역에서 검증된, 출시된 인접 패턴.
6. 일반적인 인터페이스 휴리스틱.

## 워크플로(Workflow)

### 1. 범위와 모드 설정

작업 계획이나 리뷰 노트에 대상 화면과 요청 모드를 명시한다.

### 2. 제품 맥락 로드

`AGENTS.md`

### 3. 제품 의사결정 모델링

`product-judgment.md`

### 4. 화면과 상태 매핑

진입점, 보이는 영역, 오버레이, 전환, 종료 경로, 복귀 경로를 목록화한다. 로딩, 빈 상태, 희소(sparse), 채워진 상태, 검증, 오류, 권한, 비활성, 낙관적(optimistic), 오래된(stale), 파괴적, 반응형 변형을 포함해 도달 가능한 상태만 매핑한다.

### 5. 라우팅된 레퍼런스 로드

| 필요 | 로드 |
| ---- | ---- |
`product-judgment.md`
`interface-quality.md`
`copy.md`
`design-guidelines`
`web-interface-guidelines`
`resilience.md`

### 6. 결정한 뒤 구현

기계적이지 않은 변경마다 다음에 답할 수 있어야 한다: 이것은 어떤 사용자 문제를 해결하는가, 왜 이 컴포넌트가 적절한가, 인터페이스가 전달해야 할 결과는 무엇인가, 어떤 근거가 이 결정을 뒷받침하는가, 그리고 가장 작고 일관된 변경은 무엇인가?

### 7. 검증

1. 주요 작업과 수용 기준을 확인한다.
2. 저장소 린트 검사를 실행한다.
3. 관련된 좁은 뷰포트와 넓은 뷰포트를 점검한다.
4. 중대하게 변경된 도달 가능한 상태를 모두 실행해 본다.
5. 키보드 순서, 포커스 이동, 로딩 동작, 포인터/터치 타깃을 검증한다.
6. 긴 콘텐츠, 큰 값, 제한된 너비, 그리고 현지화/RTL 위험을 테스트한다.
`review-design-system`

## 제품 디자인 표준(Product Design Standards)

- 사용자의 주요 작업과 주요 동작을 명확하게 만든다.
- 검증된 문제를 해결하는 경우가 아니라면 사용자의 멘탈 모델과 현재 맥락을 유지한다.
- 중요한 동작의 정확한 대상, 범위, 결과를 명시한다.
- 내비게이션에는 내비게이션 컴포넌트를, 동작에는 동작 컴포넌트를 사용한다.
- 중요도에 맞춰 화면의 지속성(persistence)을 선택한다.
- 모달을 추가하기 전에 인라인 노출을 우선한다.
- 기본 경로가 그 복잡성을 떠안지 않도록 하면서, 필요할 때 고급 컨트롤을 노출한다.
- 사용자가 배우고 관리해야 하는 설정을 추가하기보다, 강력한 기본값과 직접적인 동작을 우선한다.
- 커스텀 HTML이나 스타일링에 앞서 의미론적 Geist 컴포넌트와 그 API를 사용한다.
- 컨테이너를 추가하기 전에 위계, 간격, 정렬을 활용한다.
- 검증과 복구 가능한 오류 상황에서도 사용자 입력을 보존한다.
- 로딩 중 컨트롤 라벨을 그대로 유지하고, 컴포넌트의 로딩/바쁨(busy) 어포던스를 사용한다.
- 파괴적 동작은 그 영향에 비례하게 만들고, 시스템이 정직하게 지원할 수 있을 때 실행 취소(undo)를 제공한다.
- 구조, 상태, 브랜드 의도를 명확히 하는 경우가 아니라면 장식적인 새로움, 모션, 카피를 추가하지 않는다.

## 리뷰 산출물(Review Output)

사용자 영향 순으로 정렬한 발견 사항을 먼저 제시한다:

- **P0:** 주요 작업을 가로막거나, 심각한 접근성 실패를 일으키거나, 복구 불가능한 사용자 피해를 초래할 수 있음.
- **P1:** 작업 실패 가능성이 높거나, 결과를 오도하거나, 중요한 상태가 누락되었거나, 중대한 반응형/접근성 결함.
- **P2:** 의미 있는 마찰, 비일관성, 약한 위계, 또는 복구 가능성 문제.
- **P3:** 사소한 완성도나 일관성 개선.

각 발견 사항에는 다음을 포함한다: 파일/라인 또는 렌더링된 위치, 검증 상태, 표준 출처, 사용자에게 미치는 결과, 그리고 가장 작고 구체적인 수정안.

## 스킬 무결성(Skill Integrity)

- 규칙은 최신 출처 검증과 사람의 승인을 거친 뒤에만 추가하거나 변경한다.
- 범위, 근거, 증거, 예외, 그리고 나쁜/좋은 예시를 기록한다.
- 가장 좁은 대상을 우선한다: 표준 출처, 라우팅된 레퍼런스, 예시, 린트/eval 검사, 또는 커버리지 갭.
- 결정론적 검사는 기계적으로 유지한다. 판단은 그 근거와 자유도와 함께 산문으로 남긴다.
- 스크린샷 하나, 출시된 파일 하나, 리뷰어 코멘트 하나만으로 그것을 보편적 규칙으로 격상하지 않는다.

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) },
        });
      },
    };
  },
};

# 의사결정: {name}
상태: proposed | accepted | rejected
범위:
결정:
근거:
증거:
예외:
나쁜 예시:
좋은 예시:
가정:
미해결 결정:

사용자 대면 UI를 설계, 수정, 또는 리뷰할 때는
.agents/skills/product-design/SKILL.md를 불러온다.

적용 대상:
- 사용자 대면 페이지와 컴포넌트
- 카피, 인터랙션, 접근성, 반응형 동작, 그리고 상태

건너뛸 것:
- 사용자에게 보이는 효과가 없는 백엔드 전용 작업
- 텔레메트리, 생성된 파일, 문서, 그리고 마케팅

# {화면}

로드 시점:
표준 소유자:

## rule/{stable-id}
범위:
규칙:
이유:
예외:
출처:

## 예시
나쁨:
좋음:

## 커버리지 갭
- {누락된 의사결정 또는 근거}

렌더링 없이 코드가 그 실패를 식별할 수 있는가?
- 아니오: 에이전트 가이드를 사용한다.
- 예: 그 규칙이 발생하기 쉬운 거짓 양성(false positive)을 피할 수 있는가?
  - 아니오: 에이전트 가이드를 사용한다.
  - 예: 위반에 구체적인 수정안이 있는가?
    - 예: 린터를 사용한다.
    - 아니오: 경고 또는 에이전트 가이드를 사용한다.

제품이나 코드베이스 맥락이 필요함: 에이전트 가이드를 사용한다.
새로운 표준이나 제품 정책을 수립함: 사람의 결정을 요구한다.
어느 경로든, 회귀를 잡아낼 수 있는 예시나 eval을 추가한다.

수집자 프롬프트
당신은 수집자다. 메시지, 링크, 파일, 주변 맥락을 모은다.
원시 자료만 작성한다. 후보를 채점하거나 규칙을 제안하지 않는다.

판정자 프롬프트
당신은 판정자다. 관련 근거를 묶기 전에 커버리지를 검증한다.
검증된 사실, 추론, 미해결 질문을 분리한다.
모든 후보를 보류 상태로 유지한다. 가이드를 수정하지 않는다.

사람 리뷰
선택한다: 규칙, 레퍼런스, 예시, 린트 규칙, eval, 커버리지 갭, 또는 변경 없음.
안정적인 근거, 명시적 범위와 예외, 그리고 승인자를 요구한다.