--- title: "AI 개발 Skill — zenit Zig UI 문서" description: "Claude Code 등 AI Agent를 위한 개발 매뉴얼입니다. 설치하면 Agent가 zenit UI를 작성할 때 기존 컴포넌트를 먼저 고르고, toke…" url: https://zenit.z.express/ko/docs/guide/ai-skill language: ko alternate_en: https://zenit.z.express/docs/guide/ai-skill.md alternate_zh: https://zenit.z.express/zh/docs/guide/ai-skill.md alternate_es: https://zenit.z.express/es/docs/guide/ai-skill.md alternate_ja: https://zenit.z.express/ja/docs/guide/ai-skill.md alternate_fr: https://zenit.z.express/fr/docs/guide/ai-skill.md alternate_de: https://zenit.z.express/de/docs/guide/ai-skill.md project: zenit v0.1.0-alpha (Zig 0.15.2, macOS) source: https://github.com/version-next/zenit --- # zenit UI dev Skill Claude Code 등 AI Agent를 위한 개발 매뉴얼입니다. 설치하면 Agent가 zenit UI를 작성할 때 기존 컴포넌트를 먼저 고르고, token과 recipe로 스타일을 지정하며, zenit의 생명주기에 맞춰 상태를 관리하고, 넘기기 전에 직접 빌드하고 스크린샷으로 확인합니다. ## 다운로드 압축 파일은 표준 Agent Skill 폴더입니다. 진입점인 `SKILL.md`는 짧게 규칙과 결정 표만 담고, 세부 내용은 `references/`에 나뉘어 있어 Agent가 필요할 때만 읽으므로 컨텍스트를 차지하지 않습니다. [Skill 다운로드.zip · 54 KB](https://zenit.z.express/downloads/zenit-ui-dev.zip)[SKILL.md 보기](https://zenit.z.express/downloads/zenit-ui-dev.SKILL.md) zenit-ui-dev/ SKILL.md9.6 KB references/ app-architecture.md7.2 KB components.md8.3 KB macos-native.md8.2 KB pencil-design.md7.9 KB performance.md4.1 KB pitfalls.md8.5 KB project-setup.md8.1 KB state-reactivity.md7.8 KB styling.md5.8 KB ui-tree-layout.md6.1 KB verification.md5.7 KB tools/ design\_diff.ts20.6 KB png.ts3.6 KB shot.ts3.7 KB ## 설치 1. **Skill 폴더에 넣기** 개인용이면 `~/.claude/skills/`에 두면 모든 프로젝트에 적용됩니다. 팀 공유라면 저장소의 `.claude/skills/`에 커밋하면 클론하는 모두가 받게 됩니다. 2. **Agent 세션 재시작** Claude Code는 세션 시작 시 Skill을 스캔합니다. 새 세션을 열고 `/skills`에 `zenit-ui-dev`가 보이면 설치된 것입니다. 3. **평소처럼 요청하기** zenit UI 관련 작업이면 자동으로 로드됩니다. “zenit-ui-dev skill을 사용해”라고 명시해도 됩니다. 다운로드한 뒤 사용자 폴더에 압축을 풉니다 (모든 프로젝트에 적용): 압축 해제 위치 ```zig ~/.claude/skills/ └── zenit-ui-dev/ ├── SKILL.md ├── references/ └── tools/ ``` 또는 프로젝트에 압축을 풀고 커밋합니다 (팀과 공유): 압축 해제 위치 ```zig .claude/skills/ └── zenit-ui-dev/ ├── SKILL.md ├── references/ └── tools/ ``` ```sh # Codex and other agents that read AGENTS.md: unpack into the repo and reference it unzip -oq zenit-ui-dev.zip -d .agents/skills echo '- zenit UI: read .agents/skills/zenit-ui-dev/SKILL.md before writing UI code' >> AGENTS.md ``` > NOTE > > **zenit과 함께 업데이트하십시오.** zenit은 1.0 이전까지 API가 깨질 수 있습니다. zenit을 업그레이드한 뒤에는 이 Skill을 다시 받아 기존 폴더를 덮어쓰십시오. Skill에는 대상 zenit 버전이 적혀 있으며, Agent는 프로젝트의 API와 다른 점을 발견하면 소스 코드를 기준으로 삼습니다. ## 구성 내용 | 파일 | 내용 | | --- | --- | | `SKILL.md` | 진입점: 트리거 조건, 워크플로, 필수 규칙, 결정 표, 그리고 언제 어떤 reference를 읽을지 | | `references/app-architecture.md` | 프로덕션 에디터를 예로 든 대규모 앱 계층: 상태, 뷰, 명령, 서비스 | | `references/components.md` | ui.widgets 카탈로그, 두 가지 mount 형태, “디자인 요소 → 컴포넌트” 선택 표 | | `references/macos-native.md` | 메뉴, 단축키, 파일 대화상자, 클립보드, 드래그 앤 드롭, 멀티 창, IME | | `references/pencil-design.md` | Pencil (pen.dev) 디자인 재현: MCP로 수치 읽기, 필드 매핑, 스크린샷 수치 비교 | | `references/performance.md` | 가상 리스트, dirty 레벨, 대용량 텍스트, 백그라운드 스레드와 메인 스레드 통신 | | `references/pitfalls.md` | zenit과 프로덕션 앱 수정 기록에서 모은 “증상 → 원인 → 올바른 해결” | | `references/project-setup.md` | 새 프로젝트, build.zig / build.zig.zon, .app 패키징, 빌드 옵션 전달 | | `references/state-reactivity.md` | bindState / cx.on, Signal / Memo / Effect, Scope 생명주기와 정리 | | `references/styling.md` | Token → styles.zig → recipe 3계층, 테마, ui.arb 탈출구 | | `references/ui-tree-layout.md` | 노드, Flex 레이아웃, 크기, 노드 업데이트, 표시 여부, 좌표 | | `references/verification.md` | Agent 자체 검증 루프: 빌드, 스크린샷, E2E harness, DevTools, 로그 | | `tools/design_diff.ts` | 디자인 PNG와 앱 스크린샷의 수치 비교, 실행 가능한 수정 힌트 출력 | | `tools/png.ts` | design\_diff가 사용하는 무의존성 PNG 디코더 | | `tools/shot.ts` | 파일 RPC로 모든 zenit 앱 스크린샷 (Retina) | **직접 만들기 전에 컴포넌트부터** 디자인의 각 요소를 ui.widgets의 기존 컴포넌트에 매핑해, Agent가 box로 Button을 다시 조립하지 않게 합니다. **생명주기를 올바르게** bindState, pub deinit, Scope 정리, 페이지 전환 규칙으로 가장 흔한 누수, 이중 해제, 댕글링 포인터를 바로 해결합니다. **넘기기 전에 직접 확인** Agent가 빌드, 실행, 스크린샷 후 요청 사항과 대조하게 하며, “컴파일된다”에서 멈추지 않게 합니다. **실제 프로젝트의 함정** 실제 프로덕션 앱의 수정 기록에서 정리한 문제 목록으로, 각 항목에 원인과 올바른 해결 방법이 있습니다. ## 추천: Pencil로 디자인 [Pencilpen.dev](https://www.pen.dev/) 추천 워크플로 · PENCIL + SKILL Pencil과 함께: 디자인하고 AI로 구현 [Pencil](https://www.pen.dev/)로 화면을 그리고, 이 Skill로 에이전트가 구현하게 하는 방식을 추천합니다. .pen 파일의 Flex 레이아웃, 간격, 모서리 반경, 글자 크기, lucide 아이콘은 zenit의 모델과 매우 가깝습니다. Skill에는 필드 매핑표와 design\_diff 비교 도구가 들어 있어 에이전트가 감이 아닌 수치로 옮깁니다. [Pencil 알아보기](https://www.pen.dev/) 1. 01.penPencil 디자인 2. 02MCP에이전트가 정확한 수치를 읽음 3. 03zigwidgets + token으로 zenit 코드 4. 04diff디자인과 수치 비교 1. **Pencil MCP 연결** Agent에서 Pencil의 MCP server를 활성화하고 .pen 파일을 엽니다. Skill은 .pen을 MCP로만 읽습니다. MCP는 디자인 변수를 풀고 계산된 실제 크기를 제공하는데, 이 두 가지가 충실한 재현에 가장 필요합니다. 2. **픽셀이 아니라 수치 읽기** Agent는 먼저 `Get(nodeId, { resolveVariables: true })`로 gap, padding, 모서리 반경, 글자 크기, 색상을 가져온 뒤 매핑 표에 따라 zenit으로 옮깁니다: `fill_container → .fill()`, `chevron-down → ui.icons.chevron_down`. 3. **일치할 때까지 수치 비교** 디자인을 scale 2로 내보내고 `tools/shot.ts`로 실제 창을 캡처하면, `tools/design_diff.ts`가 위치 차이, 크기 차이, 히트맵, 색상 편차를 보고하고 Agent가 힌트대로 수정합니다. 한 라운드에 약 5초입니다. ```sh SKILL=~/.claude/skills/zenit-ui-dev bun $SKILL/tools/design_diff.ts --self-test ZENIT_E2E_FILE_RPC_DIR=$RPCDIR bun $SKILL/tools/shot.ts /tmp/actual.png bun $SKILL/tools/design_diff.ts /tmp/design/.png /tmp/actual.png ``` ## 사용법 특별한 문법은 필요 없습니다. 원하는 UI나 문제를 설명하면 됩니다. 효과가 좋은 프롬프트 몇 가지를 소개합니다: ``` Pencil MCP로 열려 있는 .pen의 "Settings" 프레임을 읽어 zenit으로 설정 창을 재현하고, design_diff 점수가 90을 넘으면 넘겨 주세요. zenit으로 이 앱에 설정 창을 추가해 주세요. 왼쪽은 카테고리 목록, 오른쪽은 폼이고 변경 사항은 즉시 반영됩니다. src/views/sidebar.zig에 직접 작성된 스타일을 styles.zig + recipe로 옮겨 주세요. 파일 트리가 5만 노드일 때 스크롤이 끊깁니다. 원인을 찾아 고치고, 수정 후 스크린샷을 보여 주세요. ``` > TIP > > **검증 방법을 알려 주십시오.** 요청에 “스크린샷 보여 줘”나 “E2E로 검증해”를 덧붙이면 Agent가 Skill의 자체 검증 루프를 따르므로, 실제로 확인을 거친 결과를 받게 됩니다. ## 내용 출처 Skill의 규칙은 두 프로젝트에서 나왔습니다. zenit 프레임워크 자체(공개 API, 예제, 컴포넌트 카탈로그, 테스트 도구)와 zenit으로 만든 프로덕션 macOS 에디터(대규모 앱 계층화, 네이티브 통합, 수정 기록)입니다. 예제 코드는 가능한 한 두 저장소에서 컴파일되는 코드에서 가져왔으며 이 매뉴얼과 일치합니다. 소스는 사이트 저장소의 `skill/zenit-ui-dev/`에 있으며, 빌드 시 `scripts/pack-skill.mjs`로 패키징됩니다. [SKILL.md를 직접 읽을](https://zenit.z.express/downloads/zenit-ui-dev.SKILL.md) 수도 있습니다.