Communitygithub.com

html-explainer

에이전트가 'HTML 설명 페이지'를 계획, 구축 또는 분할하여 구체적인 결과물이 사용 가능한 문서나 스크립트가 되도록 안내합니다. 이 프로시저는 HTML 설명 페이지, 이 스킬의 파일들, 디자인 룩을 통해 진행됩니다. 새로운 작업에서 이 기술이 요구될 때 사용하세요.

html-explainer란 무엇인가요?

이 스킬은 AI 에이전트(Claude Code, Cursor, Codex)가 HTML 설명 페이지를 만들 때 따라야 할 체계적인 워크플로와 디자인 가이드를 제공합니다. 핵심 목표는 사용자가 요청한 질문에만 정확히 답하는 최소한의 페이지를 만드는 것입니다. 모든 페이지는 다크 테마의 DESIGN.md를 따르며, 링크는 모두 파란색 알약 형태로 표시됩니다. 다이어그램은 스윔레인(swimlane) 또는 재생 가능한 스윔레인만 사용하며, 머메이드(mermaid) 문법으로 작성되어야 합니다. 이 스킬은 템플릿, 참조 파일, 재생 가능한 스윔레인 에셋을 포함하여 일관된 결과물을 보장하며, 작업 완료 전 반드시 수행해야 할 체크리스트도 제공합니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/frhn-xo/html-explainer/tree/HEAD/skills/html-explainer

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

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

문서

HTML 설명 페이지

사용자는 브라우저에서 이 페이지들을 읽고 Cmd+클릭으로 VS Code로 바로 이동합니다. 단락보다 스윔레인의 흐름을 훨씬 빠르게 이해하며, 각 페이지는 자신이 물은 내용에 답하고 그 이상은 포함하지 않기를 원합니다.

이 스킬의 파일들

  • assets/template.html: 모든 페이지의 시작점입니다. 복사해서 사용하며, 절대 처음부터 작성하지 않습니다.
  • references/DESIGN.md: 모든 페이지가 따르는 디자인입니다. 항상 다크 모드이며, 모든 링크는 파란색 알약입니다 (references/page.md, "룩"). 템플릿에 없는 색상이나 요소가 필요할 때 참조하세요.
  • references/page.md: 파일 이름과 위치, 사이드바, 파일 링크, 작업 섹션, 연결된 페이지 섹션, 마스터 페이지와 설명 페이지에 대한 내용입니다. 페이지를 만들거나 구조를 변경할 때 읽으세요.
  • references/writing.md: 문제 섹션과 모든 산문에 대한 내용입니다. 텍스트를 쓰기 전에 읽으세요.
  • references/diagrams.md: 스윔레인 모양과 확인 방법에 대한 내용입니다. 다이어그램을 그리거나 편집하기 전에 읽으세요.
  • references/playable.md, assets/player.js, assets/player.css: 재생 가능한 스윔레인입니다. 사용자가 "재생 가능"이라고 말하거나 div.player가 있는 페이지를 편집할 때 읽으세요.

룩

모든 페이지는 references/DESIGN.md를 따르며, 항상 다크 모드로 유지됩니다. 모든 링크는 파란색 알약 형태로 표시되어 클릭 가능함을 강조합니다: 파일은 밑줄, 다른 페이지는 ↗, 같은 페이지의 섹션은 둘 다 없음 (references/page.md, "룩: DESIGN.md, 항상 다크" 및 "세 가지 링크 유형"). 템플릿이 이미 이를 처리합니다. 모든 다이어그램은 독자가 크기 조정, 확대/축소 및 드래그할 수 있는 패널 안에 표시됩니다 (references/diagrams.md, "다이어그램 블록").

페이지를 최소로 유지

페이지에는 사용자가 요청한 내용만 포함됩니다. 추가 섹션, 표 또는 메모는 사용자가 답을 찾기 위해 지나쳐야 하는 내용입니다.

  • 섹션: 요청에 필요한 것만 포함합니다. 하나의 스윔레인과 그 주변의 짧은 단락이 하나의 섹션입니다. 사용자가 요청하지 않은 섹션은 절대 추가하지 않습니다: 요약, 목록, "이유" 섹션, 과거 결정 기록 등 없음.
  • 표: 사용자가 요청한 경우에만 사용합니다. 대신 단락과 스윔레인을 작성합니다.
  • 다이어그램 아래: 아무것도 없습니다. 파일 목록, 메모, "그려지지 않음" 줄 없음. 다이어그램을 읽기 위해 문장이 필요하면 다이어그램 앞 단락에 넣습니다.

