내보내기 복사 경계와 스킬 별칭
마이그레이션, 설치, 수정 및 경험 기록은 현재 로드된 대상 호스트 스킬 복사본에만 적용됩니다. 원본 Codex 스킬/MCP, 다운로드된 소스 코드 및 original-skills는 모두 소스 자료이며, 본 복사본 실행으로 인해 기록되지 않습니다. 사용자가 Codex 제품 자체를 별도로 구성하도록 요청하는 경우에만 해당 제품 흐름에 따라 지정된 대상을 처리합니다. 스크립트에 설치 디렉토리 또는 상태 디렉토리가 필요한 경우 대상 경로를 명시적으로 제공하고, CODEX_HOME에서 기록 위치를 암시적으로 추론하지 않아야 합니다.
교차 스킬 이름은 소스 라이브러리의 별칭을 사용할 수 있습니다. 먼저 스킬 별칭 표를 확인하고, 동일한 소스 및 플러그인의 항목을 우선 선택한 다음 id를 사용하여 해당 진입점을 호출하거나 읽습니다. 이전 $skill 또는 superpowers:skill 이름이 새 호스트에 직접 등록되어 있다고 가정해서는 안 됩니다. 대상을 확인할 수 없는 경우 먼저 확인하고 실제 제품 명령이나 셸 환경 변수를 대체하지 마십시오.
크로스 호스트 사용 규칙
본 복사본은 Agent Skills를 지원하는 클라이언트에서 사용하기 위한 것입니다. 본문 워크플로를 실행하기 전에 현재 호스트가 실제로 제공하는 도구, 권한 및 연결된 서비스를 확인하십시오. 원문의 호스트 도구 식별자는 기능 참고용이며, 해당 도구가 실제로 발견된 경우에만 호출할 수 있습니다. 다른 호스트는 검증된 동등한 MCP, CLI 또는 API를 사용해야 합니다. 동등한 기능이 없는 단계는 사용 불가능하다고 보고해야 하며, 호출이나 완료 상태를 허위로 생성해서는 안 됩니다.
스킬 리소스는 이 스킬 디렉토리를 기준으로 합니다. 출력은 현재 프로젝트에서 사용자가 지정한 위치에 기록됩니다. 스킬 이름이나 자연어로 트리거되며, 구체적인 단축 명령은 호스트가 결정합니다. 실제 제품, 모델 API, 프로토콜 필드 및 공식 URL의 이름은 원래 의미를 유지합니다. 권한 부여, 승인, 개인 정보 보호 및 도구 범위 제한은 마이그레이션 후에도 계속 적용되며, 호환성을 위해 권한을 확장해서는 안 됩니다. 구체적인 종속성 및 마이그레이션 지침은 동일한 디렉토리의 PORTABILITY.md를 참조하십시오.
shadcn/ui
UI, 컴포넌트 및 디자인 시스템을 구축하기 위한 프레임워크입니다. 컴포넌트는 CLI를 통해 사용자 프로젝트에 소스 코드로 추가됩니다.
중요: 모든 CLI 명령은 프로젝트의
packageManager를 기반으로npx shadcn@latest,pnpm dlx shadcn@latest또는bunx --bun shadcn@latest와 같은 프로젝트 패키지 러너를 사용하여 실행하십시오. 아래 예제는npx shadcn@latest를 사용하지만 프로젝트에 맞는 올바른 러너로 대체하십시오.
현재 프로젝트 컨텍스트
!`npx shadcn@latest info --json 2>/dev/null || echo '{"error": "No shadcn project found. Run shadcn init first."}'`
위 JSON에는 프로젝트 구성 및 설치된 컴포넌트가 포함되어 있습니다. npx shadcn@latest docs <component>를 사용하여 모든 컴포넌트에 대한 문서 및 예제 URL을 가져옵니다.
원칙
- 기존 컴포넌트를 먼저 사용하십시오. 사용자 정의 UI를 작성하기 전에
npx shadcn@latest search를 사용하여 레지스트리를 확인하십시오. 커뮤니티 레지스트리도 확인합니다. - 구성하고, 다시 발명하지 마십시오. 설정 페이지 = Tabs + Card + form 컨트롤. 대시보드 = Sidebar + Card + Chart + Table.
- 사용자 정의 스타일보다 기본 제공 변형을 사용하십시오.
variant="outline",size="sm"등. - 의미론적 색상을 사용하십시오.
bg-primary,text-muted-foreground—bg-blue-500과 같은 원시 값은 절대 사용하지 마십시오.
중요 규칙
이 규칙은 항상 적용됩니다. 각 규칙은 잘못된/올바른 코드 쌍이 있는 파일에 연결됩니다.
스타일링 및 Tailwind → styling.md
className은 레이아웃에만 사용하고, 스타일링에는 사용하지 마십시오. 컴포넌트 색상이나 타이포그래피를 절대 재정의하지 마십시오.space-x-*또는space-y-*를 사용하지 마십시오.flex와gap-*를 사용하십시오. 수직 스택의 경우flex flex-col gap-*.- 너비와 높이가 같으면
size-*를 사용하십시오.w-10 h-10대신size-10. truncate약어를 사용하십시오.overflow-hidden text-ellipsis whitespace-nowrap대신.- 수동
dark:색상 재정의를 사용하지 마십시오. 의미론적 토큰 (bg-background,text-muted-foreground)을 사용하십시오. - 조건부 클래스에는
cn()을 사용하십시오. 수동 템플릿 리터럴 삼항 연산자를 작성하지 마십시오. - 오버레이 컴포넌트에 수동
z-index를 사용하지 마십시오. Dialog, Sheet, Popover 등은 자체 스태킹을 처리합니다.
폼 및 입력 → forms.md
- 폼은
FieldGroup+Field를 사용합니다. 폼 레이아웃에 원시div와space-y-*또는grid gap-*를 절대 사용하지 마십시오. InputGroup은InputGroupInput/InputGroupTextarea를 사용합니다.InputGroup내부에서 원시Input/Textarea를 절대 사용하지 마십시오.- 입력 내부의 버튼은
InputGroup+InputGroupAddon을 사용합니다. - 옵션 세트(2–7개 선택지)는
ToggleGroup을 사용합니다. 수동 활성 상태로Button을 반복하지 마십시오. - 관련 체크박스/라디오 그룹화에는
FieldSet+FieldLegend를 사용합니다. 제목이 있는div를 사용하지 마십시오. - 필드 유효성 검사는
data-invalid+aria-invalid를 사용합니다.Field에는data-invalid, 컨트롤에는aria-invalid를 사용합니다. 비활성화된 경우Field에는data-disabled, 컨트롤에는disabled를 사용합니다.
컴포넌트 구조 → composition.md
- 항목은 항상 해당 그룹 내부에 있습니다.
SelectItem→SelectGroup.DropdownMenuItem→DropdownMenuGroup.CommandItem→CommandGroup. - 사용자 정의 트리거에는
asChild(radix) 또는render(base)를 사용하십시오.npx shadcn@latest info의base필드를 확인하십시오. → base-vs-radix.md - Dialog, Sheet 및 Drawer에는 항상 Title이 필요합니다. 접근성을 위해
DialogTitle,SheetTitle,DrawerTitle이 필요합니다. 시각적으로 숨기려면className="sr-only"를 사용하십시오. - 전체 Card 구성을 사용하십시오.
CardHeader/CardTitle/CardDescription/CardContent/CardFooter. 모든 것을CardContent에 덤프하지 마십시오. - Button에는
isPending/isLoading이 없습니다.Spinner+data-icon+disabled로 구성하십시오. TabsTrigger는TabsList내부에 있어야 합니다. 트리거를Tabs에 직접 렌더링하지 마십시오.Avatar에는 항상AvatarFallback이 필요합니다. 이미지 로드 실패 시를 대비합니다.
컴포넌트 사용, 사용자 정의 마크업 금지 → composition.md
- 사용자 정의 마크업보다 기존 컴포넌트를 먼저 사용하십시오. 스타일이 지정된
div를 작성하기 전에 컴포넌트가 존재하는지 확인하십시오. - Callout에는
Alert를 사용하십시오. 사용자 정의 스타일 div를 만들지 마십시오. - 빈 상태에는
Empty를 사용하십시오. 사용자 정의 빈 상태 마크업을 만들지 마십시오. - Toast는
sonner를 통해 사용하십시오.sonner의toast()를 사용하십시오. <hr>또는<div className="border-t">대신Separator를 사용하십시오.- 로딩 플레이스홀더에는
Skeleton을 사용하십시오. 사용자 정의animate-pulsediv를 사용하지 마십시오. - 사용자 정의 스타일 span 대신
Badge를 사용하십시오.
아이콘 → icons.md
Button의 아이콘은data-icon을 사용합니다. 아이콘에data-icon="inline-start"또는data-icon="inline-end"를 사용합니다.- 컴포넌트 내부의 아이콘에 크기 지정 클래스를 사용하지 마십시오. 컴포넌트는 CSS를 통해 아이콘 크기를 처리합니다.
size-4또는w-4 h-4를 사용하지 마십시오. - 아이콘을 문자열 키가 아닌 객체로 전달하십시오. 문자열 조회가 아닌
icon={CheckIcon}.
CLI
- 프리셋 코드를 수동으로 디코딩하거나 가져오지 마십시오.
npx shadcn@latest init --preset <code>에 직접 전달하십시오.
주요 패턴
다음은 올바른 shadcn/ui 코드를 구분하는 가장 일반적인 패턴입니다. 엣지 케이스는 위의 연결된 규칙 파일을 참조하십시오.
// 폼 레이아웃: FieldGroup + Field, div + Label이 아님.
<FieldGroup>
<Field>
<FieldLabel htmlFor="email">Email</FieldLabel>
<Input id="email" />
</Field>
</FieldGroup>
// 유효성 검사: Field에는 data-invalid, 컨트롤에는 aria-invalid.
<Field data-invalid>
<FieldLabel>Email</FieldLabel>
<Input aria-invalid />
<FieldDescription>Invalid email.</FieldDescription>
</Field>
// 버튼의 아이콘: data-icon, 크기 조정 클래스 없음.
<Button>
<SearchIcon data-icon="inline-start" />
Search
</Button>
// 간격: space-y-*가 아닌 gap-*.
<div className="flex flex-col gap-4"> // 올바름
<div className="space-y-4"> // 잘못됨
// 동일한 치수: w-* h-*가 아닌 size-*.
<Avatar className="size-10"> // 올바름
<Avatar className="w-10 h-10"> // 잘못됨
// 상태 색상: Badge 변형 또는 의미론적 토큰, 원시 색상 아님.
<Badge variant="secondary">+20.1%</Badge> // 올바름
<span className="text-emerald-600">+20.1%</span> // 잘못됨
컴포넌트 선택
| 필요 사항 | 사용 |
|---|---|
| 버튼/작업 | 적절한 variant가 있는 Button |
| 폼 입력 | Input, Select, Combobox, Switch, Checkbox, RadioGroup, Textarea, InputOTP, Slider |
| 2~5개 옵션 전환 | ToggleGroup + ToggleGroupItem |
| 데이터 표시 | Table, Card, Badge, Avatar |
| 내비게이션 | Sidebar, NavigationMenu, Breadcrumb, Tabs, Pagination |
| 오버레이 | Dialog (모달), Sheet (사이드 패널), Drawer (하단 시트), AlertDialog (확인) |
| 피드백 | sonner (토스트), Alert, Progress, Skeleton, Spinner |
| 명령 팔레트 | Dialog 내부의 Command |
| 차트 | Chart (Recharts 래퍼) |
| 레이아웃 | Card, Separator, Resizable, ScrollArea, Accordion, Collapsible |
| 빈 상태 | Empty |
| 메뉴 | DropdownMenu, ContextMenu, Menubar |
| 툴팁/정보 | Tooltip, HoverCard, Popover |
주요 필드
주입된 프로젝트 컨텍스트에는 다음 주요 필드가 포함되어 있습니다.
aliases→ 가져오기에 실제 별칭 접두사(예:@/,~/)를 사용하고, 하드코딩하지 마십시오.isRSC→true인 경우useState,useEffect, 이벤트 핸들러 또는 브라우저 API를 사용하는 컴포넌트는 파일 상단에"use client"가 필요합니다. 지시문에 대해 조언할 때 항상 이 필드를 참조하십시오.tailwindVersion→"v4"는@theme inline블록을 사용하고,"v3"는tailwind.config.js를 사용합니다.tailwindCssFile→ 사용자 정의 CSS 변수가 정의된 전역 CSS 파일입니다. 항상 이 파일을 편집하고 새 파일을 만들지 마십시오.style→ 컴포넌트 시각적 처리(예:nova,vega).base→ 기본 라이브러리(radix또는base). 컴포넌트 API 및 사용 가능한 속성에 영향을 줍니다.iconLibrary→ 아이콘 가져오기를 결정합니다.lucide의 경우lucide-react,tabler의 경우@tabler/icons-react등을 사용합니다.lucide-react라고 가정하지 마십시오.resolvedPaths→ 컴포넌트, 유틸리티, 훅 등을 위한 정확한 파일 시스템 대상입니다.framework→ 라우팅 및 파일 규칙(예: Next.js App Router vs Vite SPA).packageManager→ shadcn 이외의 종속성 설치(예:npm install date-fns대신pnpm add date-fns)에 사용합니다.
전체 필드 참조는 cli.md — info 명령을 참조하십시오.
컴포넌트 문서, 예제 및 사용법
npx shadcn@latest docs <component>를 실행하여 컴포넌트의 문서, 예제 및 API 참조 URL을 가져옵니다. 이러한 URL을 가져와서 실제 콘텐츠를 확인하십시오.
npx shadcn@latest docs button dialog select
컴포넌트를 생성, 수정, 디버깅 또는 사용할 때는 항상 npx shadcn@latest docs를 실행하고 URL을 먼저 가져오십시오. 이렇게 하면 추측하는 대신 올바른 API 및 사용 패턴으로 작업할 수 있습니다.
워크플로
- 프로젝트 컨텍스트 가져오기 — 위에 이미 주입되어 있습니다. 새로고침이 필요하면
npx shadcn@latest info를 다시 실행하십시오. - 먼저 설치된 컴포넌트 확인 —
add를 실행하기 전에 항상 프로젝트 컨텍스트의components목록을 확인하거나resolvedPaths.ui디렉토리를 나열하십시오. 추가되지 않은 컴포넌트를 가져오지 말고, 이미 설치된 컴포넌트를 다시 추가하지 마십시오. - 컴포넌트 찾기 —
npx shadcn@latest search. - 문서 및 예제 가져오기 —
npx shadcn@latest docs <component>를 실행하여 URL을 가져온 다음 가져오십시오.npx shadcn@latest view를 사용하여 설치하지 않은 레지스트리 항목을 찾아볼 수 있습니다. 설치된 컴포넌트의 변경 사항을 미리 보려면npx shadcn@latest add --diff를 사용하십시오. - 설치 또는 업데이트 —
npx shadcn@latest add. 기존 컴포넌트를 업데이트할 때는--dry-run및--diff를 사용하여 먼저 변경 사항을 미리 보십시오(아래 컴포넌트 업데이트 참조). - 타사 컴포넌트의 가져오기 수정 — 커뮤니티 레지스트리(예:
@bundui,@magicui)에서 컴포넌트를 추가한 후 추가된 비 UI 파일에 하드코딩된 가져오기 경로(예:@/components/ui/...)가 있는지 확인하십시오. 이러한 경로는 프로젝트의 실제 별칭과 일치하지 않을 수 있습니다.npx shadcn@latest info를 사용하여 올바른ui별칭(예:@workspace/ui/components)을 가져오고 그에 따라 가져오기를 다시 작성하십시오. CLI는 자체 UI 파일에 대한 가져오기를 다시 작성하지만 타사 레지스트리 컴포넌트는 프로젝트와 일치하지 않는 기본 경로를 사용할 수 있습니다. - 추가된 컴포넌트 검토 — 모든 레지스트리에서 컴포넌트 또는 블록을 추가한 후 항상 추가된 파일을 읽고 올바른지 확인하십시오. 누락된 하위 컴포넌트(예:
SelectGroup없는SelectItem), 누락된 가져오기, 잘못된 구성 또는 중요 규칙 위반이 있는지 확인하십시오. 또한 프로젝트 컨텍스트의iconLibrary로 아이콘 가져오기를 교체하십시오(예: 레지스트리 항목이lucide-react를 사용하지만 프로젝트가hugeicons를 사용하는 경우 가져오기 및 아이콘 이름을 그에 따라 교체). 모든 문제를 해결한 후에 진행하십시오. - 레지스트리는 명시적이어야 함 — 사용자가 블록 또는 컴포넌트 추가를 요청할 때 레지스트리를 추측하지 마십시오. 레지스트리가 지정되지 않은 경우(예: 사용자가
@shadcn,@tailark등을 지정하지 않고 "로그인 블록 추가"라고 말하는 경우) 어떤 레지스트리를 사용할지 물어보십시오. 사용자를 대신하여 레지스트리를 기본값으로 설정하지 마십시오. - 프리셋 전환 — 먼저 사용자에게 재설치, 병합 또는 건너뛰기 중 무엇을 할지 물어보십시오.
- 재설치:
npx shadcn@latest init --preset <code> --force --reinstall. 모든 컴포넌트를 덮어씁니다. - 병합:
npx shadcn@latest init --preset <code> --force --no-reinstall을 실행한 다음npx shadcn@latest info를 실행하여 설치된 컴포넌트를 나열하고, 각 설치된 컴포넌트에 대해--dry-run및--diff를 사용하여 개별적으로 스마트 병합합니다. - 건너뛰기:
npx shadcn@latest init --preset <code> --force --no-reinstall. 구성 및 CSS만 업데이트하고 컴포넌트는 그대로 둡니다. - 중요: 항상 사용자 프로젝트 디렉토리 내에서 프리셋 명령을 실행하십시오. CLI는
components.json에서 현재 기반(basevsradix)을 자동으로 유지합니다. 스크래치/임시 디렉토리를 사용해야 하는 경우(예:--dry-run비교)--base <current-base>를 명시적으로 전달하십시오. 프리셋 코드는 기반을 인코딩하지 않습니다.
- 재설치:
컴포넌트 업데이트
사용자가 로컬 변경 사항을 유지하면서 업스트림에서 컴포넌트를 업데이트하도록 요청하는 경우 --dry-run 및 --diff를 사용하여 지능적으로 병합하십시오. 절대 shadcn/ui 레지스트리에서 원시 파일 콘텐츠를 가져오지 마십시오. CLI는 로컬 변경 사항을 보존하는 업데이트된 버전을 처리합니다.
npx shadcn@latest add <component> --dry-run --diff를 실행합니다.--dry-run은 아무 것도 설치하지 않고 보고합니다.--diff는 정확한 파일 변경 사항을 보여줍니다.
- diff를 검토합니다. 로컬 변경 사항과 충돌하는 경우 사용자에게 알리고 계속 진행할지 물어보십시오.
- 사용자가 업데이트에 동의하면
--dry-run없이npx shadcn@latest add <component>를 실행하십시오.
이 접근 방식은 타사 레지스트리와 함께 작동하지만 항상 사용자에게 npx shadcn@latest add <component> --dry-run --diff를 실행할 레지스트리를 먼저 물어보십시오.
설치된 컴포넌트 확인
설치된 컴포넌트를 확인하려면 다음 중 하나를 사용하십시오.
npx shadcn@latest info --json(위에 주입됨)ls <resolvedPaths.ui>(프로젝트 컨텍스트에서resolvedPaths.ui사용)
설치된 컴포넌트는 항상 npx shadcn@latest add <component> 없이는 가져올 수 없다는 점을 기억하십시오. 이는 <Button />에 직접 적용되며, 사용자가 추가할 때까지 가져오지 마십시오.
작업 공간 지원
작업 공간 설정에서 각 작업 공간 패키지는 자체 components.json을 가질 수 있습니다. 프로젝트 컨텍스트에 여러 진입점이 표시되면 동일한 워크플로를 따르되 올바른 작업 공간에 명령을 적용하십시오. shadcn init이 여러 개 있는 경우 사용자에게 어느 것을 작업할지 물어보십시오.