speccanvas

speccanvas은(는) 무엇을 하나요?

이 스킬은 Spec Canvas 아티팩트를 휴대용 YAML 스펙으로 제작 및 유지보수하거나, 구성된 SpecCanvas MCP 서버를 통해 지속화하는 데 사용합니다.

스펙을 구조와 의도의 진실 공급원(source of truth)으로 취급하세요. 추가 설명 없이 Spec Canvas, IDE, 터미널 에이전트, 또는 저장소에 붙여넣을 수 있는 간결하고 재사용 가능한 스펙을 선호합니다.

이 스킬의 format-description YAML 파일을 작성 가이드로 사용하세요. 번들된 JSON Schema 복사본과 로컬 검증 로직을 사후 점검(post-check)으로 사용하세요.

핵심 철학

Spec Canvas 스펙은 제품 의도와 구현 사이의 간결한 다리입니다. 코드 변경 전에 에이전트와 인간이 제품의 형태에 동의할 수 있도록 돕지만, 모든 CSS, 레이아웃, 컴포넌트 조정의 실행 기록이 되어서는 안 됩니다.

• UI 스펙은 의도와 구조를 설명합니다. 화면, 주요 블록, 내비게이션, 주요 사용자 작업, 중요한 상태, 의미 있는 반응형 구조를 캡처합니다.
• 데이터 스펙은 논리적 도메인을 설명합니다. 엔티티, 필드, 열거형, 관계, 도메인 제약 조건을 캡처합니다. 물리적 데이터베이스 또는 프레임워크 세부 사항은 피합니다.
• 스펙 우선은 의미론적 변경에 적용됩니다. 요청이 제품 의미, 사용자 여정 또는 도메인 구조를 변경하는 경우 구현 전에 스펙을 업데이트합니다.
• 구현 미세 변경은 스펙을 건너뛸 수 있습니다. 요청이 외관, 레이아웃 전용이거나 사용자에게 보이지 않는 경우 구현을 직접 변경하고 스펙은 그대로 둡니다.
• 간결한 스펙이 더 좋은 스펙입니다. 화면/블록이 존재하는 이유를 설명하는 짧은 목적문을, 어떻게 구축되었는지에 대한 구현 산문보다 선호합니다.

세분성 게이트(Granularity Gate)

UI 스펙을 편집하기 전에, 요청된 변경이 스펙에 포함될 만큼 의미론적인지 판단합니다.

다음과 같은 경우 UI 스펙을 업데이트합니다:

• 화면, 화면 그룹 또는 주요 블록
• 사용자 여정, 내비게이션, 진입점 또는 사용 가능한 액션
• 중요한 사용자 대면 상태, 모드, 권한 또는 빈/오류/복구 흐름
• 주요 컴포넌트의 목적 또는 동작
• 의미 있는 반응형 구조(예: 별도의 데스크톱/모바일 경험)
• 제품 용어 또는 레이블의 의미 변경
• 공개, 관리자, 편집자, 플레이어, 온보딩 또는 유사한 제품 영역 간의 경계

구현 미세 조정에 대해서는 UI 스펙을 업데이트하지 마십시오:

• 간격: 패딩, 마진, 갭, 줄 높이
• 정확한 크기: 픽셀 값, 폰트 크기, 너비/높이(상위 수준 레이아웃 의도를 표현하지 않는 한)
• CSS 클래스, Tailwind 클래스, 컴포넌트 이름, 파일 이름 또는 프레임워크별 구조
• 정확한 색상, 그라데이션, 그림자, 테두리 반경, 아이콘 또는 장식 스타일
• 이미 설명된 블록 내의 로컬 정렬, 순서, 줄바꿈 또는 미용적 재배치
• 애니메이션 타이밍, 디바운스 타이밍, 크로스페이드 시간, 토스트 위치, 로딩 스피너 메커니즘
• 핵심 사용자 대면 기능이 아닌 브라우저/플랫폼 구현 세부 사항
• 의미를 변경하지 않는 로컬 카피 편집
• 사용자에게 보이지 않는 리팩터링

