디자인을 코드로.
Builder 사용 가이드.

설치와 첫 실행

확장 설치 → Claude CLI 설치 → 계정 로그인 → Builder 연결 순서로 준비합니다. 이미 Claude를 사용하고 있다면 설치·로그인 확인부터 시작하세요.

설치

설치할 에디터 선택

Builder 는 VS Code 계열 에디터에서 동작합니다. 에디터마다 따로 받을 것 없이 같은 .vsix 파일 하나를 씁니다. 설치 경로와 단축키도 모두 같습니다.

설치 절차

1. 확장 패널(Cmd+Shift+X) 우측 상단 … → Install from VSIX… → 배포받은 .vsix 파일 선택 — Cursor · Antigravity 도 같은 위치입니다
2. 에디터를 완전히 종료했다 다시 엽니다. 창만 새로고침하면 확장이 절반만 로드될 수 있습니다 (Cmd+Q 후 재실행)
3. 좌측 활동 표시줄 또는 우측 상단에 주황색 N 아이콘이 보이면 설치 완료

Claude 설치와 로그인

Builder는 컴퓨터에 설치된 Claude Code CLI를 실행합니다. CLI는 터미널에서 명령으로 사용하는 도구입니다. Claude 웹사이트나 에디터의 Claude 확장에 로그인했더라도 아래 CLI 설치와 로그인을 확인하세요.

사용할 Claude 계정 준비

Claude 공식 사이트에서 사용할 계정과 Claude Code 이용 권한을 확인합니다. 조직 계정이라면 초대와 이용 권한을 먼저 확인하세요. 개인 구독·조직 계정·Console 인증의 차이는 공식 인증 안내를 참고하세요.

macOS에 Claude CLI 설치

입력 위치 · Mac의 터미널 앱

1. Cmd + Space를 누르고 터미널을 검색해 엽니다.
2. 아래 명령을 복사해 붙여넣고 Enter를 누릅니다. 공식 설치 프로그램을 내려받아 실행합니다.

curl -fsSL https://claude.ai/install.sh | bash

설치가 끝나면 터미널 창을 새로 열고 설치·로그인 확인으로 이어갑니다. 에디터도 완전히 종료했다 다시 열어 설치된 CLI를 찾을 수 있게 합니다.

Windows에 Claude CLI 설치

입력 위치 · Windows PowerShell

1. 시작 메뉴에서 PowerShell을 검색해 엽니다.
2. 입력 줄이 PS C:\…>로 시작하는지 확인하고 아래 명령을 실행합니다.

irm https://claude.ai/install.ps1 | iex

설치 후 PowerShell과 에디터를 닫았다 다시 열고 아래 단계를 진행합니다. irm을 인식하지 못하면 CMD 창인지 확인하고 PowerShell에서 다시 실행하세요.

설치 기준 · Claude Code 공식 설치 안내 · 2026.09.23 확인

설치 · 로그인 확인

새로 연 터미널 또는 PowerShell에서 버전을 확인합니다.

claude --version

버전이 표시되면 로그인 명령을 실행하고, 열린 브라우저에서 사용할 계정으로 연결을 완료합니다.

claude auth login

브라우저에서 연결을 마쳤다면 터미널로 돌아와 로그인 상태를 확인합니다. 이미 로그인한 경우에도 이 명령으로 확인할 수 있습니다.

claude auth status

완료 확인 결과에 "loggedIn": true가 표시되고 계정 정보가 맞으면 Builder 연결 확인으로 이동합니다. false라면 로그인 단계를 다시 진행하세요.

명령어 기준 · Claude Code 공식 CLI 명령어 · 2026.09.23 확인

AI 계정 연동 필수

Builder 는 각자의 AI 계정으로 실행됩니다. 공용 API 키를 쓰지 않으므로 최초 1회 로그인이 필요합니다.

1. 패널을 엽니다 (Cmd+Shift+A)
2. 패널 상단의 연동 배지를 확인합니다 — claude ✓ 는 연동됨, codex ! 는 미연동입니다
3. 미연동 배지를 클릭하면 터미널이 열리며 로그인 절차가 시작됩니다 (Claude 는 claude /login, Codex 는 codex login)
4. 로그인을 마치고 패널로 돌아오면 배지가 ✓ 로 바뀝니다

명령 팔레트에서 NEXTLAB Builder: 계정 연동 으로도 같은 절차를 실행할 수 있습니다. 두 Provider 를 모두 연동해 두면 작업 성격에 따라 클릭으로 전환할 수 있습니다.

