Communitygithub.com

pessimistcamellia/proto-note

Cursor Agent Skill: 대화형 HTML 프로토타입에 변경 노트, 앵커, 커넥터 및 SDD 딥 링크를 주석으로 추가합니다. Axure 스타일 주석 패널, 원형 변경 추적에 최적화.

proto-note란 무엇인가요?

이 스킬은 단일 파일 HTML 프로토타입에 '개발자 관점의 변경 가이드'를 오버레이합니다. 오른쪽 고정 다크 주석 패널(모듈 체크박스 + 주석 카드) ↔ 페이지 번호 앵커 + 캔버스 연결선을 제공하며, 양방향 호버/클릭 위치 이동 및 SDD(소프트웨어 디자인 문서) 딥 링크를 지원합니다. 주 사용처는 Cursor AI 에이전트이며, 프로토타입 제작 시 실제 UI 라이브러리와 컴포넌트 사양을 우선 사용하고, 내부망 또는 GitHub Pages에 배포합니다. 스킬은 17개의 제품 불변 규칙과 상세한 워크플로우를 포함하여 변경 사항을 정확하고 일관되게 문서화하도록 보장하며, 다중 페이지/다중 엔드포인트 및 데이터 연동을 지원합니다.

지원 대상✓Claude Code~Codex CLI✓Cursor
npx skills add pessimistcamellia/proto-note
원본 보기→모든 스킬 둘러보기

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

OpenAIChatGPTClaudeClaudeGeminiGeminiGrokGrokPerplexityPerplexityDeepSeekDeepSeek

문서

프로토타입 변경 주석 레이어 (proto-note)

단일 파일 HTML 프로토타입 위에 '개발자 관점 변경 가이드'를 오버레이합니다: 오른쪽 고정 다크 주석 패널(모듈 체크 + 주석 카드) ↔ 페이지 번호 앵커 + 캔버스 연결선; 양방향 호버/클릭 위치 이동; 주석 카드에 SDD 딥 링크 포함.

설치 및 디렉토리

# 개인 스킬 (권장)
git clone https://github.com/pessimistcamellia/proto-note.git ~/.cursor/skills/proto-note

# 또는 프로젝트 내
git clone https://github.com/pessimistcamellia/proto-note.git .cursor/skills/proto-note

전체 디렉토리를 위 경로에 복사해도 됩니다. 디렉토리 구조:

proto-note/
├── SKILL.md
├── assets/diff-annotator.js      # 주석 엔진 (프로토타입에 인라인으로 삽입, 로직 수정 금지)
├── references/changeset-schema.md
├── docs/screenshots/             # README 스크린샷
└── scripts/deploy_github.sh      # GitHub Pages 대체 배포

환경 종속성

기능도구미사용 시
기술 스택/소스 코드 파악codewiki MCP (또는 이에 준하는 코드 검색)온라인 URL + 소스 저장소 + 브라우저 DOM 사용
SDD 딥 링크lark-cli (Feishu)문서 URL 및 섹션 blockId 수동 입력; Feishu 미사용 시 해당 섹션 앵커로 연결
픽셀 단위 조정브라우저 DevTools / chrome-devtools MCP수동으로 온라인 페이지 열어 비교
배포내부망 정적 호스팅 (우선)개인 GitHub Pages (deploy_github.sh, gh 권한 필요)

팀에 다른 프론트엔드 규범 스킬(예: 선택지 화이트리스트, 컴포넌트 라이브러리 사용법)이 있는 경우, 제작 전에 필요에 따라 읽어오십시오. 없으면 대상 저장소 소스 코드와 팀 문서를 기준으로 합니다.

기본 계획: 컴포넌트 라이브러리 및 게시 우선순위

우선순위에 따라 실행하며, 이전 단계를 사용할 수 없을 때만 다음 단계로 넘어갑니다. 마지막 단계가 기본 대체입니다:

  1. 컴포넌트 라이브러리 / 규범 (우선): 대상 온라인 시스템에서 실제 사용 중인 컴포넌트 라이브러리 및 컴포넌트 규범을 사용합니다 (소스 코드 / DOM / 팀 규범 스킬 참조). 근거 없이 라이브러리를 교체하는 것을 금지합니다.
  2. 게시 주소 (우선): 내부망에 기존 정적 호스팅(또는 팀에서 합의한 내부망 주소)이 있는 경우, 내부망에 게시하는 것을 우선합니다.
  3. 기본 대체: 실제 컴포넌트 라이브러리/규범을 얻을 수 없거나, 권한, 네트워크, 내부망 접근 불가 등의 이유로 사용할 수 없는 경우 → 컴포넌트는 일반 계획에 따라 자유롭게 선택 가능 (단일 파일 대화형 HTML 유지); 사용자 개인 GitHub 저장소(Pages)에 게시. 배포 전 gh 권한을 확인해야 하며, 권한이 없으면 먼저 사용자와 소통하고, 동의 없이 개인 저장소에 푸시하는 것을 금지합니다.

