문서 / docs/superpowers/specs/2026-08-18-guide-document-slots-design.md

가이드 문서 슬롯 설계

문서 타임라인을 작업 순서로 합치고 빈 단계에 남겨야 할 문서를 권장으로 세운 설계.

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

배경

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

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

관점

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

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

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

지금의 슬롯 현황

갈래 단계 슬롯
신규제작 01 요청 계약 비었음 → request.md 권장
신규제작 02 브레인스토밍 design.md
신규제작 03 기능 정의 spec.md
신규제작 04 기술 설계 plan.md
신규제작 05 작업 분해 tasks.md
신규제작 06 격리 구현 작업 보고
신규제작 07 독립 검토 verification-report.md
신규제작 08 매뉴얼 동기화 manual-impact.md — 파일은 있으나 단계에 배선되지 않았다
신규제작 09 통합 배포 deployment-report.md
신규제작 10 재평가 비었음 → reassessment.md 권장
SM 01~09 전부 비었음 → 아래 표대로 권장

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

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

권장 문서

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

갈래·단계 권장 파일 담을 것
신규 01 요청 계약 request.md 목적과 비목표, 성공 조건, 외부 효과
신규 10 재평가 reassessment.md 같은 기준의 재측정, 남은 위험, 다음 개선 항목
SM 01 현행 확인 current-state.md 대상 문서와 마지막 확인일, 그 뒤 커밋, 유효·낡음 판정
SM 02 개선 정의 change-definition.md 고칠 절과 더할 절 목록, 하지 않을 것
SM 03 영향 분석 impact-analysis.md 영향 목록 — 항목마다 확인함·영향 없음·확인 필요
SM 04 기술 설계 plan.md 기존 동작을 깨지 않는 방법, 되돌리는 방법
SM 05 작업 분해 tasks.md 작업마다 되돌리는 방법
SM 06 구현 task-report.md 선언한 범위 안의 변경 기록
SM 07 검증 verification-report.md 새 동작과 기존 동작 불변의 증거
SM 08 문서·매뉴얼 갱신 manual-impact.md 지목한 절의 이행 결과, 갱신된 확인일
SM 09 배포·운영 deployment-report.md 배포 기록, 되돌아갈 기준점

데이터 구조

문서 정보의 단일 출처를 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에 영향과 조치를 기록한다. 공개 경로 다섯은 그대로이므로 헌법의 경로 조항은 건드리지 않는다.

맨 위로