mveplus/claude-skills

How-it-works 사이트

site/ 디렉토리에 의존성 없는 슬라이드쇼를 생성하여 코드베이스를 왜에서 코드 수준까지 설명하고, 프로젝트의 실제 로직을 반영하는 대화형 데모를 포함하며, 이를 게시하는 CI 작업을 추가합니다. 참조 구현: https://mveplus.github.io/onair-led-sign-firmware/ (19개 슬라이드, 4개 시뮬레이션; 소스는 https://github.com/mveplus/onair-led-sign-firmware/tree/main/site에 있습니다).

이 스킬의 templates/ 디렉토리에 있는 템플릿:

파일	복사 위치	목적
index.html	site/index.html	페이지 크롬 + 복제할 슬라이드 패턴
deck.css	site/deck.css	테마 토큰, 레이아웃, 컴포넌트
deck.js	site/deck.js	내비게이션, 개요, 해시 라우팅, 프레임 루프, 스테퍼 헬퍼
app.js	site/app.js	프로젝트 데모를 위한 시작 파일 (스테퍼 연결, 프레임 훅)
github-pages.yml	.github/workflows/pages.yml	GitHub Pages 배포
gitlab-ci.yml	.gitlab-ci.yml에 병합	GitLab Pages 배포

프로젝트별 데모 코드는 site/app.js에 작성하고 (선택적으로 site/app.css에 스타일 추가); deck.js와 deck.css는 일반적으로 유지합니다.

프로세스

1. 빌드 전 질문 (AskUserQuestion 한 번 호출)

먼저 git remote -v를 확인하여 호스팅 질문이 현실을 반영하도록 합니다. 원격 저장소가 GitHub인데 사용자가 GitLab을 말하는 경우 (또는 그 반대), 이에 대해 질문합니다. 최대 네 가지 질문을 합니다:

• 호스팅: GitHub Pages, GitLab Pages, 또는 둘 다.
• 대상/깊이: 혼합 (먼저 아이디어, 그 다음 심층 분석; 기본값), 개발자, 또는 비개발자.
• 대화형 데모: 이 프로젝트에 특화된 3~4개의 후보군을 제공하며, 빠른 스캔을 통해 찾습니다 (상태 머신, 타이밍/임계값 로직, 요청 흐름, 수학/공식, 설정 빌더). 다중 선택 가능.
• 선택사항: 저장소가 제안하는 경우 언어 또는 브랜딩 제약 조건.

2. 코드를 제대로 읽기

진입점, 주요 모듈, README/문서 및 CI 파일을 읽습니다. 슬라이드에서 언급할 모든 내용 (타임아웃, 임계값, 기본값, 주제, 엔드포인트, 리셋이 초기화하는 내용)은 README가 아닌 코드에서 가져옵니다. 문서-코드 불일치 목록과 막다른 지점 (예: 소비자가 없는 CI 작업)을 유지합니다. 슬라이드에는 코드의 실제 동작을 보여주고, 마지막에 사용자에게 목록을 보고합니다. 슬라이드를 문서에 맞게 조용히 "수정"하지 마십시오.

3. 개요 (~12–20개 슬라이드), 챕터별로 그룹화

일반적인 구성: 제목 (재미있는 상호작용 요소 포함) → 아이디어/문제 → 큰 그림 (클릭 가능한 아키텍처) → 요청/데이터 흐름 (애니메이션 스테퍼) → 주요 구성 요소당 하나의 슬라이드 → 복원력/장애 처리 → 보안/비밀 → 빌드, CI, 전달 → 링크가 포함된 설계 원칙 요약. 모든 슬라이드는 data-chapter와 data-title 속성이 필요합니다.

4. 빌드