제품 불변 규칙

  1. 변경 3단계 + 유형: 페이지 / 모듈 / 필드; 유형은 신규, 텍스트, 열거형 기준, 로직, 프로세스, 삭제로 구분하며, 막연하게 '신규'라고 표시하는 것을 금지합니다.
  2. 기본 숨김, 모듈 체크박스: 열었을 때 레이블을 표시하지 않음; page::module 기준으로 체크; 상태는 localStorage에 저장됩니다. 신규 모듈의 누락된 키는 기본적으로 true (표시), '한 번이라도 스위치를 껐다'는 이유로 상속된 숨김을 금지합니다; 더티 상태는 LS_KEY 버전 업그레이드로 제거합니다.
  3. SDD에만 연결, PRD는 표시하지 않음: 주석 카드는 SDD문서URL#blockId를 사용합니다.
  4. 정보 간결: 주석 패널에 버전 번호/베이스라인/사용 설명 없음; desc는 결론만 작성.
  5. 클릭 가능하면 반드시 유효: 모듈 체크 시 즉시 뷰 전환 + 스크롤 + 펄스 위치 이동.
  6. 리뷰 상태는 주석 패널에서만: 일반/빈 상태/오류 상태 등은 demoControls에 배치; 실제 비즈니스 탭은 비즈니스 페이지에 유지.
  7. 입력 분기에 재현 가능한 예제 제공: examples는 fixture와 일치해야 하며, 플레이스홀더 가짜 값을 금지합니다.
  8. 주석 패널이 콘텐츠를 가리지 않음: 비즈니스 레이아웃을 압축하지 않음; spacer로 scrollWidth를 확장하여 가로 스크롤로 오른쪽 전체를 볼 수 있게 합니다. body padding-right만 추가하거나 비즈니스 루트 너비를 변경하는 것을 금지합니다.
  9. 컴포넌트 라이브러리 및 규범은 실제 온라인 우선: 복원 가능하면 반드시 복원해야 합니다 ('기본 계획' 1단계 참조). 동일한 컴포넌트 라이브러리 사용이 곧 복원을 의미하지 않음 — 스켈레톤, 열 집합/열 너비, 고정 열, 셀 구조, 작업 열 레이아웃, 사용자 정의 클래스명 및 핵심 스타일은 온라인 DOM/소스 코드를 참조해야 함; 인도 전에 화면별로 스크린샷 비교. 실제 컴포넌트 라이브러리/규범을 얻을 수 없는 경우에만 일반 컴포넌트 대체를 허용합니다.
  10. 게시는 내부망 우선, 그 다음 개인 GitHub: 내부망 주소가 있으면 우선 사용; 사용 불가 시 개인 GitHub Pages에 게시 ('기본 계획' 2–3단계 참조).
  11. '이전' = 온라인 현재 상태: 신규 항목은 '해당 페이지/모듈/기능/필드 없음'으로 작성; 이전 데모 버전과의 차이로 작성하는 것을 금지; 온라인 신규 항목을 빠뜨리지 않음.
  12. UI 위치가 없으면 연결선 없음: 순수 프로세스/링크는 target: null, 앵커 없음; 카드는 '프로세스 및 링크 · 페이지에서 보이지 않음'에 포함되며 changes 끝에 배치.
  13. 팝업 내 변경 사항: 주석 카드 클릭 시 DIFF_HOOKS.locate를 통해 팝업을 연 다음 연결선 작성; 앵커/연결선 z-index는 팝업보다 높아야 함 (엔진은 9000대 사용).
  14. 팝업은 페이지 가로/세로 스크롤을 따름: 주석 패널이 열려 있을 때 팝업 컨테이너는 (-scrollX,-scrollY)에 따라 이동 (엔진에서 처리); 스크롤을 피하기 위해 잠그는 것을 금지.
  15. 다운로드 가능한 파일은 실제 형식: 템플릿/영수증은 실제 비즈니스와 동일한 형식 및 구조 (예: 이중 시트는 실제 .xlsx여야 함); CSV로 대체하는 것을 금지.
  16. 멀티 엔드포인트 각각 제작 및 연동: 운영 백엔드, C-엔드 등은 시스템 경계에 따라 HTML 분리; 통합 메뉴에 '엔드포인트 · 페이지' 명시; 페이지 간 데이터가 있으면 시뮬레이션 기록/읽기/시작/중지/예외.
  17. 주석 카드는 SDD로 이동 가능해야 함: SDD가 있을 때 각 변경 사항(또는 해당 기능 포인트)에 sdd.section + blockId를 구성; 카드에 딥 링크 렌더링; 클릭 시 해당 섹션이 열려야 하며, 섹션 이름만 쓰는 것을 금지.

