Ant Design CLI은(는) 무엇을 하나요?
@ant-design/cli — v4/v5/v6에 대한 번들 antd 메타데이터(및 v3→v4, v4→v5, v5→v6 마이그레이션 가이드)가 포함된 로컬 CLI 도구에 액세스할 수 있습니다. 이를 사용하여 구성 요소 지식을 쿼리하고, 프로젝트를 분석하며, 마이그레이션을 안내할 수 있습니다. 모든 데이터는 오프라인에서 사용할 수 있으며, 네트워크가 필요하지 않습니다.
설정
처음 사용하기 전에 CLI가 설치되어 있는지 확인하십시오. 설치되어 있지 않으면 자동으로 설치하십시오:
which antd || npm install -g @ant-design/cli
명령어를 실행한 후 출력에 "Update available" 알림이 포함된 경우, 계속하기 전에 antd upgrade를 실행하여 업데이트하십시오.
프로그래밍 방식으로 구문 분석할 수 있는 구조화된 출력을 위해 항상 --format json을 사용하십시오.
시나리오
1. antd 컴포넌트 코드 작성
antd 컴포넌트 코드를 작성하기 전에 먼저 해당 API를 조회하십시오. 기억에 의존하지 마십시오.
# 사용 가능한 props 확인
antd info Button --format json
# 시작점으로 사용할 수 있는 작동 데모 가져오기
antd demo Button basic --format json
# 사용자 정의 스타일링을 위한 시맨틱 classNames/styles 확인
antd semantic Button --format json
# 테마를 위한 컴포넌트 수준 디자인 토큰 확인
antd token Button --format json
# 전체 디자인 언어(design.md) 확인: 색상, 타이포그래피, 간격, 반경 + 원칙
antd design.md --format json
워크플로: antd info → props 이해 → antd demo → 작동 예제 가져오기 → 코드 작성.
2. 전체 문서 조회
포괄적인 컴포넌트 문서(props뿐만 아니라)가 필요할 때:
antd doc Table --format json # Table에 대한 전체 마크다운 문서
antd doc Table --lang zh # 중국어 문서
3. antd 문제 디버깅
코드가 예상대로 작동하지 않거나 사용자가 antd 버그를 보고할 때:
# 전체 환경 스냅샷 수집 (시스템, 종속성, 브라우저, 빌드 도구)
antd env --format json
# 사용자의 antd 버전에 대해 prop이 존재하는지 확인
antd info Select --version 5.12.0 --format json
# prop이 더 이상 사용되지 않는지 확인
antd lint ./src/components/MyForm.tsx --format json
# 프로젝트 수준 구성 문제 진단
antd doctor --format json
워크플로: antd env → 전체 환경 캡처 → antd doctor → 구성 확인 → antd info --version X → 사용자의 정확한 버전에 대한 API 확인 → antd lint → 더 이상 사용되지 않거나 잘못된 사용법 찾기.
4. 버전 간 마이그레이션
사용자가 antd를 업그레이드하려는 경우(예: v3→v4 또는 v4→v5):
# 전체 마이그레이션 체크리스트 가져오기
antd migrate 3 4 --format json # v3 → v4
antd migrate 4 5 --format json # v4 → v5
# 특정 컴포넌트에 대한 마이그레이션 확인
antd migrate 4 5 --component Select --format json
# 에이전트 친화적인 자동 마이그레이션 프롬프트 생성 (파일 수정 안 함)
antd migrate 4 5 --apply ./src --format json
# 두 버전 간의 변경 사항 확인
antd changelog 4.24.0 5.0.0 --format json
# 특정 컴포넌트에 대한 변경 사항 확인
antd changelog 4.24.0 5.0.0 Select --format json
워크플로: antd migrate → 전체 체크리스트 가져오기 → antd changelog <v1> <v2> → 주요 변경 사항 이해 → 수정 사항 적용 → antd lint → 더 이상 사용되지 않는 사용법이 없는지 확인.
5. 프로젝트 antd 사용 분석
사용자가 프로젝트에서 antd가 어떻게 사용되는지 이해하려고 할 때:
# 컴포넌트 사용 통계 스캔
antd usage ./src --format json
# 특정 컴포넌트로 필터링
antd usage ./src --filter Form --format json
# 모범 사례 위반 검사
antd lint ./src --format json
# 특정 규칙 범주만 확인
antd lint ./src --only deprecated --format json
antd lint ./src --only a11y --format json
antd lint ./src --only performance --format json
6. 체인지로그 및 버전 기록 확인
사용자가 버전의 변경 사항에 대해 물을 때:
# 특정 버전 체인지로그
antd changelog 5.22.0 --format json
# 버전 범위 (양쪽 포함)
antd changelog 5.21.0..5.24.0 --format json
7. 사용 가능한 컴포넌트 탐색
사용자가 사용할 컴포넌트를 선택할 때:
# 모든 컴포넌트를 카테고리와 함께 나열
antd list --format json
# 특정 antd 버전에 대한 컴포넌트 나열
antd list --version 5.0.0 --format json
8. 환경 정보 수집
프로젝트의 antd 설정을 이해하거나 버그 보고서를 위한 정보를 준비해야 할 때:
# 전체 환경 스냅샷 (텍스트 — GitHub Issues에 붙여넣기)
antd env
# 프로그래밍 방식 사용을 위한 구조화된 JSON
antd env --format json
# 특정 프로젝트 디렉터리 스캔
antd env ./my-project --format json
수집 항목: OS, Node, 패키지 관리자(npm/pnpm/yarn/bun/utoo), npm 레지스트리, 브라우저, 핵심 종속성(antd/react/dayjs), 모든 @ant-design/* 및 rc-* 패키지, 빌드 도구(umi/vite/webpack/typescript 등).
9. antd 버그 보고
사용자가 antd 버그를 보고하도록 요청할 때:
# 0단계: 참조용 환경 정보 수집 (선택 사항 — antd bug는 이미 기본 환경을 포함함)
# 출력을 사용하여 버전을 교차 확인하거나 버그 보고서에 추가 세부 정보 첨부
antd env --format json
# 1단계: 사용자 검토를 위한 미리보기
antd bug --title "DatePicker가 날짜 선택 시 충돌합니다" \
--reproduction "https://codesandbox.io/s/xxx" \
--steps "1. DatePicker 열기 2. 날짜 클릭" \
--expected "날짜가 선택됨" \
--actual "오류와 함께 컴포넌트 충돌" \
--format json
# 2단계: 사용자에게 보여주고 확인 요청
# 3단계: 사용자가 확인하면 제출
antd bug --title "DatePicker가 날짜 선택 시 충돌합니다" \
--reproduction "https://codesandbox.io/s/xxx" \
--steps "1. DatePicker 열기 2. 날짜 클릭" \
--expected "날짜가 선택됨" \
--actual "오류와 함께 컴포넌트 충돌" \
--submit
10. CLI 문제 보고
사용자가 CLI 버그를 보고하도록 요청하거나, 명시적으로 버그 제출을 요청할 때:
# 사용자를 위한 버그 보고서 미리보기
antd bug-cli --title "antd info Button이 v5.12.0에 대해 잘못된 props를 반환합니다" \
--description "버전 5.12.0에 대한 Button props를 쿼리할 때, 출력에 해당 버전에 존재하지 않는 props가 포함됩니다" \
--steps "1. 실행: antd info Button --version 5.12.0 --format json" \
--expected "antd 5.12.0 Button API와 일치하는 props" \
--actual "props에 'classNames'가 포함되어 있으며 이는 5.16.0에서 추가되었습니다" \
--format json
보고서를 사용자에게 보여주고 제출 전에 확인하십시오:
antd bug-cli --title "antd info Button이 v5.12.0에 대해 잘못된 props를 반환합니다" \
--description "..." \
--steps "..." \
--expected "..." \
--actual "..." \
--submit
거부: 환경 변수 ANTD_NO_AUTO_REPORT=1이 설정된 경우, 버그 보고 제안을 모두 건너뛰십시오. 사용자가 직접 요청하지 않는 한 antd bug 또는 antd bug-cli를 제안하지 마십시오.
11. CLI 업그레이드
사용자가 @ant-design/cli를 최신 버전으로 업데이트하거나 "Update available" 알림이 표시될 때:
# 최신 버전으로 업그레이드 (패키지 관리자 자동 감지)
antd upgrade
이 명령은 CLI를 설치한 패키지 관리자(npm, yarn, pnpm, bun, cnpm, utoo)를 감지하고 적절한 업그레이드 명령을 실행합니다. 감지에 실패하면 수동 명령을 제안합니다.
12. MCP 서버로 사용
MCP를 지원하는 IDE(Claude Desktop, Cursor 등)에서 작업하는 경우, CLI를 MCP 서버로 실행하여 모든 지식 쿼리 도구를 직접 노출할 수 있습니다:
{
"mcpServers": {
"antd": {
"command": "antd",
"args": ["mcp", "--version", "5.20.0"]
}
}
}
이는 MCP 프로토콜을 통해 8개의 도구(antd_list, antd_info, antd_doc, antd_demo, antd_token, antd_design_md, antd_semantic, antd_changelog)와 2개의 프롬프트(antd-expert, antd-page-generator)를 제공합니다.
글로벌 플래그
| 플래그 | 목적 |
|---|---|
--format <format> | 출력 형식: json, text 또는 markdown (에이전트는 json을 선호해야 함) |
--version <v> | 특정 antd 버전 대상 지정 (예: 5.20.0) |
--lang zh | 중국어 출력 (기본값: en) |
--detail | 추가 필드 포함 (설명, 이후 버전, 더 이상 사용되지 않음, FAQ) |
-V, --cli-version | CLI 버전 출력 및 종료 |
핵심 규칙
- 작성 전에 항상 쿼리하십시오 — antd API를 기억에서 추측하지 마십시오. 먼저
antd info를 실행하십시오. - 사용자 버전과 일치시키십시오 — 지식 쿼리(
list/info/doc/demo/token/semantic/changelog)는 antd v4+를 지원합니다. 프로젝트가 antd 4.x/5.x/6.x를 사용하는 경우--version 4.24.0/5.24.0/6.x를 전달하십시오. antd v3 프로젝트의 경우 먼저antd migrate 3 4를 사용하십시오. --format json을 사용하십시오 — 모든 명령어가 이를 지원합니다. 텍스트 출력을 정규식으로 매칭하는 대신 JSON 출력을 구문 분석하십시오.- 마이그레이션을 제안하기 전에 확인하십시오 — 버전 업그레이드에 대해 조언하기 전에
antd changelog <v1> <v2>및antd migrate를 실행하십시오. - 변경 후 린트하십시오 — antd 코드를 작성하거나 수정한 후, 변경된 파일에 대해
antd lint를 실행하여 더 이상 사용되지 않거나 문제가 있는 사용법을 찾으십시오. - antd 버그 보고 — 사용자가 antd 버그를 보고하도록 요청할 때
antd bug를 사용하십시오. 항상 먼저 미리보고 사용자 확인을 받은 후 제출하십시오. - CLI 문제 보고 — 사용자가 CLI 문제에 대해 물을 때
antd bug-cli를 사용하여 보고서를 제출하도록 도우십시오. 항상 먼저 미리보고 사용자 확인을 받은 후 제출하십시오.