preview-prose-audit git:20260916.83c053dA

Immutable. This exact content never changes and is served at /api/v1/blob/2f27fb413c452595.

---
name: preview-prose-audit
metadata:
  internal: true
description: 프리뷰 산문(public/preview/*/preview.html — 라이트·다크 한 파일의 캡션 등 글 전체)이 services/*.md 나 상류가 뒷받침하지 않는 주장을 하는지 대조·판정할 때 쓴다. 판정 근거의 등급, 상류(Claude Design 번들 또는 브랜드 발행물) 확인 절차, 슬러그별 상류 판정표, 그 되돌리기가 남긴 판정 규칙을 담는다. 프리뷰 산문을 고치거나 "md에 없다"를 근거로 프리뷰를 정정하려 할 때 반드시 먼저 읽을 것.
---

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

프리뷰 산문이 `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가 인용한 출처다.

| 슬러그 | 상태 |
| --- | --- |
| `seed-design` | 번들 **없음** — 브랜드 발행물(공개 문서·npm 패키지)에서 직접 만들었다 |
| `class101` | 번들 **있으나 상류 아님** — 번들 README가 스스로를 *"a faithful recreation of CLASS101's open-source Vibrant Design System"* 이라 적고, 출처로 크롤 코퍼스 58쪽 · `vibrant-design.com` · `github.com/pedaling/opensource`(MIT)를 든다. md도 같은 공개 출처 48개를 인용 190개로 쓴다 — **둘이 형제다.** 판정은 브랜드 발행물(공개 문서·오픈소스 코드)로 한다 |
| `vapor-ui` | 번들에서 **만들었으나 전량 뒤집혔다** — md 머리말이 번들을 1차 출처로 밝혔지만 References 5개는 전부 공개(`vapor-ui.goorm.io` · goorm 블로그 · Figma Community · npm · 공개 저장소 `goorm-dev/vapor-ui`). 번들값이 공개 발행값과 크게 어긋나 **토큰 절과 컴포넌트 절을 차례로 교체했다** — `## Colors` 110개(2026-07-29), 그리고 `## Typography` · `## Spacing` · `## Rounded` · `## Elevation & Depth` · `## Components`(2026-08-17, 이슈 292번). 판정은 npm `@vapor-ui/core` 1.3.0 배포본과 **문서 사이트가 서빙하는 CSS 청크** 둘로 하며, 이 둘이 서로를 확인해 준다. 문서 사이트의 props 표는 지연 로드라 수치 출처로 쓸 수 없다 |

| `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 `:322` 가 숫자만 적지 않고
> "공식 타입 스케일 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건이 부재 주장 형태" 로 집계됐으나 그건 사유에 쓰인 어휘를 센 것이고, 실제로 무게를
  지는 근거는 대부분 값·자기모순이었다.
- **"참이다" 가 "되살려야 한다" 를 뜻하지 않는다.** 상류가 사실을 뒷받침해도 유지가 맞을
  수 있다 — **프리뷰 산문은 규범문이 아니라 관찰문**이라는 별개 축이 남기 때문이다. 되돌리기가
  "감사가 참인 것을 지웠다" 만 찾으면 이 축을 놓친다.