프레젠테이션 레이어 규범 (엔진에 내장, 되돌리지 않음)

  • 오른쪽 주석 패널: 진한 네이비 블루, 너비 360px, 접어서 플로팅 진입점으로 만들 수 있음.
  • 가로 스크롤: document.body.scrollWidth로 비즈니스 너비 측정 (spacer는 absolute이며 이 값에 포함되지 않음); spacer를 먼저 숨기고 측정하지 않음. 스크롤 복원은 behavior:"instant"를 사용하여 scroll-behavior:smooth와 충돌 방지.
  • 앵커: 문서 좌표 position:absolute, 대상 왼쪽 상단 고정; fixed+스크롤 추적 프레임 금지; 가려짐은 elementFromPoint로 숨김.
  • 연결선: 평소에는 선 없음; 호버/고정 시에만 하나 그리기; 고정 상태가 호버 상태보다 우선; 시작점은 실시간 rect 사용.
  • 주석 카드: 번호 + 제목 + 유형·레벨 + 결론 + 이전/이후 + SDD; examples 포함 가능.
  • 데모 영역: 주석 패널 상단 segmented control → DIFF_HOOKS.setDemoState.

기술 스택 복원 (Step 0)

'기본 계획'에 따라 실행: 복원 가능하면 반드시 복원; 불가능하면 이유를 기록한 후 자유 선택 대체 진행.

  1. 사용자가 온라인 URL을 제공하지 않음 → 먼저 알림; 여전히 없으면 시스템/라우트/소스 코드 직접 검색.
  2. codewiki(또는 소스 코드 검색) 사용하여 확인: 프레임워크, 컴포넌트 라이브러리, 라우트→페이지 파일, 핵심 템플릿 조각; 필요한 경우 인덱스 신선도 확인, 온라인 DOM으로 교정.
  3. 우선 대상 저장소의 실제 컴포넌트 라이브러리 및 규범 사용; 신규 컨트롤은 해당 페이지의 기존 유형/크기/배열 따름. 동일한 컴포넌트 라이브러리 사용이 곧 복원을 의미하지 않음 — 스켈레톤, 열 집합/열 너비, 고정 열, 셀 구조, 작업 열 레이아웃, 사용자 정의 클래스명은 온라인 DOM/소스 코드 참조.
  4. 팀 규범 스킬이 있으면 따름; 없으면 대상 저장소 및 문서 따름.
  5. 픽셀 단위 또는 검색이 부족할 때: 온라인 페이지를 열어 마운트 방식, 컴포넌트 클래스명, 테이블 열 너비/고정 열, 작업 열 구조, 사용자 정의 computed style 캡처.
  6. 결과물은 여전히 단일 파일 HTML; CDN으로 동일한 프레임워크/컴포넌트 라이브러리를 가져올 수 있으면 가져옴. 전체 페이지를 복원할 수 없을 때, 일반적인 컴포넌트 라이브러리를 자유롭게 선택하여 대화형 프로토타입 완성, 인도 설명에 '미복원 사유' 명시.
  7. 게시: 내부망 정적 주소가 있으면 우선 업로드; 그렇지 않으면 사용자 GitHub 권한을 얻은 후 deploy_github.sh로 개인 저장소에 게시.

고주파 함정: 외부 레이어에 초과 min-width를 설정하여 테이블을 고정시키지 말 것 (내부 가로 스크롤 및 fixed 열 손실); 통합 메뉴 상단 바는 position:fixed 사용, 넓은 페이지 가로 스크롤 시 상단 바 끊김 방지.

다중 페이지 / 멀티 엔드포인트 및 데이터 연동

  1. 먼저 행렬 작성: 엔드포인트/시스템 → 페이지 → 주요 상태 → 업스트림/다운스트림 데이터; 다른 기술 스택은 파일 분리, 강제 병합하지 않음.
  2. 통합 메뉴: '엔드포인트 · 페이지' 명명, 현재 페이지 강조; 메뉴는 변경 주석을 하지 않음.
  3. 동일 출처 동일 디렉토리 배포, localStorage 공유 보장.
  4. 공유 상태 키: proto-note:<requirement-slug>:state:v1; 읽기/쓰기 후 동일 페이지에 이벤트 발행, 교차 탭에서 storage 청취.
  5. URL은 비즈니스 ID만 포함; 본문은 공유 상태에 위치. 동일 출처가 아닌 경우 우선 동일 출처로 변경, 그렇지 않으면 postMessage 및 origin 검증.
  6. 내장 fixture + '데모 데이터 초기화'; 업스트림/다운스트림 상태 및 예외 재현 가능.