완료 확인 패널 옵션의 Provider를 Claude로 선택하고 claude ✓ 배지를 확인합니다. Codex를 사용할 때는 Codex CLI를 별도로 설치하고 계정을 연결합니다.

Claude 연결이 안 될 때

which claude

(Get-Command claude).Source

설치 상태를 더 확인하려면 터미널에서 claude doctor를 실행합니다. 다른 설정은 전체 설정, 작업 중 오류는 문제 해결을 참고하세요.

패널 열기 — 세 가지 경로

패널 각부

• 상단 배지 — Provider 별 연동 상태. 클릭하면 로그인 안내로 이어집니다
• 작업 선택 — 무엇을 시킬지 먼저 고릅니다. 선택에 따라 아래 입력 영역이 바뀝니다
• 옵션 줄 — Provider · 강도 · 권한 · 모델 · 검증 루프 (6.1 참조)
• 상태줄 — 하네스 21개 (내장 21 · Next 트랙) 처럼 지금 대화에 주입되는 표준의 개수와 판별된 트랙을 표시합니다
• 입력창 — @ 로 파일 첨부, / 로 명령 팔레트, Enter 전송, Shift+Enter 줄바꿈

Figma → Code

Figma 디자인 링크 하나로 한화 DS 스타일 React 코드를 생성합니다. 스크린샷을 보고 추측하는 방식이 아니라, Figma Dev Mode MCP 로 실제 색·간격·구조·변수를 읽어 변환합니다. 그래서 최초 1회 MCP 연결이 필요하고, 매번 node-id 가 포함된 링크가 필요합니다.

전체 흐름 한눈에

Figma 연결하기

Builder 가 Figma 를 읽으려면 두 가지가 연결되어야 합니다. (A) Figma 데스크톱 앱의 MCP 서버를 켜는 일은 사람이 해야 하고, (B) AI CLI 에 그 서버를 등록하는 일은 확장이 자동으로 합니다.

셋업은 최초 1회면 되지만, Figma 앱을 껐다 켠 뒤에는 (A) 의 MCP 서버가 다시 꺼져 있을 수 있습니다. Figma → Code 실행 직전에 확장이 서버 생존을 빠르게 다시 확인하고, 꺼져 있으면 알려 줍니다.

디자인 링크 복사하기

Builder 는 링크에 담긴 node-id 로 "어느 프레임을 그릴지" 를 판단합니다. 파일 주소만 있고 node-id 가 없으면 엉뚱한 화면이 생성되거나 생성이 중단됩니다.

1. Figma 에서 코드로 만들 프레임(화면 단위)을 선택합니다
2. 우클릭 → Copy link to selection 을 선택합니다 (상단 Share 버튼의 링크 복사와 다릅니다 — 그쪽은 node-id 가 없을 수 있습니다)
3. 복사된 주소에 ?node-id=… 가 포함되어 있는지 눈으로 확인합니다

# 올바른 링크 — node-id 포함
https://www.figma.com/design/<fileKey>/파일이름?node-id=684-16571&m=dev

# 잘못된 링크 — 파일만 가리킴 (어떤 프레임인지 알 수 없음)
https://www.figma.com/design/<fileKey>/파일이름

생성할 화면 지정하기

패널 상단 작업 선택에서 Figma to Code 를 고르면 전용 입력 영역이 나타납니다. 단축키 Cmd+Alt+F 또는 입력창에 /figma 로도 전환됩니다.

입력을 마치고 코드 생성을 누르면 나머지는 도구가 이어갑니다. 생성에는 한화 개발표준 + 선택한 킷의 매핑 규칙 + 동봉 아이콘 415종 + 한화 폰트·테마가 자동으로 얹힙니다.

코드 생성 진행하기

• 요청 요약 카드 — 컴포넌트명 · UI 킷 · Figma node · 출력 폴더까지, 무엇이 실행되는지 먼저 보여줍니다
• 진행 로그 — 선택한 모델과 도구 호출 단위 진행 상황, 경과 시간이 그대로 보입니다
• 중지 — Cmd+Alt+S 또는 중지 버튼으로 언제든 멈출 수 있습니다

입력부터 검증 통과까지 보통 5~10분입니다. 화면이 복잡해져도 생성 시간은 크게 늘지 않습니다. 출력이 멈춘 채 일정 시간(기본 3분)이 지나면 무응답으로 보고 자동 중지합니다 — 긴 생성은 출력이 계속되므로 영향받지 않습니다.

