들어가며
AI 코딩 에이전트에게 "로그인 폼 만들어줘"라고 했더니, 있지도 않는 props를 쓰고, import 경로를 틀리고, 프로젝트 테마와 전혀 안 맞는 결과물이 나온 경험이 있나요?
shadcn/ui가 더 확실하고 사용하기 쉽게 shadcn/cli v4로 업데이트 되었어요.
shadcn/ui가 AI 시대에 주목받는 이유
shadcn/ui는 이미 주목을 많이 받았던 UI 프레임워크이지만 AI시대가 되며 더더욱 많이 주목받고 활용되고 있습니다.
일반적인 컴포넌트 라이브러리와 다르죠. npm에서 패키지를 설치하는 방식이 아니라, 컴포넌트 코드를 직접 프로젝트에 복사하는 구조입니다.
npx shadcn@latest add button
# → src/components/ui/button.tsx 파일이 생성됨
이 "코드 소유" 방식이 AI와 합이 좋아요:
- AI가 컴포넌트 코드를 직접 읽고 이해할 수 있다
- 숨겨진 추상화 없이 모든 구현이 투명하다
- 프로젝트에 맞게 자유롭게 수정 가능하다
하지만 AI가 "shadcn/ui를 안다"고 해도, 내 프로젝트에서 어떻게 설정되어 있는지는 모른다는 점에서 문제가 종종 발생해요. CLI v4가 이 문제를 해결해줍니다.
CLI v4의 핵심: AI 에이전트를 위한 3가지 설정
1. Skills — "AI에게 내 프로젝트를 알려주는 법"
문제
Claude Code나 Codex 같은 AI 에이전트는 학습 데이터에 의존하죠. 하지만 shadcn/ui는 빠르게 업데이트되고, 프로젝트마다 설정이 다릅니다.
결과적으로:
- 컴포넌트 API를 잘못 사용
- 테마 토큰이 불일치
- import 경로 오류
- 올바른 props를 찾느라 시간 낭비
해결: shadcn/skills
npx skills add shadcn/ui이 한 줄이면 AI 에이전트가 내 프로젝트에 대해 자동으로 파악을 합니다:
- components.json 설정 (프레임워크, CSS 변수, 경로 등)
- Tailwind 설정
- 설치된 컴포넌트 목록
- 아이콘 라이브러리 종류
- 프레임워크 타입과 버전
설정 전 vs 설정 후
# Skills 설정 전
// AI가 추측으로 생성한 코드
import { Button } from "shadcn/button" // 경로 틀림
<Button variant="solid"> // 존재하지 않는 variant
# Skills 설정 후
// AI가 실제 설정을 읽고 생성한 코드
import { Button } from "@/components/ui/button" // 정확한 경로
<Button variant="default"> // 올바른 variant
Skills는 AI에게 "추측하지 말고 읽어라"를 가능하게 만듭니다.
2. MCP Server — "AI가 실시간으로 문서를 찾아보는 법"
문제
AI의 학습 데이터에는 시점이 있죠. shadcn/ui가 어제 업데이트 했다면 Data Table의 새로운 정렬 API를 AI는 모릅니다.
해결: shadcn MCP 서버
claude mcp add shadcn -- npx shadcn@latest mcpMCP(Model Context Protocol)는 AI 에이전트가 실시간으로 shadcn/ui 레지스트리에 접근할 수 있게 해줍니다.
AI가 할 수 있게 되는 것:
- 컴포넌트 문서와 예제를 실시간 조회
- 최신 API와 props 확인
- 설치 명령어 자동 생성
- 커뮤니티 레지스트리 검색
실제 사용 예시
개발자: "Data Table에 정렬 기능 추가해줘"
AI (MCP 없이): 학습 데이터 기반으로 추측 → 구버전 API 사용 → 에러
AI (MCP 있음): shadcn 레지스트리에서 최신 Data Table 문서 조회
→ 현재 버전의 정확한 정렬 API 확인
→ 올바른 구현 코드 생성
VS Code에서 설정하기
.vscode/mcp.json 파일에 추가:
{
"servers": {
"shadcn": {
"command": "npx",
"args": ["shadcn@latest", "mcp"]
}
}
}
3. Preset — "디자인 시스템을 한 줄로 전달하는 법"
문제
AI가 컴포넌트를 올바르게 생성해도, 색상이 프로젝트 테마와 안 맞고, 폰트가 다르고, border-radius가 일관성 없는 경우가 흔하게 일어납니다.
해결: 프리셋 코드
프리셋은 디자인 시스템 전체를 짧은 코드 한 줄로 압축합니다.
npx shadcn@latest init --preset a1Dg5eFl
이 코드 안에 담기는 것:
- 색상 팔레트 (라이트/다크 모드 포함)
- 테마 설정
- 아이콘 라이브러리
- 폰트
- Border radius
프리셋 만드는 법
1. shadcn/create에 접속
2. 시각적으로 색상, 폰트, 반경 등을 조정
3. 실제 UI 컴포넌트로 미리보기
4. 프리셋 코드 생성 (예: a1Dg5eFl)
5. 팀에 공유하거나 AI에게 전달
활용 시나리오
팀 프로젝트:
"이 프리셋 코드로 프로젝트 초기화해줘: a1Dg5eFl"
→ 모든 팀원이 동일한 디자인 시스템을 즉시 적용
AI에게 디자인 시스템 전달:
"이 프리셋 기반으로 대시보드 페이지 만들어줘"
→ AI가 프리셋의 정확한 색상, 폰트, 스타일을 사용하여 일관된 UI 생성
CLI v4의 그 외 유용한 기능들
--dry-run, --diff, --view: 변경 전 확인
AI 에이전트가 컴포넌트를 추가하기 전에, 어떤 파일이 어떻게 바뀌는지 미리 볼 수 있어요.
# 실제 변경 없이 미리보기
npx shadcn@latest add button --dry-run
# 기존 코드와 차이점 비교
npx shadcn@latest add button --diff
# 컴포넌트 코드만 보기
npx shadcn@latest add button --view이것은 AI가 자율적으로 작업할 때 특히 중요해요. "일단 추가하고 보자"가 아니라, 확인 후 적용이 가능해지기 때문이죠.
shadcn docs: 터미널에서 문서 조회
npx shadcn@latest docs combobox브라우저를 열 필요 없이 CLI에서 바로 컴포넌트 문서, 예제 코드, 사용법을 확인할 수 있어요. AI 에이전트도 이 명령어로 필요한 정보를 즉시 가져올 수 있고요.
shadcn info: 프로젝트 진단
npx shadcn@latest info현재 프로젝트의 프레임워크, 버전, CSS 변수, 설치된 컴포넌트 등 전체 현황을 출력합니다. AI에게 "내 프로젝트 상태 알려줘"를 자동화한 것이에요.
shadcn init --template: 프로젝트 스캐폴딩
# Next.js 프로젝트 한 번에 생성
npx shadcn@latest init -t next
# 모노레포 구조
npx shadcn@latest init -t next --monorepoNext.js, Vite, Laravel, React Router, Astro, TanStack Start를 지원합니다. 다크 모드 설정도 자동으로 포함되요.
shadcn init --base: 프리미티브 선택
npx shadcn@latest init --base radix # Radix UI 기반
npx shadcn@latest init --base base-ui # Base UI 기반프로젝트에 맞는 headless UI 프리미티브를 선택할 수 있습니다.
실전 워크플로우: 처음부터 끝까지
Step 1: 프로젝트 초기화\
# 프리셋 포함 Next.js 프로젝트 생성
npx shadcn@latest init -t next --preset a1Dg5eFl
Step 2: AI 에이전트 연동
# Skills 설치 (프로젝트 컨텍스트)
npx skills add shadcn/ui
# MCP 서버 연결 (실시간 문서)
claude mcp add shadcn -- npx shadcn@latest mcp
Step 3: AI와 함께 개발
개발자: "사용자 프로필 페이지를 만들어줘.
Avatar, Card, Badge, Tabs 컴포넌트를 써서."
AI 에이전트:
1. Skills로 프로젝트 설정 확인
2. MCP로 각 컴포넌트 최신 API 조회
3. 프리셋 기반 테마에 맞는 코드 생성
4. --diff로 변경사항 확인 후 적용(물론 실제로 X만들어줘. 하진 않죠...)
Step 4: 검증
# 컴포넌트가 올바르게 추가되었는지 확인
npx shadcn@latest info
왜 이 조합이 좋을까요?
이전에는 AI에게 UI를 맡기면...?
AI가 코드 생성 → 에러 발생 → 수동으로 수정 → 다시 요청 → 또 에러
→ 결국 직접 작성 → "AI 쓰느니 직접 하는 게 낫다"
Skills + MCP + Preset 조합은...!
AI가 프로젝트 설정 읽음 (Skills)
→ 최신 문서 확인 (MCP)
→ 디자인 시스템에 맞게 생성 (Preset)
→ 변경 전 검증 (--diff)
→ 한 번에 올바른 결과물
핵심은 AI에게 컨텍스트를 주는 것이에요. 똑똑한 AI에게 정보를 안 주면 추측할 수밖에 없고, 추측은 항상 옳지는 않아요. 정보를 주면 그만큼 정확해지죠. 당연한 이야기지만, shadcn/cli v4는 이 "정보 전달"을 자동화했다는 점에서 의미가 큰 것 같아요.
기존 프로젝트에도 적용 가능한가?
가능합니다. components.json이 존재하는 프로젝트라면 Skills가 자동으로 감지해요. 새 프로젝트를 만들 필요 없이, 기존 shadcn/ui 프로젝트에 바로 적용할 수 있어요.
# 기존 프로젝트에서
npx skills add shadcn/ui # Skills 추가
claude mcp add shadcn -- npx shadcn@latest mcp # MCP 연결
# 끝. 바로 사용 가능.
registry:base와 registry:font
CLI v4에서 레지스트리도 크게 강화되었어요.
registry:base는 전체 디자인 시스템을 하나의 페이로드로 배포할 수 있게 해요. 컴포넌트, 의존성, CSS 변수, 폰트, 설정 파일을 한 번의 설치로 모두 가져옵니다.
registry:font는 폰트를 1급 레지스트리 타입으로 승격되었어요. 컴포넌트를 설치하듯이 폰트를 설치하고 관리할 수 있어요.
회사나 팀이 자체 디자인 시스템을 만들어 사내 레지스트리로 배포하면, 새 프로젝트를 시작할 때 명령어 하나로 전체 디자인 시스템으로 설정할 수 있어요. AI 에이전트도 이 레지스트리를 참조하여 일관된 코드를 생성할 수 있고요.
마치며
shadcn/ui의 철학은 처음부터 "코드를 소유하라(own the code)"였어요.
npm 패키지에 의존하지 말고, 컴포넌트 코드를 직접 가져와서 원하는 대로 수정하라는 것이죠.
CLI v4는 이 철학을 AI 시대에 맞게 확장했다고 볼 수 있어요.
이상 shadcn 업데이트 관련 소식을 마칩니다.
긴 글 읽어주셔서 감사합니다.
참고 자료
- [shadcn/cli v4 공식 체인지로그](https://ui.shadcn.com/docs/changelog/2026-03-cli-v4)
- [shadcn/ui + Claude Code: 3 Settings That Fix AI-Generated UI Quality](https://dev.to/_46ea277e677b888e0cd13/shadcnui-claude-code-3-settings-that-fix-ai-generated-ui-quality-2dea)
- [shadcn MCP Server 공식 문서](https://ui.shadcn.com/docs/mcp)
- [How to use AI to build accurate ShadCN components — LogRocket](https://blog.logrocket.com/ai-shadcn-components/)
- [shadcn/ui 공식 사이트](https://ui.shadcn.com/)