공개 문서 조회 설계

작성일: 2026-08-17 상태: 사용자 설계 승인 완료, 구현 전

배경

사이트는 하네스 작업법을 설명하고 5240lab의 적용 근거를 보여주지만, 그 작업법이 실제로 만들어낸 문서 자체는 저장소 안에만 있다. 설계 문서, 기능정의서, 기술계획, 작업목록, 검증 보고서는 하네스가 무엇을 산출하는지 보여주는 가장 직접적인 증거인데 방문자는 볼 수 없다.

사용자는 이 문서들을 사이트에서 조회할 수 있게 해달라고 요청했고, 공개 범위는 로그인 없는 완전 공개, 대상은 네 문서군 전부로 승인했다.

목표

• 저장소의 마크다운 문서를 사이트에서 읽을 수 있게 한다.
• 공개해서는 안 되는 값이 빌드를 통과하지 못하게 막는다.
• 웹 런타임이 원본 저장소를 직접 읽지 않는다는 헌법 원칙 V를 지킨다.
• JavaScript 없이도 문서를 읽을 수 있게 한다.

검토한 방향

1. 전용 /docs 섹션(선택): 목록 페이지와 문서 페이지를 새로 만들고 헤더에 다섯 번째 메뉴를 추가한다. 문서가 독립된 목적을 가지므로 탐색이 명확하다. 헌법의 "네 개의 안정적인 경로" 제약을 개정해야 한다.
2. 가이드 하위로: /guide/docs에 넣어 상위 메뉴를 늘리지 않는다. 헌법 제약을 건드리지 않지만, 가이드는 작업법 설명이고 문서는 산출물 원문이라 성격이 섞인다.
3. 적용 근거 페이지 안에: 기존 근거 탐색기에 문서 계층을 더한다. 새 경로가 없지만 근거는 검증된 발췌이고 문서는 전문이라 한 화면에 두 종류가 섞이고, 33편은 탐색기 하나에 넣기에 많다.

데이터 흐름

기존 근거 파이프라인(scripts/verify-evidence.ts → content/generated/evidence.public.json)과 대칭 구조를 따른다.

content/docs-manifest.ts          문서를 명시적으로 선언 (경로·묶음·제목·요약·순서)
        ↓  scripts/verify-docs.ts   (npm run build 앞단)
        읽기 → 공개 안전 검사 → 가림 → 마크다운을 HTML로 변환
        ↓
content/generated/docs.public.json   런타임이 읽는 유일한 소스

글로브가 아니라 명시적 매니페스트를 쓴다. 헌법 원칙 V가 "명시된 파일만 읽는다"를 요구하기 때문이고, 제목·요약·순서를 손으로 잡을 수 있는 이점도 있다. 문서가 늘면 매니페스트에 한 줄을 더하는 것이 공개 결정을 내리는 행위가 된다.

마크다운을 HTML로 바꾸는 일은 빌드 시점에만 한다. 현재 런타임 의존성은 next와 react뿐이며, 변환기를 devDependency로 두어 이 상태를 유지한다.

공개 안전 게이트

가리는 것과 실패시키는 것을 나눈다.

진짜 비밀값은 가리지 않고 실패시킨다. 조용히 가리면 비밀이 있었다는 사실 자체가 사라져서 다음 사람이 원본을 고칠 기회를 잃는다. 반대로 절대 경로와 사설 IP는 문서의 설명 가치를 해치지 않으면서 안전하게 바꿀 수 있으므로 가림으로 처리한다.

허용 URL 목록은 문서 안전 정책 모듈에 상수로 두고 매니페스트와 함께 검토한다. 현재 33편에 등장하는 URL은 https://harness.insapien.co.kr과 그 하위 경로, 그리고 가림 대상인 <로컬>뿐이므로 초기 허용 목록은 사이트 자기 주소 하나로 시작한다.

기존 lib/evidence-validator.ts의 UNSAFE_PUBLIC_PATTERNS를 그대로 쓰지 않는 이유는 그 목록이 모든 URL을 금지하기 때문이다. 근거 발췌에는 맞지만 문서에는 사이트 자기 주소가 정당하게 등장한다. 패턴 정의는 공유하되 문서용 정책을 따로 둔다.

공개 대상

승인 시점의 33편에 이 설계 문서를 더해 34편이며, 네 묶음으로 나눈다.

사전 조사에서 33편 중 23편은 이미 안전 패턴에 걸리지 않았다. 걸린 10편은 URL 7편, 절대경로 2편, 사설 IP 2편이며 진짜 비밀값은 없었다.

화면

/docs 목록은 네 묶음을 순서대로 보여준다. 각 문서는 제목, 한 줄 요약, 원본 경로를 가진다.

/docs/[group]/[slug] 본문은 제목, 원본 경로, 목차, 본문, 이전·다음 문서 링크를 가진다. 모든 경로는 generateStaticParams로 정적 생성한다.

문서 본문의 # 제목은 페이지 h1과 충돌하므로 한 단계씩 낮춰 h2부터 시작한다. 크기는 2026-08-17에 조정한 공통 제목 스케일을 그대로 쓴다. 마크다운 안의 원시 HTML은 차단하고 허용 태그만 통과시킨다. 표와 코드 블록은 각자 가로 스크롤 컨테이너 안에 두어 본문이 가로로 넘치지 않게 한다.

헤더에 "문서"를 다섯 번째 메뉴로 넣는다.

검증

• 단위: 매니페스트 스키마, 가림 규칙, 비밀 패턴에서 빌드 실패, 마크다운 변환의 스크립트 차단과 제목 앵커 부여
• 브라우저: 목록과 본문 렌더, 공개 문서 전편의 200 응답, 제목 위계 유지, 375–1920px 가로 넘침 없음, 접근성 검사
• 배포: 외부 스모크 경로에 /docs 추가

선행 문서 수정

헌법의 기술 및 운영 제약에 "공개 사이트는 /, /guide, /5240lab, /roadmap 네 개의 안정적인 경로를 제공한다"가 박혀 있다. 원칙 II에 따라 구현 전에 다섯 경로로 개정한다. 공개 경로가 느는 변경이므로 원칙 IV에 따라 매뉴얼 영향도 기록한다.

비목표

• 문서 검색과 전문 색인은 만들지 않는다.
• 문서 편집이나 업로드 기능은 만들지 않는다.
• 원본 마크다운 파일을 그대로 내려받게 하지 않는다.
• 저장소의 모든 마크다운을 자동으로 공개하지 않는다. 매니페스트에 선언한 것만 낸다.