XStudio Patterns Skill

XStudio Builder 애플리케이션의 코드 패턴, 규칙 및 모범 사례를 정의하는 통합 스킬입니다.

목적

• •코드 일관성 및 품질 보장
• •팀 전체 표준화된 패턴 적용
• •보안, 성능, 접근성 요구사항 충족
• •유지보수성 향상

규칙 카테고리

CRITICAL (즉시 적용 필수)

Domain (domain-*) - 비즈니스 로직

• •domain-element-hierarchy - Element 계층 구조 규칙
• •domain-o1-lookup - O(1) 인덱스 기반 검색
• •domain-history-integration - 히스토리 기록 필수
• •domain-async-pipeline - 비동기 파이프라인 순서
• •domain-layout-resolution - Page/Layout 합성 규칙
• •domain-delta-messaging - Delta 메시징 패턴
• •domain-component-lifecycle - 컴포넌트 생명주기

Validation (validation-*) - 입력 검증/에러 처리

• •validation-input-boundary - 경계 입력 검증 (Zod)
• •validation-error-boundary - Error Boundary 필수

Styling (style-*)

• •style-no-inline-tailwind - 인라인 Tailwind 클래스 금지
• •style-tv-variants - tv() 사용 필수
• •style-react-aria-prefix - react-aria-* CSS 접두사

TypeScript (type-*)

• •type-no-any - any 타입 금지
• •type-explicit-return - 명시적 반환 타입

PIXI Layout (pixi-*)

• •pixi-no-xy-props - x/y props 금지
• •pixi-layout-import-first - @pixi/layout 최우선 import
• •pixi-hybrid-layout-engine - 하이브리드 레이아웃 엔진 display 선택

Security (postmessage-*)

• •postmessage-origin-verify - origin 검증 필수

Component Spec (spec-*)

• •spec-build-sync - @xstudio/specs 빌드 동기화 필수
• •spec-value-sync - Spec ↔ Builder ↔ CSS 값 동기화

HIGH (강력 권장)

Architecture (arch-*)

• •arch-reference-impl - 참조 구현 모음

Component Spec (spec-*)

• •spec-single-source-truth - ComponentSpec 단일 소스 패턴
• •spec-shape-rendering - Shape 기반 렌더링
• •spec-token-usage - 토큰 참조 형식

Styling (style-*)

• •style-css-reuse - CSS 클래스 재사용

React-Aria (react-aria-*)

• •react-aria-hooks-required - React-Aria 훅 사용
• •react-aria-no-manual-aria - 수동 ARIA 속성 금지
• •react-aria-stately-hooks - React-Stately 상태 훅

Supabase (supabase-*)

• •supabase-no-direct-calls - 컴포넌트 직접 호출 금지
• •supabase-service-modules - 서비스 모듈 사용
• •supabase-rls-required - Row Level Security 필수

Zustand (zustand-*)

• •zustand-factory-pattern - StateCreator 팩토리 패턴
• •zustand-modular-files - 슬라이스별 파일 분리

PostMessage (postmessage-*)

• •postmessage-buffer-ready - PREVIEW_READY 버퍼링

Inspector (inspector-*)

• •inspector-inline-styles - 오버레이 인라인 스타일
• •inspector-history-sync - 히스토리 동기화

PIXI Layout (pixi-*)

• •pixi-border-box-model - Border-Box 모델 크기 계산 필수
• •pixi-text-isleaf - Text isLeaf 설정
• •pixi-hitarea-absolute - 히트 영역 absolute 위치
• •pixi-viewport-culling - Viewport Culling 좌표 시스템 및 부모 가시성 패턴

MEDIUM-HIGH

PIXI Layout (pixi-*)

• •pixi-no-flex-height - flex + % height 조합 금지

MEDIUM (권장)

Performance (perf-*)

• •perf-checklist - 성능 체크리스트
• •perf-barrel-imports - Barrel import 지양
• •perf-promise-all - Promise.all 병렬 처리
• •perf-dynamic-imports - 동적 import 활용
• •perf-map-set-lookups - Map/Set O(1) 검색

Testing (test-*)

• •test-stories-required - Storybook 스토리 필수

기술 스택

사용법

# 특정 규칙 적용 예시
# 1. rules/ 폴더에서 관련 규칙 확인
# 2. Incorrect 예시 패턴 검색
# 3. Correct 예시로 수정

규칙 파일 형식

모든 규칙 파일은 Vercel Agent Skills 패턴을 따릅니다:

---
title: 규칙 제목
impact: CRITICAL | HIGH | MEDIUM-HIGH | MEDIUM | LOW
impactDescription: 영향 설명
tags: [tag1, tag2]
---

규칙 설명

## Incorrect
잘못된 코드 예시

## Correct
올바른 코드 예시

아키텍처 결정 기록 (ADR)

주요 기술 결정의 배경과 근거:

• •ADR-001 - Zustand 선택 이유
• •ADR-002 - ITCSS + tv() 선택 이유
• •ADR-003 - PixiJS 선택 이유
• •ADR-004 - iframe 격리 이유
• •Component Spec Architecture - 단일 소스 컴포넌트 스펙 설계
• •Layout Requirements - 하이브리드 레이아웃 엔진 CSS 호환 구현

기여

새 규칙 추가 시:

1. •rules/_template.md 복사
2. •적절한 접두사 사용 (style-, type-, react-aria- 등)
3. •SKILL.md에 규칙 링크 추가
4. •impact 레벨 적절히 설정