• 템플릿을 복사하고 index.html에서 슬라이드 패턴을 복제합니다 (히어로, 카드가 있는 두 열, 스테퍼, 정보 그리드).
• 시뮬레이션은 프로젝트의 실제 알고리즘을 재사용합니다: 함수 (정수 연산, 임계값, 순서)를 포팅하고 슬라이드에 해당 이름을 인용합니다. 겉보기에만 맞는 시뮬레이션은 버그입니다.
• 애니메이션에는 Deck.onFrame(slideId, fn)을 사용하여 보이는 슬라이드만 애니메이션되도록 합니다. 클릭 스루 시퀀스에는 Deck.stepper(...)를 사용합니다.
• 다이어그램: CSS 토큰을 사용하는 인라인 SVG; 외부 리소스 없음. CDN이나 가져올 폰트가 없으므로 사이트가 오프라인 및 제한된 Pages에서도 작동합니다.
• 이미지: site/img/에 복사하고, 메타데이터를 제거한 후 크기를 조정합니다 (ImageMagick 사용: magick in -auto-orient -strip -resize 1200x -quality 80 out.jpg). 저장소의 원본 이미지에 GPS EXIF가 있는지 확인하고 (예: identify -format '%[EXIF:GPSLatitude]' 또는 exiftool -gps:all) 발견되면 사용자에게 경고합니다. 휴대폰 사진에는 일반적으로 촬영 장소 정보가 포함되어 있습니다. 푸시되면 git 히스토리에 남으므로 제거하려면 히스토리 재작성이 필요하며, 이는 사용자의 결정입니다.

5. 게시 설정

• GitHub: github-pages.yml을 복사합니다. Pages는 한 번 Source = Actions로 활성화해야 합니다 (Settings → Pages) 또는 아래 명령어를 사용합니다. 사용자가 복사할 명령어는 펜스 코드 블록에 아무것도 덧붙이지 않고 제공합니다. 문장의 마침표가 함께 복사되면 인수에 포함되어 (build_type=workflow.) API가 거부합니다:

  gh api -X POST repos/OWNER/REPO/pages -f build_type=workflow
  

  기본 브랜치에서만 배포됩니다.
• GitLab: pages 작업을 기존 .gitlab-ci.yml에 병합합니다; 덮어쓰지 마십시오. Pages는 자동으로 활성화되며 URL은 Deploy → Pages에서 확인할 수 있습니다.
• README의 개요/"How it works" 섹션에 짧은 링크 단락을 추가합니다.

6. 보고 전 검증

• node --check site/*.js
• python3 -m http.server 8765 --bind 127.0.0.1 --directory site로 서빙합니다 (백그라운드에서). 브라우저 자동화 도구를 사용할 수 있는 경우 (예: Chrome의 Claude), 사이트를 열고 각 챕터를 스크린샷으로 캡처하고 각 데모를 페이지에서 JavaScript를 실행하여 (.click(), PointerEvent 디스패치) 좌표 클릭보다는 구동합니다. 스크린샷은 종종 CSS 픽셀에 비례하여 확대/축소되므로 좌표 클릭이 빗나갈 수 있습니다. 창 크기를 조정할 수 없는 경우, 380px iframe에서 사이트를 로드하고 getBoundingClientRect().right > 381인 요소를 찾아 휴대폰 너비를 확인합니다.
• 브라우저 도구가 없으면 사용자에게 수동으로 확인해야 할 페이지와 데모를 알려줍니다. 사이트를 테스트했다고 보고하지 마십시오.
• 연 탭을 닫고 이후 서버를 중지합니다.

7. 인계

커밋 또는 푸시하기 전에 질문합니다. 그런 다음 브랜치에서: 사이트에 대한 하나의 커밋, 사용자가 요청한 코드 수정 사항에 대한 별도의 커밋을 만듭니다. 보고: 무엇이 빌드되었는지, Pages를 활성화하는 방법, 불일치 목록, 테스트되지 않은 항목 (예: 하드웨어).

스타일 규칙

• 기본적으로 어두운 테마 (deck.css의 토큰), --accent를 통해 프로젝트별로 색조를 변경할 수 있는 빨간색 악센트.
• 평이하고 구체적인 표현. 무엇을 하는지뿐만 아니라 왜 설계 선택이 존재하는지 설명합니다.
• 코드 발췌는 짧고 실제 코드입니다 (소스에서 잘라내며, 파일 이름을 주석으로 표시).
• 키보드: ←/→/Space/PageUp/PageDown/Home/End, 개요는 O, 닫기는 Esc. 터치에서 스와이프. 모든 슬라이드는 고유한 URL을 가집니다 (#/slide-id).