사용자가 미용적 또는 레이아웃 미세 변경을 요청하면 코드 변경을 직접 수행하고 UI 스펙을 건드리지 않습니다.

기본 파일 위치

사용자가 다른 위치를 명시적으로 요청하지 않는 한, Spec Canvas 파일을 프로젝트 루트의 spec/ 아래에 생성하고 업데이트합니다.

• UI 스펙 경로: spec/ui-spec.yaml
• 데이터 스펙 경로: spec/data-spec.yaml

spec/ 디렉토리가 없으면 생성합니다. 하나의 아티팩트만 요청된 경우 관련 파일만 생성합니다.

MCP 모드

사용자가 라이브 SpecCanvas 프로젝트, 문서, 개정판, 구현, 아카이브 작업을 요청하거나 환경에서 MCP 도구를 명확히 사용할 수 있을 때는 speccanvas라는 구성된 MCP 서버를 사용합니다.

• MCP를 사용할 수 있는 경우, 라이브 SpecCanvas 데이터를 생성하거나 업데이트하기 전에 references/mcp-workflow.md를 읽습니다.
• 작업이 UI 스펙을 생성하거나 업데이트하는 경우 references/ui-spec-workflow.md도 읽습니다.
• 작업이 화면 구현을 생성하는 경우 references/implementation-workflow.md도 읽습니다.
• MCP를 사용할 수 없는 경우 연결 세부 정보를 임의로 만들지 마십시오. 휴대용 YAML 파일로 작업하거나 사용자에게 speccanvas MCP 서버를 구성하도록 요청합니다.
• MCP URL, Bearer 토큰, 스테이징 호스트 또는 로컬 비밀을 이 스킬에 저장하지 마십시오. 이러한 정보는 에이전트의 MCP 구성 및 환경 변수에 속합니다.

MCP 모델 ID 규칙

MCP를 통해 에이전트가 작성한 화면 구현을 저장할 때는 항상 안정적인 모델 ID를 { identityKey, provider, model, version } 형식으로 제공합니다.

• 글로벌 에이전트 규칙, 환경 변수 또는 현재 세션에서 활성 모델을 확인한 후 add_implementation을 호출합니다.
• add_implementation의 경우 modelIdentity를 직접 전달합니다. agentName으로 대체하지 마십시오.
• agentName은 수동/레거시 대체 수단입니다. 사람이 구현을 업로드하거나 모델 ID가 의도적으로 제공되지 않는 경우에만 modelIdentity: null과 함께 사용합니다.
• 활성 모델을 알 수 없거나, 모호하거나, 등록되지 않은 경우 중지하고 명확히 설명을 요청합니다. 조용히 agentName으로 저장하지 마십시오.

워크플로우

1. 아티팩트 경계 식별 작업에 필요한 항목을 결정합니다:

   • UI 스펙만
   • 데이터 스펙만
   • 두 스펙 모두
   • 기존 스펙에 대한 설명, 검토, 정리 또는 유효성 검사
   • 요청이 구현 미세 조정이므로 스펙 변경 불필요
   • 프로젝트, 스펙, 개정판, 구현 또는 아카이브의 라이브 MCP 지속화

2. 세분성 게이트 적용 UI 작업의 경우 요청이 제품 의도/구조를 변경하는지 또는 구현 세부 사항만 변경하는지 판단합니다. 미세 조정에 불과하면 스펙을 그대로 둡니다.

3. 소스 자료 수집 구조를 정의하는 입력만 사용합니다:

   • 제품 아이디어 또는 기능 요청
   • 기존 스크린샷 또는 UI 설명
   • 코드베이스 구조
   • 현재 YAML 스펙
   • 엔티티 목록, API 노트 또는 도메인 규칙

4. 필수 워크플로우 및 포맷 참조 읽기

   • UI 스펙 생성 또는 개정: references/ui-spec-workflow.md 읽기
   • 화면 구현 생성: references/implementation-workflow.md 읽기
   • 라이브 MCP 지속화: references/mcp-workflow.md 읽기
   • UI 스펙 작성: references/ui-spec-format-0-0-3.yaml 읽기
   • 데이터 스펙 작성: references/data-spec-format-0-0-1.yaml 읽기
   • 로컬 검증 동작 및 검토 휴리스틱: 필요에 따라 references/workflow.md, references/validation-rules-ui.md, references/validation-rules-data.md 읽기
   • 현재 번들된 스키마는 schemas/ui-spec.schema.json 및 schemas/data-spec.schema.json에 있습니다.

