AI 에이전트용 디자인 도구를 만들고 명령과 검사를 정리하기

## 디자인 명령을 하나의 스킬로 묶고 명령마다 자료 파일 하나를 정하기 사용자 대상 명령 표면을 간결하게 유지하면서 일치하는 각 명령을 범위가 명확한 참조 자료로 라우팅하라. 통합하면 메뉴의 혼잡을 줄이고 공유 디자인 원칙을 더 쉽게 유지할 수 있다. ### 명령 아키텍처 - 별도의 수명 주기가 실제로 필요하지 않다면 여러 독립 스킬보다 하위 명령을 갖춘 하나의 사용자 호출 가능 디자인 스킬을 선호하라. - 각 명령을 참조 파일에 매핑하는 단일 라우터 표를 유지하라. - 빌드 및 바로가기 생성기가 사용하는 권위 있는 메타데이터에 명령 설명, 인수 힌트, 카테고리, 관계를 유지하라. - 제공자별 사본을 각각 편집하지 말고 하나의 원본에서 제공자별 스킬 파일을 생성하라. - 가벼운 바로가기는 정식 명령으로 연결하는 리디렉션으로만 사용하라. - 공유 원칙은 공통 원본에, 명령별 결정은 관련 참조에 배치하라. 공유 지침을 복제하지 말고 링크하라. ### 컨텍스트 라우팅 - 디자인 성격 구분이나 플랫폼 규칙집을 선택하기 전에 프로젝트 컨텍스트를 읽어라. - 명시적인 프로젝트 필드를 우선하고, 그다음 작업 및 표면 단서를 사용한 뒤, 문서화된 기본값을 적용하라. - 인식할 수 없는 컨텍스트 값에는 관련 없는 규칙집을 알리지 않고 적용하지 말고 경고하라. - 명령의 플랫폼 동작이 크게 다르면 기본 파일 대신 변형 참조를 로드하라. ## 브랜드용인지 앱 화면용인지 먼저 정하고 웹이나 각 OS의 규칙을 더하기 디자인 목적과 제공 플랫폼을 독립적인 축으로 취급하라. 디자인 성격은 경험 목표를 정의하고, 플랫폼은 상호작용 규칙과 구현 제약을 정의한다. ### 디자인 성격 - 디자인 자체가 제품인 마케팅, 캠페인, 포트폴리오, 편집 경험, 차별화된 공개 표면에는 브랜드 성격을 사용하라. - 하나의 유행하는 스타일을 강요하지 말고 여러 시각적 방향에서 드러나는 차별성으로 브랜드 작업을 평가하라. - 디자인이 애플리케이션, 대시보드, 관리자 표면 또는 도구를 지원하는 경우 제품 성격을 사용하라. - 숙련된 사용자가 쌓아 온 익숙함, 신뢰, 능숙함을 기준으로 제품 작업을 평가하라. - 디자인 성격은 이후의 디자인 결정을 바꾸므로 초기에 확인하라. ### 플랫폼 - 반응형 웹, 단일 네이티브 플랫폼, 적응형 크로스 플랫폼 제공을 구분하라. - 플랫폼을 디자인 목적의 대체물로 취급하지 말고, 선택한 디자인 성격 위에 네이티브 플랫폼 지침을 더하라. - 적응형 제품에는 두 네이티브 규칙집을 모두 적용하고 운영체제별로 조정하라. 모든 플랫폼에 동일한 시각 처리를 적용하는 것은 적응형이 아니다. - 원본 파일이 웹과 비슷한 확장자를 사용하더라도 네이티브 프로젝트에서는 브라우저 오버레이, HTML 감지기, 실시간 웹 훅을 비활성화하라. - 접근성 검증은 전용 감사 경로에 유지하라. 안전하지만 디자인이 부족한 작업을 만들 수 있다면 창의적 생성 중에 일반적인 접근성 알림을 반복해서 주입하지 마라. ## 색 사용 규칙과 공개 글의 금지 표현 목록 지키기 시각 토큰, 레이아웃 코드, 편집 문체, 게시 콘텐츠에는 명시적인 소유자와 자동 검사가 필요하지만, 사람의 디자인 판단을 대체해서는 안 된다. ### 시각적 기반 - 하나의 진입점, 공유 토큰, 범위가 명확한 부분 파일로 구성된 작고 검사 가능한 스타일링 아키텍처를 선호하라. - 의미론적 색상 토큰을 일관되게 사용하라. 본문에는 대비가 가장 높은 잉크 색상을, 크기가 뒷받침하는 곳에만 더 부드러운 어두운 색조를, 보조 레이블에는 차분한 색조를 사용하라. - 시각 시스템이 색조가 들어간 양극단 색상을 정의한다면 순수한 검정과 순수한 흰색을 피하라. - 구현 규칙을 규칙이 적용되는 표면 가까이에 두고, 지원되는 경우 핫 리로드 동작을 유지하라. ### 편집 원칙 - 공개 문구, 튜토리얼, 문서 또는 마케팅 페이지를 변경하기 전에 프로젝트의 편집 개요를 읽어라. - 과도하게 사용된 문구, 문장 부호, AI 같은 산문 패턴에 대해 문서화된 금지 목록을 적용하라. - 철자 기법으로 산문 검증기를 회피하지 마라. 금지된 용어에 필요한 기술적 의미가 있다면 스타일 가이드 수정을 제안하라. - 정규식으로 판단할 수 없는 공허한 확신, 반복적인 리듬, 자동적인 삼단 구성, 공식적인 대조 전환 같은 구조적 문제를 검토하라. - 각 편집 항목을 빌드 도구와 렌더링 프레임워크가 함께 사용하는 단일 콘텐츠 트리에 유지하라. - 명령 편집 항목에는 짧은 레이블과 사용 사례, 절차, 구체적인 예제, 실제 함정에 관한 섹션을 제공하라. ## 자동으로 만들어진 파일을 평소 디자인 변경에 섞지 않기 작성 원본, 생성 배포물, 로컬 상태, 릴리스 출력을 분리하여 일반 디자인 작업이 불필요하거나 오해를 부르는 산출물을 만들지 않게 하라. ### 원본 우선 빌드 - 일반 개발에는 원본 우선 빌드를 사용하고, 추적되는 제공자별 배포물을 동기화해야 할 때는 별도의 릴리스 빌드를 사용하라. - 생성된 제공자 디렉터리는 설치를 위해 의도적으로 커밋하더라도 작성 표면이 아닌 배포 산출물로 취급하라. - 작업이 릴리스, 생성 출력 동기화 또는 빌드 시스템 변경이 아니라면 기능 변경에 생성된 조합을 포함하지 마라. - 승인된 절차를 통해 원본 변경 후 추적 출력을 다시 생성하고, 매니페스트, 메타데이터 또는 생성된 프런트매터가 어긋나면 검증을 실패시켜라. - 추적되는 배포 디렉터리 안에 있더라도 로컬 상태 파일은 무시하라. - 콘텐츠 로더나 명령 메타데이터가 핫 리로드되지 않으면 개발 서버를 다시 시작하라. 브라우저 새로고침을 빌드 시점 데이터의 재로드로 착각하지 마라. ### 게시 산출물 - 표시되는 개수와 레이블이 어긋나지 않도록 권위 있는 메타데이터에서 소셜 카드와 유사 산출물을 생성하라. - 선명한 텍스트가 필요하면 더 높은 해상도로 렌더링한 뒤 축소하라. - 눈에 보이는 변경이 있는 산출물에 캐시 무효화가 필요하다면 같은 변경에서 파일 이름과 모든 참조를 업데이트하라. - 플랫폼이 의도한 빌드를 통해 배포 경로, 재작성, 정적 산출물, 서버 함수를 검증하라. - 새 배포가 실제로 서비스된 후에만 외부 미리보기 캐시를 미리 채워라. ## 허락 없이 외부 프로젝트에 올리지 않고 비용이 드는 테스트는 따로 두기 디자인 도구는 구현을 자동화할 수 있지만 명시적인 권한 없이 사람의 기여 경계를 넘어서는 안 된다. ### 기여 권한 - 저장소의 이슈 우선 또는 승인 우선 기여 정책을 따르라. - 권한을 가진 유지관리자가 요청하거나 명확히 승인하지 않았다면 외부 이슈나 풀 리퀘스트를 열지 마라. - 정책에서 요구한다면 커밋, 변경 설명, 댓글, 이슈 본문에 AI 지원을 공개하라. - 권한 없는 AI 에이전트가 게시 요청을 받더라도 외부 작업을 중단하고 대신 로컬 인계 안내를 준비하라. - 일반 기여에는 생성된 릴리스 산출물과 관련 없는 동기화 변경을 포함하지 마라. ### 테스트 선택 - 빠르고 결정론적인 단위 및 픽스처 테스트를 기본 스위트에 유지하라. - 브라우저 기반 전체 주기 테스트, 의존성 설치, 실시간 개발 서버, 유료 모델 호출은 명시적으로 선택하는 명령 뒤에 배치하라. - 비용이 큰 실시간 테스트는 무제한 기본값으로 실행하지 말고, 해당 테스트가 다루는 통합 경로를 변경할 때 실행하라. - 테스트 에이전트를 좁은 인터페이스 뒤에서 교체할 수 있게 하고, 광범위한 픽스처 범위에는 결정론적 대체물을 사용하라. - 동작 평가에서는 세련된 자유 형식 답변이 아니라 도구 호출 추적을 검증하라. - 제공자 간 라우팅이 테스트 대상 동작이라면 여러 모델 계열을 사용하고, 자격 증명이 없을 때는 깔끔하게 건너뛰어라. - 비용과 변동성을 의도한 경우가 아니라면 유료 평가 스위트를 지속적 통합에 포함하지 마라. ## 명령을 추가할 때 모든 목록을 고치고 새 버전 출시는 따로 하기 명령과 독립적으로 배포되는 컴포넌트에는 동기화된 메타데이터가 필요하지만, 기능 작업과 릴리스 작업은 분리해야 한다. ### 명령 추가 또는 변경 - 명령 참조, 라우터 항목, 메뉴 항목, 유효 명령 목록, 메타데이터, 카테고리, 관계, 시각화 매핑을 함께 추가하라. - 사람이 보는 모든 명령 개수를 업데이트하고, 기계 판독 가능한 개수는 빌드가 라우터에서 도출하고 검증하게 하라. - 선택적 편집 콘텐츠와 자동 실행 설명을 분리하라. 전자는 독자를 위해 작성하고 후자는 명령 일치를 위해 작성한다. - 플랫폼별 명령이 크게 다르면 라우팅된 변형을 추가하고 공유 운영체제 세부정보는 플랫폼 참조에 유지하라. ### 버전 및 릴리스 정책 - 일반적인 기능 변경에서 버전을 올리거나 릴리스 노트를 추가하지 마라. - 독립적으로 배포되는 컴포넌트의 버전을 따로 관리하고 변경된 컴포넌트만 업데이트하라. - 릴리스 시 권위 있는 매니페스트와 동기화된 미러를 업데이트하고, 사용자에게 보이는 노트를 추가하고, 릴리스 빌드를 실행한 다음, 컴포넌트별 접두사로 태그하라. - 게시하기 전에 릴리스 자동화를 미리 확인하라. - 작업 트리가 변경된 상태이거나, 브랜치가 동기화되지 않았거나, 태그가 이미 존재하거나, 노트가 누락되었거나, 재생성으로 커밋되지 않은 차이가 생기면 릴리스를 거부하라. - 변경 로그 항목을 간결하고 사용자 중심으로 유지하라. 내부 리팩터링, 도구 세부정보, 생성 출력 동기화는 제외하라. ## 새 디자인 검사를 만들기 전에 실패하는 테스트부터 쓰기 하나의 디자인 감지기가 CLI, 브라우저 오버레이, 확장 기능, 웹사이트를 지원한다면 규칙 엔진에는 단일 원본이 있어야 하며 모든 파생 소비자를 다시 빌드하고 검증해야 한다. ### 규칙 개발 순서 1. 고유하게 식별된 예제를 갖춘 픽스처를 추가하되, 표시되어야 할 사례를 최소 네 개, 거짓 양성 형상을 최소 다섯 개 포함한다. 2. 테스트 DOM에 레이아웃 엔진이 없다면 명시적인 치수를 사용한다. 3. 규칙을 구현하기 전에 범위가 명확한 테스트를 추가하고 실패하는지 확인한다. 4. DOM 접근 없이 안정적인 식별자와 스니펫을 반환하는 규칙 메타데이터와 순수 검사 함수를 추가한다. 5. 브라우저 및 테스트 DOM 어댑터를 별도로 구현한 다음 두 어댑터를 관련된 모든 순회 반복문에 연결한다. 6. 생성된 각 감지 소비자를 다시 빌드하고 전체 테스트 스위트를 실행한다. 7. 브라우저에서 픽스처와 대표적인 실제 페이지를 검증하여 어댑터 불일치와 거짓 양성을 찾아낸다. ### 픽스처 및 평가 원칙 - 테스트가 일치하는 사례를 추출할 수 있도록 스니펫에 안정적인 인용 텍스트나 다른 결정론적 식별자를 사용하라. - DOM 에뮬레이터에서는 레이아웃 기하에 의존하지 말고 명시적인 스타일을 파싱하라. - 브라우저와 에뮬레이터의 동작이 다른 배경, 그라디언트, 색상 정규화에는 공유 도우미를 사용하라. - 디자인 시스템의 효과를 측정할 때는 동일한 개요에서 디자인 시스템을 적용한 결과와 적용하지 않은 결과를 비교하라. - 평가 인프라를 자체 운영 지침과 함께 별도의 작업 공간에 유지하라. - 평가 일괄 실행 전에 최신 디자인 원본을 빌드하고, 최상위 지침 제목이 바뀔 때마다 인라인 스킬 섹션 필터를 업데이트하라.