워크플로우

  1. Step 0 기술 스택 복원.
  2. PRD에서 변경 목록, 엔드포인트/페이지 행렬, 입력 분기 및 페이지 간 데이터 관계 추출 → references/changeset-schema.md 참조.
  3. SDD blockId를 가져와 각 변경 사항의 sdd에 기록.
  4. 엔드포인트별로 프로토타입 제작; 멀티 엔드포인트는 메뉴와 공유 상태 구성 및 연동 검증.
  5. 주석 레이어 연동:
    • 컨테이너에 data-diff-page 추가; 위치 지점에 id 추가; DIFF_HOOKS.locate / setDemoState 구현.
    • 리뷰 탭을 meta.demoControls로 이동.
    • 분기를 examples에 기록 (fixture와 일치).
    • </body> 앞에 DIFF_CHANGESET 인라인, 그 다음 최신 assets/diff-annotator.js 전체 복사 (오래된 복사본 사용 금지).
  6. 배포 및 자체 점검:

    • 내부망 우선: 기존 내부망 정적 호스팅이 있으면 업로드; 객체 키가 덮어쓰이지 않으면 새 경로 (-v2 등)로 변경, 반환 URL + md5 기준.

    • 대체 GitHub Pages: 내부망을 사용할 수 없을 때 개인 저장소에 게시. 먼저 gh auth status; 권한이 없으면 소통하고 gh auth login 완료, 권한 없이 개인 저장소 푸시 금지:

      bash ~/.cursor/skills/proto-note/scripts/deploy_github.sh <slug> ./index.html

자체 점검 목록

  • 복원 가능 시 온라인 실제 컴포넌트 라이브러리/규범 사용; 복원 불가 시 사유 명시 및 자유 선택 대체 진행
  • 게시 우선 내부망; 내부망 사용 불가 시 권한 획득 후 개인 GitHub에 게시
  • 온라인 화면별 비교 (온라인 페이지가 있는 경우: 열 너비, 고정 열, 작업 열, 페이징, 상단 바)
  • 초기 앵커/연결선 없음; 모듈 체크 해제; 신규 모듈은 기존 방문자에게 기본 표시
  • 모듈 체크 시 해당 카드/앵커/선만 표시 및 자동 위치 이동; 팝업 내 변경 사항은 자동 팝업 열기 및 연결선이 팝업 위에 위치
  • 스크롤 시 앵커 이동 없음; 평소 연결선 없음, 고정/호버 시 하나의 선만; 고정 상태가 hover에 의해 빼앗기지 않음
  • 주석 패널 열린 상태에서 가로 스크롤로 오른쪽 전체 보기 가능; 가로 스크롤 위치가 DOM 업데이트로 인해 튕기지 않음; 팝업이 하단 페이지 가로/세로 스크롤을 따름
  • target:null은 앵커 없음, 카드는 '프로세스 및 링크'에 있고 뒤쪽에 위치; '이전'은 모두 온라인 현재 상태, 빠뜨림 없음
  • 주석 카드 SDD 딥 링크가 열리고 해당 섹션으로 위치 이동
  • 데모 상태는 주석 패널에서만; examples 재현 가능; 다운로드 파일 형식 정확
  • 멀티 엔드포인트 메뉴 접근 가능; 프로토타입 간 읽기/쓰기/새로고침/교차 탭/초기화 일치
  • 주석 패널 접으면 깔끔; 비즈니스 상호 작용에 영향 없음

참조

관련 스킬

steipete/sag

ElevenLabs text-to-speech with mac-style say UX.

community

steipete/oracle

Oracle CLI second-model review/debug/refactor/design with selected files, dry-run token checks, API or browser engine.

community

steipete/peekaboo

Capture and automate macOS UI with the Peekaboo CLI.

community

mattpocock/design-an-interface

Generate multiple radically different interface designs for a module using parallel sub-agents. Use when user wants to design an API, explore interface options, compare module shapes, or mentions "design it twice".

community

mattpocock/prototype

Build a throwaway prototype to flesh out a design — a runnable terminal app for state/business-logic questions, or several radically different UI variations toggleable from one route.

community

mattpocock/grill-me

Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".

community