Preview Prose Audit

프리뷰 산문 감사 — 판정 근거의 등급

프리뷰 산문이 services/*.md가 뒷받침하지 않는 주장을 하는지 사람이 대조하는 작업이 2026-08-04 ~ 08-17 에 걸쳐 이어졌다. 그 판정에는 근거 등급이 있고, 낮은 등급을 근거로 쓰면 프리뷰를 망가뜨린다.

• ❌ "md에 없음"은 결함의 근거가 아니다. 번들을 거친 항목에서 md와 프리뷰는 둘 다 같은 Claude Design 핸드오프 번들에서 갈라졌고, md는 컴포넌트 상태·수치·변형명을 상당 부분 옮기지 않은 손실 전사다. md의 침묵은 "프리뷰가 지어냈다"가 아니라 "md가 안 적었다"인 경우가 많다.
• ✅ "md 또는 상류가 반증함"만 결함이다. 값이 다르거나, 다른 컴포넌트의 값을 귀속했거나, 상류에 그 이름이 없을 때.

상류를 확인하는 법: DesignSync MCP(list_projects → list_files → get_file)로 슬러그별 Claude Design 프로젝트를 읽는다. 거의 모든 카탈로그 항목에 대응 프로젝트가 있다.

다만 번들이 상류인 것은 md가 번들에서 나왔을 때뿐이다. md가 브랜드 발행물(공개 문서· 오픈소스 저장소·npm 패키지)에서 직접 만들어졌다면 그것들이 상류이고 번들은 형제다 — 같은 출처에서 갈라진 또 하나의 재구성물이라 md를 뒤엎을 권위가 없다. md의 ## References 를 먼저 보라: 번들을 가리키지 않고 공개 URL만 열거하면 이 경우다.

/design-md 스킬이 처음부터 만든 항목은 또 다르다 — 스킬은 승인된 md를 프리뷰 저자에게 넘겨 프리뷰를 md에서 만든다. 그 항목에서 확인할 곳은 번들이 아니라 md와 md가 인용한 출처다.

이 문서는 산문이 참인가만 다룬다. 남아도 되는가는 다른 자리에 있다. 한 문장이 참이면서 남을 자격이 없을 수 있고, 필요하면서 거짓일 수도 있다 — 한쪽 판정이 다른 쪽을 대신하지 못한다. 남아도 되는가는 .claude/skills/design-md/references/rubric-preview.md 의 ## Explanatory prose 가 advisory 로 다룬다(warn 만 내고 10점 총점은 건드리지 않는다). 그 절은 질문이 아니라 닫힌 허용 목록이다 — 시연 자체의 글(히어로 브랜드명·태그라인·CTA, 섹션 제목, 컴포넌트·목업 안 카피) 말고 화면에 둘 수 있는 글은 catalog-disclaimer 띠 · catalog-dummy 더미 데이터 표기 · catalog-attribution 줄 · 컴포넌트·상태 이름표(스펙·값 라벨 포함) · 조작 안내 · 이미지 자리 표시뿐이다. 그 밖의 설명 문장은 전부 디자인 설명 캡션이라 뺀다.

예전 기준은 "이 말을 design.md 가 할 수 있는가?" 였고, 못 하는 말(빌려 온 값 · 반응형 거동 · 토큰에서 벗어난 자리 · 접근성 단서)은 남겼다. #499 가 그 예외를 닫는다 — LG전자에는 그 예외에 기대 남은 설명 노트가 12개 있었고(리뷰의 "가정임을 밝혀라" 지적에는 그중 한 노트에 문장을 덧붙여 답했다), 다음 단계에서 12개를 모두 지웠다. 가정을 밝혀야 하면 문장이 아니라 그 요소의 짧은 표지(활성 (가정))로 한다. 요소가 목업 .screen 안이면 표지는 목업 밖 셀 이름표·상태 이름표에 단다(더미 데이터 표기와 같은 규칙). 판정 근거도 "한 화면에 세 번"이 아니다 — Live Preview · Tokens · DESIGN.md 세 탭은 배타적이라 (src/routes/services/$slug.tsx 의 DetailTabsList) md 는 탭 하나 거리에 있다. 근거는 "프리뷰의 일은 설명이 아니라 시연" 이다.

리멤버가 렌더 텍스트의 61% 가 설명인 채 10/10 을 받은 것이 그 축이 없던 시절의 결과다(이슈 #396). 여기서 "참이다" 를 확인했다고 그 문장이 남을 자격을 얻는 것은 아니다.

| wanted | 번들 있고 상류가 맞으나 항목에 따라 진다 — md 가 번들이 아니라 브랜드 발행물(몽타주 문서)을 대조한 블록이 있고, 그 자리에서는 번들 README 가 브랜드 발행값과 어긋난다. 아래 타입 스타일 수 사례 |

이 표는 발견되는 대로 늘어난다 — 새 슬러그를 감사하기 전에 md의 ## References 를 먼저 확인하고, 번들이 상류가 아니면 여기에 적을 것.

DesignSync를 못 쓰면 판정하지 말 것. 이 규칙은 상류 확인을 요구하는데 그 MCP는 모두에게 열려 있지 않다. 대안 경로는 두 가지다 — 슬러그의 크롤 캐시 (.claude/cache/design-md/<slug>/, gitignore됨)와 브랜드 발행물. 셋 다 없으면 결함으로 올리지 말고 유보로 남긴다 — 상류를 열어 볼 수 없었다고 적는다. 확인할 수 없는 것을 "md에 없으니 결함"으로 처리하는 것이 바로 이 절이 막으려는 오류다.

상류가 프리뷰를 뒷받침하는데 md가 비어 있으면 고칠 것은 프리뷰가 아니라 md다.

다만 상류가 늘 이기는 건 아니다. 이 규칙이 상류를 앞세우는 이유는 md가 번들의 손실 전사이기 때문이다 — 그 관계가 성립하지 않으면 적용되지 않는다. 번들도 재구성물이라 브랜드 발행물과 어긋날 수 있다. 상류를 확인했는데 md와 다르면 어느 쪽이 브랜드 발행물에 더 가까운가로 가른다.

단, 그 판단은 브랜드 발행물을 직접 열어서 한다. md가 "브랜드 발행물과 대조했다"고 적어 둔 것만으로는 부족하다 — 그건 md의 자기 서술이고, 루트 문서(CLAUDE.md)의 「인용은 존재가 아니라 내용 일치」 원칙이 바로 그것을 검사 대상으로 삼는다. md의 주장을 근거로 md를 신뢰하면 순환이다. 인용된 URL을 열어 값을 세어 보고, 확인하지 못하면 어느 쪽이 맞다고도 정하지 말고 유보한다.

사례 (wanted 타입 스타일 수). 번들 README는 18, md는 19로 적는다. [src:5](몽타주 공식 타이포그래피 문서)를 직접 열어 세었더니 19개였고 md의 표와 이름까지 일치했다. 즉 번들 README가 브랜드 발행물과 어긋난 경우이고, "상류 우선"만 기계적으로 적용하면 브랜드 공식값을 버리고 번들값으로 되돌리게 된다. 공식 표가 싣는 19개는 Display 1·2·3 / Title 1·2·3 / Heading 1·2 / Headline 1·2 / Body 1·2 × Normal·Reading / Label 1 × Normal·Reading · Label 2 / Caption 1·2 다 (montage.wanted.co.kr/docs/foundations/base-material/typography). md 가 번들이 아니라 브랜드 발행물을 대조한 자리라 손실 전사 관계가 성립하지 않고, 그래서 "상류 우선" 도 적용되지 않는다. md 의 ## Typography 절이 숫자만 적지 않고 "공식 타입 스케일 19행과 대응하며 57개 값 중 56개가 일치한다" 고 밝힌 것이 단서였다 — 그래도 자기 서술만으로는 부족해 [src:5] 를 직접 열어 세었다.

이 규칙은 사고 후에 생겼다. 2026-08-06 전수 조사에서 착지한 산문 정정 84건 중 33건만 정당했다. 나머지 50건을 반증 검증에 걸어 30건이 감사 오탐으로 확증, 19건 기각, 1건 유보가 나왔다. 집행하면서 확증은 31로 움직였다 — 기각 판정도 부재 주장에 기대면 확증과 똑같이 틀리기 때문이다. 대표 사례: kyobobook의 State — hover를 "md에 hover가 0건"이라며 pressed로 바꿨는데 번들에 <span>Hover</span>와 .primary.hover{background:blue-800}이 그대로 있었다. greeting은 Drawer 카드를 Side panel로 개명했는데 번들에 Drawer.jsx·drawer.card.html·Drawer.prompt.md가 있다.

봇 리뷰 3~4라운드가 이 오류를 전부 통과시켰다 — 리뷰어도 md만 근거로 삼아 같은 전제를 공유했기 때문이다. 같은 전제를 공유한 검증은 그 전제를 검사하지 못한다. 값을 고치는 것보다 이름을 바꾸는 정정이 더 위험하다 — 값은 틀리면 눈에 띄지만 이름은 굳어져 다음 감사가 그 이름을 기준으로 삼는다.

되돌리기는 종결됐다 (2026-08-17)

확증된 감사 오탐을 되돌렸고(bezier · toss · socar · 11st · greeting · wanted · gmarket · vapor-ui), 기각 19건도 사유 전문으로 재검토했으며, 상류를 열어 보지 못해 유보로 남았던 2건도 해소했다. 열려 있는 건은 없다.

다만 확증된 감사 오탐이 전부 되돌려진 것은 아니다. greeting 의 Doodlin 워드마크 카드 1건은 확증된 감사 오탐인데도 되살리지 않고 종결했다 — 빈 카드 제거로 이미 걷혔고, 복원하려면 프리뷰를 자체 완결로 만들면서 싣지 않기로 한 브랜드 PNG 자산이 필요하기 때문이다. 아래 넷째 규칙의 실례이고, 판정의 수와 집행의 수를 섞지 말 것. 자산 정책이 바뀌어 되살리게 되면 그 카드를 두 차례 고친 문구를 따로 되돌리지 말고 상류 카드를 처음부터 다시 옮길 것.

진행 상황을 슬러그별로 들고 있던 대장 문서는 그래서 지웠다 — 건별 판정 근거와 되돌린 문구 전문은 git 히스토리와 그 PR 들에 남는다. 여기에 슬러그 목록이나 PR 번호를 다시 적지 말 것. 대장을 따로 둔 이유가 그것이었고, 대장이 스스로 경고했듯 문서에 적힌 상태는 늘 낡는다.

그 캠페인이 남긴 판정 규칙 넷은 다음 감사에도 그대로 적용된다.

• 기각도 근거 등급으로 재검토한다. 반증 검증의 기각 판정이 부재 주장에 기대면 확증과 똑같이 틀린다. 경로·파일 이름을 근거로 든 기각은 그 경로가 어느 트리 것인지 먼저 확인할 것.
• 결론만 보고 통째로 채택하거나 기각하지 말 것. 한 판정 안에 맞는 근거와 틀린 근거가 섞여 있다(bezier Divider). 테마별로 갈리기도 한다 — bezier Modal 의 라이트 scrim 40% 는 번들이 뒷받침해 감사 오탐이지만 다크의 55% 는 근거가 없어 정당한 정정이었다. 양 테마를 같은 값으로 되돌리지 말 것.
• 기각 사유를 어휘로 분류하지 말 것 — 세어서는 알 수 없고 읽어야 한다. 한때 "16건이 부재 주장 형태" 로 집계됐으나 그건 사유에 쓰인 어휘를 센 것이고, 실제로 무게를 지는 근거는 대부분 값·자기모순이었다.
• "참이다" 가 "되살려야 한다" 를 뜻하지 않는다. 상류가 사실을 뒷받침해도 유지가 맞을 수 있다 — 프리뷰 산문은 규범문이 아니라 관찰문이라는 별개 축이 남기 때문이다. 되돌리기가 "감사가 참인 것을 지웠다" 만 찾으면 이 축을 놓친다.