요청에 따라 어떤 섹션을 사용할지

페이지를 질문에 맞춥니다:

  • "문제가 무엇인지", 디버깅, 버그 수정: 문제 섹션을 먼저 둡니다 (references/writing.md). 버그의 스윔레인(마스터 페이지의 경우 재생 가능한 것, references/playable.md)을 포함합니다. 그런 다음 설명에 필요한 추가 스윔레인을 배치합니다.

  • 작업이 논의된 후 기능 구현 또는 버그 수정: 문제 섹션 바로 아래에 작업 섹션을 둡니다 (references/page.md, "작업 섹션"). 사용자가 아직 문제를 파악 중이라면 작업이 아직 없으므로 작업 섹션도 없습니다.

  • "이게 어떻게 동작하나요?", "이 프로젝트는 무엇인가요?": 문제 섹션도 작업 섹션도 없습니다. 흐름의 스윔레인과 도움이 되는 짧은 단락을 배치합니다.

  • "이런 것을 어떻게 만들 수 있나요?": 하나의 섹션: 일반적인 스윔레인, 추가할 수 있는 추가 기능, 진행 방법을 포함합니다.

  • 다른 페이지와 연결된 페이지(마스터와 그 설명 페이지들, 또는 사용자가 연결을 요청한 페이지들): 맨 아래에 연결된 페이지 섹션을 둡니다 (references/page.md, "연결된 페이지 섹션").

그 외: 가장 적은 수의 섹션으로 질문에 답합니다.

다이어그램: 스윔레인만

두 가지 종류의 다이어그램만 있습니다:

  1. 스윔레인: 액터 또는 시스템당 하나의 상자를 사용하는 순서도입니다. 작업을 수행하는 상자 안에 단계가 있고, 작업이 이동할 때 경계를 넘는 화살표가 있습니다 (references/diagrams.md).
  2. 재생 가능한 스윔레인: 재설정/뒤로/다음/재생 버튼, 누를 때마다 하나의 화살표, 그리고 아래에 설명이 있는 동일한 스윔레인입니다 (references/playable.md). "재생 가능", "재생 가능한 스윔레인", "재생 가능한 다이어그램" 및 "재생 가능한 전/후" 모두 이 의미입니다. "스윔레인" 단독 사용은 일반 스윔레인을 의미합니다.

다른 다이어그램 요청("머메이드 다이어그램", "흐름 그리기", "이것의 다이어그램")은 모두 스윔레인으로 대체됩니다.

워크플로

  1. 이것이 마스터 페이지의 설명 페이지인가요? 티켓 폴더에서 요청의 고유한 구문을 grep합니다. 사용자가 항목 텍스트만 붙여넣고 마스터 이름을 언급하지 않은 경우에도 마찬가지입니다. 일치하면 새 페이지는 해당 마스터의 설명 페이지입니다. 마스터의 파일명 접두사를 사용하고 동일한 변경에서 양방향 링크를 추가합니다 (references/page.md).
  2. 파일 생성 (references/page.md, "파일"), assets/template.html에서 복사합니다. {{…}} 플레이스홀더를 채우고 localStorage 키 toc-open-CHANGE-ME를 페이지 고유 값으로 변경합니다.
  3. 섹션 결정 "요청에 따라 어떤 섹션을 사용할지"를 참고하여 필요한 섹션만 작성합니다.
  4. 스윔레인 그리기 (references/diagrams.md). 렌더링하기 전에 커버된 코드의 모든 루프, 분기, 실패 경로 및 조기 반환을 나열하고 각각이 그려졌는지 확인합니다.
  5. 모든 파일 참조 링크 #L<줄> 형식으로 연결합니다. 각 경로가 존재하고 대상 줄이 실제로 텍스트가 주장하는 내용인지 확인합니다.
  6. 아래 체크리스트를 실행한 후 채팅에 페이지 링크(아래 참조)와 함께 보고합니다. 코드가 수행하는 작업 중 다이어그램에서 누락된 것이 있으면 그 회신에 말합니다.