검증 결과 확인하기

생성 직후 세 겹의 검증이 순서대로 동작합니다. 앞의 둘은 기본으로 켜져 있습니다.

3

검증 루프 (선택)

기본 꺼짐 — 패널 옵션에서 켜기 로 전환

정밀도를 끝까지 밀어붙일 때 켭니다. 매 반복마다 Playwright 실제 렌더 · 디자인 규칙 · 시각 대조 3종으로 채점하고, 모든 검증 항목이 통과하고 시각 점수가 게이트에 도달할 때까지 보정을 반복합니다. 최고점 산출물이 최종본이 됩니다.

기준	기본값	의미
최대 반복	3회	게이트 미달이어도 이 횟수에서 멈추고 최고점 산출물 복원
시각 게이트	90점	이 점수 이상이면 통과 (룰 점수는 진단용, 게이트에서 제외)
시간 예산	15분	루프 전체 누적 기준. 0 이면 반복 횟수로만 제한

언제 켜나

간단한 폼·목록은 끄기로 충분합니다. 시안과 픽셀 단위로 맞춰야 하는 화면, 또는 결과를 그대로 리뷰에 올려야 할 때 켜기를 쓰세요. 반복하는 만큼 시간과 토큰을 더 씁니다.

미리보기 확인하기

• 렌더 미리보기 — 통과 직후 방금 만들어진 화면의 실제 스크린샷이 채팅에 바로 임베드됩니다. 파일을 열지 않고 눈으로 확인합니다
• Storybook 미리보기 — Storybook 으로 미리볼까요? 알림에서 원클릭. 한화 폰트·테마로 light/dark 를 모두 확인할 수 있습니다 (명령: NEXTLAB Builder: Storybook 미리보기, 슬래시: /preview)
• 산출물 위치 — .nextlab/generated/<컴포넌트명>/ 에 생성됩니다. 결과 카드에서 복사 · 새 파일로 열기 · 재생성 · 프로젝트 적용으로 바로 이어집니다

원본 (Figma)	생성 결과 (Storybook)

다크 모드를 따로 만들지 않아도 됩니다 — 테마 토큰 기반이라 Storybook 툴바 토글 한 번으로 Dark 와 Light 가 모두 나옵니다.

생성된 화면 수정하기

결과가 대체로 맞는데 일부만 어긋났다면, 재생성하지 말고 리터치로 고치는 편이 빠릅니다. Figma 입력 영역의 리터치 버튼 또는 슬래시 명령 /retouch 로 실행합니다.

# 리터치 지시 예시
카드 사이 여백을 24px 로 좁혀줘
결재선 영역 제목을 16px 볼드로 바꿔줘
하단 버튼을 오른쪽 정렬로 옮겨줘

프로젝트에 적용하기

검수를 마쳤으면 NEXTLAB Builder: 산출물 적용 (프로젝트로 복사) 를 실행합니다. 생성 폴더의 결과물이 프로젝트 안으로 복사되며, 컴포넌트별 하위 폴더로 정리됩니다.

어떤 UI 킷으로 생성했든 적용 대상은 한 곳으로 모이므로 결과물이 흩어지지 않습니다. 쌓인 생성물은 NEXTLAB Builder: 생성 산출물 정리 로 비울 수 있습니다.

Figma → Code 체크리스트

• Figma 데스크톱 앱이 켜져 있고, 대상 파일이 열려 있다
• Dev Mode 의 MCP server 가 Enable 되어 있다
• 환경 셋업에서 figma MCP 등록 이 ✓ 였다
• 링크에 node-id 가 포함되어 있다
• 화면 성격에 맞는 UI 킷을 골랐다 (MUI / DS2 / DS3)
• 결과를 미리보기로 눈으로 확인했다

AI 채팅 · 인라인 편집

어느 AI 를 고르든 한화 개발표준이 자동으로 주입됩니다. 표준에 어긋나는 요청은 실행되지 않고, 규칙 번호와 함께 대안으로 대체됩니다.

채팅 기본

• 파일 첨부 — 입력창에서 @ 를 치면 워크스페이스 파일 검색이 열립니다. 📎 버튼으로 파일·이미지도 첨부할 수 있습니다
• 선택 코드 첨부 — 에디터에서 코드를 선택하고 Cmd+I
• 슬래시 명령 — 줄 맨 앞에서 / 를 치면 내장 명령 목록이 열립니다 (6.4 참조)
• 입력창 포커스 — 어디서든 Cmd+L