5. 스펙 초안 작성 또는 개정 문서를 유효한 YAML로 유지하고 포맷 필드 내에 머무릅니다. 포맷이 명시적으로 허용하지 않는 한 사용자 정의 최상위 섹션을 만들지 마십시오. 의도를 유지하는 가장 작은 의미론적 업데이트를 수행합니다. 픽셀 수준의 구현 노트로 스펙을 확장하지 마십시오.

6. 결과 검증 scripts/validate-spec.mjs를 사용할 수 있으면 최종 YAML에 대해 실행한 후 결과를 반환합니다. 스펙을 반환하기 전에 검증 오류를 수정합니다.

7. 결과 반환 검증된 YAML을 반환하거나, 검토 작업의 경우 먼저 문제점을 나열하고 그 다음 수정된 조각 또는 파일을 반환합니다.

핵심 규칙

포맷 파일을 작성 소스로 사용

format-description YAML 파일이 이 스킬의 기본 작성 참조입니다. 그 구조, 필드 명명, 예제 및 지침을 먼저 따릅니다. UI 스펙의 경우 references/ui-spec-format-0-0-3.yaml이 현재 로컬 진실 소스이며 번들된 스키마 및 검증기와 일관성을 유지해야 합니다.

스키마 검증을 사후 점검으로 사용

스키마 검증은 작성 가이드가 아닙니다. 최종 확인 단계입니다.

• 포맷 파일에서 스펙을 작성합니다.
• scripts/validate-spec.mjs로 작성된 스펙을 검증합니다.
• 최종 YAML을 반환하기 전에 스키마 및 검증 규칙 실패를 수정합니다.

schemas/에 번들된 스키마는 Spec Canvas 구현 및 이 스킬의 format-description 참조와 동기화되어야 합니다. 차이가 있는 경우 스킬 버그로 간주하고 조용히 타협점을 만들지 말고 명시적으로 지적합니다.

UI와 데이터 정렬 유지

두 스펙이 모두 존재하는 경우:

• 화면, 엔티티 및 액션 간의 명명 일치
• UI 액션이 실제 엔티티 또는 워크플로우를 암시하는지 확인
• 데이터 스펙 관계가 UI 구조를 지원하는지 확인
• 조용히 백엔드 개념을 발명하지 말고 차이점을 표시

포맷 휴대성 유지

저장소에 존재하고 모든 에이전트가 재사용할 수 있는 일반 YAML 파일을 생성합니다. 스펙이 Spec Canvas UI 상태, 숨겨진 메타데이터 또는 채팅 전용 가정에 의존하지 않도록 합니다.

UI 스펙을 구현 세부 사항 위에 유지

UI 스펙을 CSS, 컴포넌트 문서 또는 변경 로그의 대체품으로 사용하지 마십시오. 좋은 purpose는 사용자 관점에서 화면 또는 블록이 무엇을 위한 것인지 설명합니다. 정확한 간격, 클래스 이름, 픽셀 크기, 일시적인 구현 메커니즘 또는 제품 의미를 변경하지 않는 모든 작은 컨트롤을 열거해서는 안 됩니다.

작업 패턴

새 UI 스펙 생성

• docType, format_version 및 metadata로 시작합니다.
• UI 스펙에서 metadata.description은 필수이며 최상위 제품 의도를 담아야 합니다.
• 주요 앱 형태가 알려지면 screens를 추가합니다.
• 사용자가 보이는 구조를 원할 때 blocks를 추가합니다. blocks는 탐색 단계에서 생략할 수 있습니다.
• templates, navigation 또는 반응형 필드는 실질적으로 도움이 될 때만 추가합니다.
• 현재 로컬 포맷에서 지원하는 UI 반응형 작성에는 metadata.breakpoints, 적응형 screen.template, 적응형 block.columns 및 block.visible이 포함됩니다.
• UI 포맷 파일의 인용 지침을 포함하여 원래 포맷 파일 규칙을 유지합니다.
• 가능한 경우 scripts/validate-spec.mjs로 완성된 파일을 검증합니다.

