가이드 문서 슬롯 설계

작성일: 2026-08-18 상태: 사용자 승인(문서 타임라인 폐지, 단계별 문서 슬롯, 결번은 권장으로 하이라이트)

배경

/guide는 같은 것을 두 절에 나눠 보여주고 있다. 02 문서 타임라인은 네 문서 (design·spec·plan·tasks)를 작성 시점과 승인 게이트와 함께 세우고, 03 작업 순서는 같은 네 문서를 신규제작 10단계 중 2~5단계로 다시 세운다. 읽는 사람에게는 별개 개념처럼 번호가 붙지만 실제로는 후자의 부분집합이다.

나뉜 대가는 문구 이원화다. 같은 관문이 implementationDocuments[].gate와 executionDetails[].gate에 별개 리터럴로 두 벌 있다. 한쪽만 고치면 조용히 어긋나고, 그 어긋남은 이미 /docs로 샌다 — content/journey.ts의 gateForDocType은 네 단계 게이트를 문서 쪽에서, gateForStep은 나머지를 작업순서 쪽에서 끌어오기 때문에 한 화면에 두 어투가 섞인다.

관점

하네스는 단계마다 남기는 MD 문서로 정의된다. 그러므로 화면의 단위는 "문서 목록"이 아니라 단계이고, 단계마다 문서 슬롯이 하나 있다.

• 슬롯이 채워져 있다 — 그 문서가 실제로 있다. 실물로 가는 문을 연다.
• 슬롯이 비어 있다 — 그 단계가 남겨야 할 문서가 아직 없다. 무엇을 써야 하는지 권장하고 하이라이트한다. 잘못이 아니라 아직 채워지지 않은 자리다.

이 관점을 적용하면 신규제작 쪽에도 빈 슬롯이 드러난다. 지금까지는 문서 넷만 세웠기 때문에 보이지 않았다.

지금의 슬롯 현황

08은 결번이 아니라 배선 누락이다. 이번에 잇는다. 신규제작의 진짜 결번은 01과 10 둘이다.

SM이 전부 비어 있는 것은 실수가 아니다. 이 여정은 trace: "attempted"이고, 2026-08-18 파일럿이 1단계에서 걸려 완주하지 못했다. 자취가 없는 자리에 문서를 지어내지 않는다는 규칙은 유지하되, 자취 대신 권장을 세운다 — 빈칸을 감추지 않고 빈칸이라고 말하는 것이 이 사이트의 방식이다.

권장 문서

SM의 4~9단계는 신규제작과 같은 파일명을 쓴다. 같은 일을 다른 이름으로 두 벌 만들지 않는다. SM 고유는 앞의 셋뿐이다.

데이터 구조

문서 정보의 단일 출처를 content/guide.ts의 stageDocuments로 옮긴다. 키는 여정 단계 id다.

stageDocuments: Record<stageId, {
  filename: string      // 화면에 그대로 보이는 파일명
  purpose: string       // 이 문서가 무엇을 담는가
  gate?: string         // 이 문서가 통과시켜야 하는 관문(있을 때만)
  example?: { group, slug }   // 실물이 있으면 /docs의 그 문서
}>

example이 있으면 채워진 슬롯, 없으면 권장 슬롯이다. 판정은 데이터 한 곳에서 나온다 — 화면과 검증이 같은 값을 본다.

implementationDocuments는 없앤다. 그 네 항목의 gate는 stageDocuments로 옮기고, content/journey.ts의 gateForDocType은 새 출처를 읽는다. 게이트 문구가 두 벌로 갈라지던 경로가 이로써 닫힌다.

기존 앵커 doc-type-{design|spec|plan|tasks}는 그대로 유지한다. /docs의 guideAnchorByStage가 이 앵커로 링크하고 있어 바꾸면 딥링크가 죽는다.

화면

02 문서 타임라인 절을 없앤다. 목차는 여섯에서 다섯으로 줄고, 작업 순서가 02가 된다.

두 갈래 패널의 각 단계 카드 안, 통과 조건 아래에 슬롯을 그린다.

옛 타임라인이 갖고 있던 "작성 시점"은 옮기지 않는다. 단계 번호가 이미 시점을 말하고 있고, 그것을 다시 적는 것이 바로 이 통합이 없애려는 중복이다. 승인 게이트도 옮기지 않는다 — 단계 카드의 "통과 조건"이 이미 그 자리에 있다.

• 채워짐 — 파일명(코드체)과 "실제 문서 보기" 링크, 목적 한 줄.
• 권장 — 점선 테두리, 권장 라벨, 파일명, "이 단계는 이 문서를 남겨야 합니다"와 담을 것 한 줄. 실패색이 아니라 강조색을 쓴다.

나중에 확인하는 방법

권장이 말로만 남지 않게 검증에 건다. scripts/verify-content.ts에 다음을 더한다.

1. validateStageDocuments — example이 있는 슬롯은 그 group/slug가 /docs 스냅샷에 실재해야 한다. 없으면 빌드 실패. (지금의 validateGuideDocumentExamples를 대체한다.)
2. 권장 문서 현황 보고 — example이 없는 슬롯을 파일명과 함께 목록으로 출력한다. 실패시키지 않는다. 아직 쓰지 않은 것은 잘못이 아니라 남은 일이다.

권장 문서가 실제로 작성되어 매니페스트에 오르면 example을 채우는 것만으로 슬롯이 실물로 바뀐다. 그 전후를 비교하면 "추천한 문서가 실제로 추가되었는가"가 검증 출력으로 바로 보인다.

검토한 다른 방향

• 두 절을 유지하고 게이트만 단일 출처화 — 가장 싸지만 읽는 사람에게는 여전히 같은 것이 두 번 나온다. 사용자가 통합으로 결정했다.
• 작업 순서에 /docs의 실물 18편을 전부 나열 — 가이드가 /docs를 다시 그리게 되어 "같은 말을 두 곳에서 관리하지 않는다"는 규칙을 새로 어긴다. 슬롯당 대표 1종만 세우고 깊이는 /docs가 감당한다.

매뉴얼 영향

manual-impact: affected — /guide의 절 구성과 앵커가 바뀐다. docs/manual-impact.md에 영향과 조치를 기록한다. 공개 경로 다섯은 그대로이므로 헌법의 경로 조항은 건드리지 않는다.