명세를 docs/memo-spec.md로 분리 + 스키마 드리프트 검사

[cbcruk]

CLAUDE.md가 성격이 다른 셋을 한 파일에서 하고 있었다 — 판단(작성 원칙), 명세(필드·값), 기록(변경 이력). 오늘 하루에 321 → 389줄이 됐고 그중 명세만 130줄이었다.

쪼갠 기준: 성격/안정성

파일	담는 것	변화
CLAUDE.md	판단 — 작성 원칙, 압축, 템플릿, 워크플로우	389 → 305줄
docs/memo-spec.md	명세 — 필드, type·status, 태그·각주, 계보, 링크 부식	신규
577.md	왜 그렇게 정했나	기존

CLAUDE.md의 명세 자리에는 쓸 때 바로 필요한 필수 필드 5개만 남기고 나머지는 스펙을 가리킨다. 선택 필드 표를 두 곳에 두면 그 자체가 드리프트다.

스펙에만 넣은 두 절

검사 체계 — 기계와 사람의 경계

린터가 조용한 게 곧 문제가 없다는 뜻이 아니다. 오늘 사각지대를 두 번 만났다.

무엇	왜 기계가 못 하나	표시
저자가 존댓말로 쓴 자기 글	번역문과 같은 신호로 잡힌다	voice: author
과압축·자기 반복	부풀린 문장은 잡지만 눌러 담은 문장은 못 잡는다	(없음)
계보인가 단순 유사인가	URL이 겹쳐도 계보가 아닐 수 있다	parent를 걸지 않음
링크가 "확인 불가"일 때	봇 차단과 실제 소멸을 구분 못 한다	브라우저로 확인

채택하지 않은 것 — 거절 근거

같은 논의를 반복하지 않으려고 숫자와 함께 남겼다.

필드	안 쓰는 이유
stale_after	버전을 고정한 메모가 10개뿐. 만료를 선언할 대상이 없고 시간축도 오염됐다
resource	URL이 2개 이상인 메모가 359개. 대상을 하나로 특정할 수 없다
verified	단일 저자라 전부 같은 값
관계 레이어 추가	parent조차 오래 0이었다. 스키마가 부족한 게 아니라 후보를 못 보고 있었다

드리프트 검사 — 넣자마자 실제 드리프트가 나왔다

문서만 늘리면 5번째 드리프트 지점이 될 뿐이라, lint:memo에 명세 ↔ 스키마 대조를 넣었다. 필드 표를 마커(fields:start/fields:end)로 감싸고 이름·필수 여부를 content.config.ts와 비교한다.

embed가 스키마에 있고 11개 메모가 쓰는데 CLAUDE.md에는 없었다.

"드리프트 표면이 4개"라는 게 추상적 우려가 아니라 이미 벌어진 일이었다. 스펙에 정확히 문서화했다(CodePen·StackBlitz 같은 실행 예제 링크).

세 방향으로 검증했다:

필드 삭제        → ✗ 스키마에 있는 `embed` 이 필드 표에 없다
필수 여부 뒤집기 → ✗ `tags` 의 필수 여부가 스키마와 다르다 (문서: 선택, 스키마: 필수)
없는 필드 추가   → ✗ 필드 표의 `stale_after` 이 스키마에 없다

스펙에 임계값은 적지 않았다

"무엇을 검사하는가"만 적고 "어떤 숫자로"는 코드에 뒀다 — 예를 들어 lint:voice의 존댓말 3곳 같은 임계값. 적으면 정확해지지만 튜닝할 때마다 두 곳을 고쳐야 한다. 지금 방향은 드리프트 표면을 늘리지 않는 쪽이다.

확인

pnpm lint:memo   →  메모 542개 검사 — 오류 0, 경고 0
pnpm lint:voice  →  542개 중 0개에 남의 문장이 남아 있다
pnpm build       →  통과

스킬 두 개(create-memo, consolidate-memos)의 참조도 새 위치로 갱신했다.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Qv2pQrCq9z1GaxxDu2vohK

---

Generated by Claude Code

[bolt-new-by-stackblitz]

Run & review this pull request in StackBlitz Codeflow.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
cbcruk-github-io	Ready	Preview, Comment	Jul 29, 2026 6:22am