새 데이터 스펙 생성

• 물리적 데이터베이스가 아닌 논리적 도메인 모델을 설명합니다.
• 공유되는 통제된 어휘가 중요할 때만 enums를 추가합니다.
• 비즈니스적으로 의미 있는 fields로 entities를 정의합니다.
• 논리적 교차 엔티티 구조를 위해 relations를 사용합니다.
• 인덱스, 마이그레이션 또는 ORM별 구문과 같은 구현 전용 사항을 스펙 외부에서 사용자가 명시적으로 요청하지 않는 한 누출하지 않습니다.
• 가능한 경우 scripts/validate-spec.mjs로 완성된 파일을 검증합니다.

기존 스펙 검토 또는 수리

다음을 확인합니다:

• 유효하지 않거나 지원되지 않는 필드
• 누락된 필수 섹션
• 끊어진 화면, 템플릿 또는 내비게이션 참조
• 데이터 스펙의 열거형, 외래 키 또는 관계 오류
• 로컬 검증 규칙에 의해 표면화된 사용자 정의 검증 실패
• 원래 포맷 파일과 현재 로컬 구현 간의 스키마-포맷 불일치
• 구현 메커니즘을 설명하는 과도하게 세부적인 UI purpose 텍스트(제품 의도 대신)

수리할 때 원래 제품 의도를 유지하고 명확성을 회복하는 가장 작은 수정을 합니다.

과도하게 세부적인 UI 스펙 간결화

• 제품 구조가 실제로 변경되지 않는 한 기존 화면, 템플릿, 영역 및 블록 ID를 안정적으로 유지합니다.
• 긴 purpose 단락을 사용자 대면 의도의 한 문장 요약으로 대체합니다.
• 화면, 주요 블록, 내비게이션, 중요한 상태 및 의미 있는 모드를 유지합니다.
• CSS/레이아웃 미세 세부 사항, 플랫폼 특이점, 정확한 타이밍, 로깅 동작 및 컴포넌트 내부 메커니즘을 제거합니다.
• 전체 파일 YAML 재포맷을 피하고, diff를 검토 가능하게 유지하기 위해 대상 편집을 사용합니다.
• 편집 후 검증합니다.

기존 앱에서 스펙 재구성

• 보이는 워크플로우에서 화면 추론
• 반복되는 영역 및 사용자 작업에서 블록 추론
• 도메인 명사 및 상태 변경에서 엔티티 추론
• 관찰된 것과 추측된 것을 분리
• 소스 자료가 불완전할 때 불확실성을 명시적으로 표시

검증

가능한 경우 scripts/validate-spec.mjs를 사용합니다.

• 입력: YAML 스펙 파일의 경로
• docType에서 문서 유형 감지
• 이 스킬의 번들된 JSON Schema에 대해 검증
• 관련 사용자 정의 검증 규칙 실행
• 경고는 권고로 처리
• 오류는 수정된 스펙을 반환할 때 최종 출력에 대한 차단 항목으로 처리

로컬 Spec Canvas 종속성이 없어 스크립트를 실행할 수 없으면 간략히 언급하고 포맷 파일과 검증 규칙 참조를 사용한 수동 검토로 대체합니다.

출력 기대치

스펙을 반환할 때:

• 유효한 YAML 제공
• 포맷에 필요한 곳에서 ID는 snake_case 유지
• 포맷 파일에 의해 정확히 정의된 필드 이름 유지
• 구조에 실질적으로 영향을 미칠 때 가정 언급
• 검증이 실행되었는지 언급

다시 작성된 파일 대신 검토를 반환할 때:

• 구조적 문제를 먼저 나열
• 그 다음 구체적인 수정 사항 제시
• 그 다음 유용한 경우 수정된 조각 또는 전체 스펙 제공