완료 전 체크리스트

  • 페이지에는 요청에 필요한 섹션만 있습니다. 문제를 설명하지 않으면 문제 섹션 없음, 작업이 논의되지 않았으면 작업 섹션 없음, 요청되지 않았으면 표 없음, 다이어그램 아래에 아무것도 없음.
  • 페이지가 사람의 말이나 원하는 바를 설명하는 경우, 첫 문장은 사용자가 사용할 단어로 그들이 원하는 것을 말합니다 (references/writing.md, "누군가가 의미한 바를 설명하기").
  • 페이지는 템플릿의 룩을 유지합니다. 항상 다크 모드, 모든 색상은 references/DESIGN.md에서, 모든 링크는 파란색 알약과 해당 표시, prefers-color-scheme 밝은 테마 추가 없음 (references/page.md, "룩").
  • 범례는 색상이 아닌 의미를 명명합니다 ("잘못된 부분"이며 "황토색 = …" 아님). 페이지에는 자체 색상 목록이 없습니다 (references/page.md).
  • 모든 다이어그램은 스윔레인입니다. 페이지에 sequenceDiagram, stateDiagram, classDiagram 등 다른 유형은 없습니다.
  • 모든 다이어그램을 mermaid-cli로 렌더링하고 PNG를 확인합니다 (references/diagrams.md, "렌더링하여 확인"). 페이지는 Mermaid 구문 오류 없이 로드되어야 합니다.
  • 보내기, 쓰기, 호출 또는 읽기를 수행하는 모든 상자는 텍스트에 대상과 출처를 명시하고, 화살표는 해당 시스템의 상자에 닿아야 합니다. 다른 시스템에 대한 호출은 화살표가 나가고, 다음 단계에서 응답을 사용하는 경우 돌아오는 화살표도 있어야 합니다.
  • 스윔레인 레인: 소스에서 [" "]와 ghost를 grep합니다. 없어야 합니다. PNG에서 레인 상자가 자체 단계에 필요한 것보다 더 넓거나 높지 않습니다.
  • 재생 가능한 스윔레인: 브라우저에서 처음부터 끝까지 단계별로 실행하고 다시 되돌아옵니다.
  • 모든 사이드바 href 및 data-href는 페이지의 id로 확인되고, 모든 파일 링크 경로는 페이지 기준으로 존재합니다.
  • 설명 페이지: 마스터가 해당 주제를 논의하는 곳마다 링크하고, 설명 페이지의 리드가 다시 링크합니다.
  • 연결된 페이지: 각 페이지는 연결된 페이지 섹션에 다른 페이지를 나열하고, 해당 섹션은 페이지의 마지막이며, 모든 링크는 기존 파일을 엽니다.
  • 작업 상태 변경 후: grep으로 각 작업의 체크박스 클래스와 레이블을 나란히 나열하고, 완료된 작업은 모두 동일하게 보입니다 (references/page.md).
  • 자동화로 열린 브라우저 탭은 일반적으로 백그라운드(document.visibilityState === "hidden")에 있으므로 스크롤 이벤트가 발생하지 않습니다. 각 scrollIntoView() 후 markActive()를 호출하여 스크롤 스파이를 테스트하고, 고장났다고 결론내리지 마십시오.

채팅에서 페이지 언급하기

채팅 응답이 HTML 페이지를 언급할 때마다 사용자가 브라우저 주소 표시줄에 바로 붙여넣을 수 있는 두 줄을 제공합니다. 각 줄은 별도 줄에 있어야 합니다:

file:///Users/<사용자>/<저장소>/<티켓>_<주제>/<주제>.html

/Users/<사용자>/<저장소>/<티켓>_<주제>/<주제>.html

첫 번째 줄은 전체 file:/// URL이고, 두 번째 줄은 디스크의 절대 경로입니다. 각 줄에는 다른 것이 들어가지 않습니다: 산문, 백틱, 마크다운 링크, 글머리 기호, > 인용문 없음. 필요한 경우 위 줄에 짧은 레이블을 넣습니다 (예: "브라우저에 붙여넣으세요:"). 특정 섹션을 의미하는 경우 id가 존재하는지 확인한 후 URL에 #id를 추가합니다. 채팅의 코드 파일은 일반 상대 링크를 유지합니다.

이유: 상대 링크는 VS Code에서 HTML 소스를 열고, file:/// 링크는 브라우저에서 렌더링된 페이지를 엽니다. 문장에 묻히거나 마크다운으로 감싸인 URL은 수동으로 골라내야 합니다.

관련 스킬