페이지 내 요구사항 문서 읽기 진입점 (뷰어)
목표
프로젝트에 이미 존재하는 요구사항 문서를 제품 인터페이스에 연동하여, 사용자가 현재 페이지에서 바로 해당 설명을 열람할 수 있도록 합니다. 동시에 진입점이 초기 로딩 속도를 저하시키지 않고, 과거 콘텐츠가 유출되지 않으며, 프로덕션 환경에서 내부 문서가 의도치 않게 노출되지 않도록 보장합니다.
문서 작성과의 경계
- 이 스킬은 읽기 진입점의 구현만 담당합니다: 진입점 위치, 문서 매핑, 빌드 복사, 렌더링, 검색, 지연 로딩, 오류 상태, 프로덕션 노출면 처리, 테스트 및 워크스루.
- 문서 콘텐츠는
prd-rule-authoring또는 기타 소스에서 제공됩니다. 이 스킬은 문서를 어떻게 작성해야 하는지 규정하지 않으며, 프로젝트가 반드시 prd-rule-authoring을 사용해야 한다고 요구하지도 않습니다. - 두 스킬은 서로 독립적입니다: 읽기 진입점이 없는 프로젝트도 요구사항 문서를 산출해야 하며, 읽기 진입점이 있어도 문서 작성 규칙이 변경되지 않습니다.
- 유일한 결합점은 문서 디렉토리 + Markdown 규약입니다: 경로, 제목, 렌더링 가능한 구문. 규약은 프로젝트 설정에 정의되며, 스킬에 하드코딩되지 않습니다.
사용 시기
- 제품/개발/테스트 담당자가 '현재 페이지에서 바로 규칙을 확인'하고 싶어 분할 화면으로 MD를 검색하지 않아야 할 때.
- 체계화된 Markdown 요구사항 문서가 이미 존재하며, 읽기 전용으로 표시해야 할 때.
- 내부 문서를 납품 데모에 연동해야 하지만, 프로덕션 가시성을 제어해야 할 때.
해당 사항 없음: 온라인 편집/협업 댓글, 문서 승인 워크플로우, 전체 텍스트 검색 서비스화, 권한별 읽기(향후 확장 가능, 최소 구현에는 포함되지 않음).
읽기 순서
| 파일 | 언제 읽을 것인가 |
|---|---|
references/integration-design.md | 진입점/빌드/매핑/지연 로딩 설계 시 |
references/rendering-and-search.md | 제한된 MD 렌더링, 과거 챕터 필터링, 검색 시 |
references/acceptance-checklist.md | 테스트, 워크스루 및 승인 시 |
references/ops-and-governance.md | 프로덕션 노출면, 문서 업데이트 및 릴리스 프로세스 시 |
최소 구현 체크리스트
- 진입점: 문서 매핑이 있는 페이지에서만 표시. 매핑이 없으면 렌더링하지 않음 (죽은 버튼을 남기지 않음). 진입점 자체는 문서를 전혀 로드하지 않음.
- 소스: 문서 소스는 리포지토리 내 Markdown 파일(또는 이에 준하는 정적 파일)입니다. 빌드 시점에 아티팩트 디렉토리로 복사되며, 산출물과 매핑 간 양방향 검증(매핑 누락 시 또는 고아 문서 발견 시 빌드 실패)을 수행합니다.
- 매핑: 라우트/페이지 → 문서 경로의 레지스트리가 유일한 매핑 소스입니다. 문서 트리는 모듈별로 그룹화되며, 모듈 수준 문서는 개별적으로 식별됩니다.
- 로딩: 드로어/패널이 열린 후에만 문서를 요청합니다. 첫 번째 열기에서 현재 문서를 로드합니다. 검색 색인은 열린 후 유휴 시간에 구축됩니다. 시작 시 문서를 미리 로드하지 않습니다.
- 렌더링: 제한된 Markdown 렌더링 (제목, 단락, 목록, 테이블, 코드, 인용문, 구분선, 링크). 모든 HTML은 이스케이프되며, 화이트리스트에 있는 태그만 출력합니다. 한글/괄호가 포함된 파일명은 분할 URL 인코딩합니다. 서브패스 배포에 적응합니다. 제목 앵커 슬러그는 HTML/URL 위험 문자(
<>&"')를 안전하게 처리하며, 앵커 생성은 단일 진입점 (목차, 본문, 검색, 위치 지정에서 공유)을 사용합니다. - 리더 규칙: 최신 설명만 표시합니다. '업데이트 기록/변경 로그' 챕터는 렌더링하지 않습니다 (해당 내용 포함). 목차와 검색에서도 동기적으로 제외됩니다. 소스 문서에 기록 스냅샷 주석이 포함된 경우, 프로젝트 규약에 따라 필터링하거나 문서 작성자가 작성하지 않아야 합니다.
- 상호작용: 목차 클릭 시 위치 지정, 액션 페이지는 섹션별 기본 위치 지정 힌트 제공, 전역 키워드 검색 (문서별 그룹화, 현재 페이지 히트는 상단 고정, 스니펫은 Markdown 노이즈 제거) 및 이동, 오류 상태 및 재시도, 닫기. 검색 결과 탐색 컨텍스트 유지: 히트 클릭 시 본문만 전환되며, 검색어/결과 목록이 초기화되지 않습니다. 결과 영역의 스크롤 위치가 유지됩니다. 히트 항목은 강조 표시됩니다 (안정적인 키 사용, 최소한 문서+앵커+제목 포함, 필요 시 동일 섹션의 여러 히트를 구분하기 위해 스니펫 추가). 명확한 '검색 초기화' 진입점을 제공하여 문서 트리를 복원합니다. 문서 트리에서 문서를 열면 검색이 초기화됩니다. 색인을 다시 구축하지 않습니다. 레드라인: 목차가 상단에 고정되거나 확장 목록이 본문 상단에 상주하는 경우, 클릭 시 위치 지정은 오프셋을 고려한 커버 높이만큼 이동하여 가려짐을 방지해야 합니다. 자동화된 가려짐 단언 (
toBeVisible은 가려짐을 판단하지 않음)을 사용합니다. 상단 고정 접이식 목차, 스크롤 보상 등 업그레이드된 형태의 세부 사항은references/integration-design.md§7을 참조하십시오. - 프로덕션 노출면 처리: 진입점 스위치는 버튼만 제어하며, 정적 문서를 보호하지 않습니다. 프로덕션에서는 반드시 두 가지 중 하나를 선택해야 합니다: 빌드 시 문서 디렉토리를 제외하거나, 문서 경로에 인증을 추가합니다 (프로덕션 액세스 게이트에 기록).
- 테스트: 매핑 완전성, 빌드 산출물 일관성, 과거 챕터 미표시, 지연 로딩 (프리로드 없음), 검색 및 이동, 검색 결과 컨텍스트 유지 (키워드/결과/스크롤 위치 유지, 연속 히트, 초기화 시 트리 복원, 강조 고유성, 색인 재구축 없음), 오류 상태. 목차/위치 지정에 가려짐 단언 추가 (
toBeVisible은 가려짐을 판단하지 않음). 스크롤 복원 단언은 clamp를 허용하며, 픽셀 단위의 정확한 일치는 요구하지 않습니다. 브라우저에서 워크스루를 수행하고 증거를 보관합니다 (스크린샷과 최종 동작 일치).
경계
- 비즈니스 페이지 동작, 메뉴/라우트 비즈니스 값, Mock 데이터를 변경하지 않습니다. 읽기 진입점과 문서 에셋 파이프라인만 추가합니다.
- 타사 무거운 MD 렌더링 의존성을 도입하지 않습니다. 렌더러는 제한적이고, 테스트 가능하며, 이스케이프 가능해야 합니다.
- '문서 작성 규칙'을 이 스킬에 작성하지 않습니다. '진입점 구현 세부 사항'을 문서 작성 스킬에 작성하지 않습니다.
- 실제 권한, 프로덕션 배포 및 인증 방식은 프로젝트 게이트를 따릅니다. Mock/데모 통과가 프로덕션에서 보호되었음을 의미하지는 않습니다.
납품 설명
진입점 위치 및 표시 조건, 문서 소스 및 매핑, 빌드 복사 및 검증, 렌더링 및 과거 필터링, 지연 로딩 및 검색, 오류 상태, 프로덕션 노출면 처리, 테스트 및 워크스루 증거, 미처리 항목.