인라인 편집 — Cmd+Alt+K

에디터를 떠나지 않고 선택한 코드를 자연어로 고칩니다. 적용 전에 diff 로 확인합니다.

1. 지시

위반이 있는 코드를 선택하고 Cmd+Alt+K → NXL 표준에 맞게 리팩터링해줘 한 줄이면 됩니다.

2. 제안 — 적용 전에 diff 로

원본과 AI 제안을 나란히 비교합니다. any · as 단언 · var 가 unknown + 타입 가드 구조로 바뀐 것이 한눈에 보입니다.

변경 내용 적용하기

진단 경고가 모두 사라지고, 반환 타입까지 명시된 표준 코드만 남습니다.

AI Quick Fix

표준 위반 진단에 커서를 두고 전구 아이콘(Cmd+.)을 클릭하면 AI 가 그 규칙에 맞게 그 자리에서 수정합니다. 진단이 무엇을, 왜, 대신 무엇을 쓰라는지 함께 알려주므로 규칙을 외울 필요가 없습니다.

그 밖의 생성 기능

코드 리뷰 · 커밋

코드 리뷰 — Cmd+Alt+R

현재 변경사항(git diff)을 한화 개발표준 기준으로 점검합니다. 지적은 규칙 번호와 파일:라인으로 근거를 남기므로, 리뷰어와의 논쟁이 아니라 확인 작업이 됩니다. 커밋 전에 한 번 돌리면 리뷰 반려를 크게 줄일 수 있습니다.

커밋 생성 — Cmd+Alt+C

변경 내용을 분석해 표준 형식의 커밋 메시지를 작성하고, 확인 후 실제 커밋까지 진행합니다. diff 가 크면 반복되는 잡음 줄(타임스탬프·해시·로그)을 [xN] 으로 접어 토큰을 아낍니다 (nxlCode.optimizePromptTokens, 기본 켜짐 — 코드 본문은 손대지 않습니다).

개발표준과 보안 점검

이 장의 기능은 따로 실행하지 않아도 항상 켜져 있습니다. 무엇이 자동으로 지켜지는지만 알아 두면 됩니다.

실시간 표준 진단 — 18개 규칙

AI 가 짠 코드든 사람이 짠 코드든, .ts · .tsx 를 편집·저장하는 즉시 위반을 표시합니다 (nxlCode.liveDiagnostics).

민감정보 전송 차단 — 8종

입력창의 내용과 첨부 파일 본문을 전송 직전에 검사합니다. 검사는 PC 안에서 끝나므로 민감정보가 AI 서버에 도달하지 않습니다 (nxlCode.security.enabled).

차단되면 해당 값을 제거하거나 마스킹한 뒤 다시 보내면 됩니다.

개발표준 하네스 — 21개 모듈

• 자동 주입 — 작업 성격에 맞는 모듈을 골라 AI 프롬프트에 강제합니다. 채팅·생성·리뷰 어디서나, 어느 Provider 를 골라도 동일합니다
• 트랙 자동 감지 — 워크스페이스의 package.json 에 next 가 있으면 Next 트랙, vite 면 Vite 트랙으로 판정해 해당 규칙만 적용합니다. 감지가 틀릴 때만 nxlCode.stack 으로 고정하세요
• 팀 커스터마이징 — NEXTLAB Builder: 하네스 초기화 로 .nextlab/harness 를 만들면 팀 규칙을 문서로 관리할 수 있습니다. 문서를 고치면 다음 실행부터 전원에게 반영됩니다
• 보안 잠금 — 절대금지·보안 모듈은 워크스페이스 하네스로 대체할 수 없습니다. 로컬 파일로 보안 정책을 무력화하는 우회가 차단됩니다

옵션과 설정

기본값 그대로 써도 됩니다. 이 장은 바꾸고 싶어졌을 때 찾아보는 참조 문서입니다.

패널 옵션 — 대화마다 바꾸는 것

설정 전체 — settings.json

VS Code 설정에서 nxlCode 로 검색하면 모두 보입니다. 아래는 실제로 손댈 일이 있는 것들만 목적별로 묶은 것입니다.

생성 · 검증

Figma · 미리보기

AI · 실행

표준 · 보안 · 환경

단축키

슬래시 명령과 명령 팔레트

입력창 슬래시 명령 — 줄 맨 앞에서 /

명령 팔레트 — Cmd+Shift+P → NEXTLAB

문제 해결