Skip to main content

문서 품질 검증 스킬

2부 구성: 1부 자동 검사(명령 실행) → 2부 판단 체크리스트(사람 수준 판단) → 3부 리포트. 기존에 알려진 이슈는 known-issues.md 와 대조해 신규 발생분만 보고한다.

1부. 자동 검사

모든 명령은 저장소 루트에서 실행. 읽기 전용.
검사 범위 주의: ko/*.mdx 는 최상위만 매칭해 ko/dev/·ko/ops/ 의 60여 페이지를 조용히 건너뛴다. 아래 명령들은 모두 ko 를 재귀로 도는 형태로 통일돼 있으니 축약하지 말 것. ko/**/*.mdx 도 zsh 에서만 재귀라 bash 하네스에서는 결과가 달라진다.

1. 고아 파일 / 등록 누락

navigation 스킬(.claude/skills/navigation/SKILL.md)의 고아 검사 스크립트를 실행한다. known-issues.md 의 기준선(28개)보다 늘었으면 신규 고아.

2. 깨진 내부 링크

이것이 정본이다. 앵커(#...), ko/ 밖 경로, 같은 대상의 중복 참조까지 모두 잡는다.
known-issues.md 에 기록된 기존 29건(13개 파일) 과 대조해 신규분만 보고한다. 보조 grep — mintlify 를 못 쓸 때만 쓴다. 고유 대상만 보여주므로 건수가 실제보다 작게 나온다(앵커·ko/ 밖 경로 누락, 중복 참조 dedupe):

3. 외부 이미지 상태 검사

이미지가 대부분 외부 URL(files.cloudtype.io)이므로 404 검사가 필수:
(수십 개 URL 이므로 수 분 걸릴 수 있음. 특정 페이지만 검사하려면 grep 대상을 좁힌다.)

4. frontmatter 완결성

ko/dev/{python,django,flask,fastapi,node,nextjs,nestjs}.mdxicon 누락 7건은 정당한 예외다 — 중첩 그룹이 icon 을 가진다(doc-writing 스킬 frontmatter 규칙 참조). 보고에서 제외한다.

5. 중복 섹션 후보 (동일 h2 제목)

동일 h2 가 여러 파일에 있으면 내용 중복 의심 — 해당 파일들을 열어 실제 중복인지 확인한다. 단, 모델 연동 페이지들의 “API 키 생성하기”나 배포 예제 페이지들의 “템플릿 선택”처럼 구조가 같아서 나오는 정당한 중복이 대부분이므로 반드시 본문을 대조한다. 현재 기준선 29건.

6. 스텁 페이지 검출

40줄 미만이면 스텁 후보. known-issues.md 의 기존 스텁 목록(22개)과 대조.

7. 컴포넌트 관례 위반

리드 Card 는 강한 관례이지만 절대 규칙은 아님 — 위반 페이지는 “권고”로 보고.

8. 용어집 위반 (대표 패턴)

외부 커넥터 페이지(ko/{slack,notion,jira}.mdx)는 페이지 전체가 해당 서비스 맥락이라 줄 단위로는 판별되지 않으므로 경로째 제외한다. 현재 기준선 0건 — 결과가 나오면 신규 위반이다. 전체 용어집은 doc-writing 스킬 참조.

2부. 판단 체크리스트

자동 검사로 잡히지 않는 항목. 페이지를 열어 판단한다:
  • 유형-톤 일치: 페이지 유형(doc-writing 결정 트리 기준)과 실제 톤이 맞는가? 기능 가이드에 마케팅 문구가, 마케팅형에 구현 세부가 섞여 있지 않은가?
  • 주 독자 1명: 이 페이지의 주 독자(의사결정자/사용자/개발자/AI 전문가/관리자)가 명확한가? 두 독자를 동시에 겨냥해 초점이 흐려지지 않았나?
  • 핵심 차별점 연결: AGENTS.md 의 핵심 차별점 5개 중 어느 것을 뒷받침하는지 도입부(Card 리드 또는 첫 문단)에서 드러나는가? 특히 신규 기능 페이지.
  • 여정 정합: 이 페이지가 전제하는 지식(예: 지식베이스 개념)을 다루는 페이지가 사이드바에서 앞에 있는가?
  • 잠재 고객 관점: 처음 보는 사람이 이 페이지만 읽어도 “이 기능이 어떤 업무 문제를 푸는지” 알 수 있는가? 기능 명세만 나열돼 있지 않은가?
  • 스크린샷 최신성: Frame 이미지가 현재 UI 와 다르다는 징후(메뉴명 불일치 등)가 없는가?

3부. 리포트 형식

심각도 3단계 표로 보고. 수정은 별도 승인 후에만 진행한다. 리포트 마지막에 known-issues.md 갱신 필요 여부를 명시한다 (해소된 이슈 발견 시 목록에서 제거, 신규 이슈는 추가).