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, "연결된 페이지 섹션").
그 외: 가장 적은 수의 섹션으로 질문에 답합니다.
다이어그램: 스윔레인만
두 가지 종류의 다이어그램만 있습니다:
- 스윔레인: 액터 또는 시스템당 하나의 상자를 사용하는 순서도입니다. 작업을 수행하는 상자 안에 단계가 있고, 작업이 이동할 때 경계를 넘는 화살표가 있습니다 (
references/diagrams.md). - 재생 가능한 스윔레인: 재설정/뒤로/다음/재생 버튼, 누를 때마다 하나의 화살표, 그리고 아래에 설명이 있는 동일한 스윔레인입니다 (
references/playable.md). "재생 가능", "재생 가능한 스윔레인", "재생 가능한 다이어그램" 및 "재생 가능한 전/후" 모두 이 의미입니다. "스윔레인" 단독 사용은 일반 스윔레인을 의미합니다.
다른 다이어그램 요청("머메이드 다이어그램", "흐름 그리기", "이것의 다이어그램")은 모두 스윔레인으로 대체됩니다.
워크플로
- 이것이 마스터 페이지의 설명 페이지인가요? 티켓 폴더에서 요청의 고유한 구문을 grep합니다. 사용자가 항목 텍스트만 붙여넣고 마스터 이름을 언급하지 않은 경우에도 마찬가지입니다. 일치하면 새 페이지는 해당 마스터의 설명 페이지입니다. 마스터의 파일명 접두사를 사용하고 동일한 변경에서 양방향 링크를 추가합니다 (
references/page.md). - 파일 생성 (
references/page.md, "파일"),assets/template.html에서 복사합니다.{{…}}플레이스홀더를 채우고localStorage키toc-open-CHANGE-ME를 페이지 고유 값으로 변경합니다. - 섹션 결정 "요청에 따라 어떤 섹션을 사용할지"를 참고하여 필요한 섹션만 작성합니다.
- 스윔레인 그리기 (
references/diagrams.md). 렌더링하기 전에 커버된 코드의 모든 루프, 분기, 실패 경로 및 조기 반환을 나열하고 각각이 그려졌는지 확인합니다. - 모든 파일 참조 링크
#L<줄>형식으로 연결합니다. 각 경로가 존재하고 대상 줄이 실제로 텍스트가 주장하는 내용인지 확인합니다. - 아래 체크리스트를 실행한 후 채팅에 페이지 링크(아래 참조)와 함께 보고합니다. 코드가 수행하는 작업 중 다이어그램에서 누락된 것이 있으면 그 회신에 말합니다.
완료 전 체크리스트
- 페이지에는 요청에 필요한 섹션만 있습니다. 문제를 설명하지 않으면 문제 섹션 없음, 작업이 논의되지 않았으면 작업 섹션 없음, 요청되지 않았으면 표 없음, 다이어그램 아래에 아무것도 없음.
- 페이지가 사람의 말이나 원하는 바를 설명하는 경우, 첫 문장은 사용자가 사용할 단어로 그들이 원하는 것을 말합니다 (
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은 수동으로 골라내야 합니다.