콘텐츠 일관성 검증기
개요
여러 문서 소스(웹사이트, GitHub 저장소, 로컬 문서) 간의 어조, 용어, 서식 및 구조적 일관성을 확인합니다. 심각도별로 분류된 읽기 전용 불일치 보고서를 생성하며, 파일 경로와 라인 번호를 포함한 실행 가능한 수정 제안을 제공합니다.
예시
- 사전 릴리스 감사: 새 버전을 태깅하기 전에 검증기를 실행하여 README, 문서 사이트, 변경 로그 간의 버전 불일치를 발견하십시오. 예를 들어 웹사이트에는 v2.1.0이라고 나와 있지만 GitHub README에는 여전히 v2.0.0이 참조되어 있는 경우.
- 리브랜딩 후 확인: 제품 이름을 변경하거나 용어를 업데이트한 후(예: "plugin"을 "extension"으로) 모든 문서, 랜딩 페이지, 기여 가이드에서 새 용어가 일관되게 사용되는지 검증합니다.
- 온보딩 검토: 새로운 기여자가 혼란스러운 문서를 신고하면 일관성 검사를 실행하여 문서 소스 전반에서 상충되는 기능 주장, 오래된 연락처 정보, 누락된 섹션을 찾아냅니다.
사전 요구 사항
- 최소 두 개의 콘텐츠 소스(웹사이트, GitHub 저장소, 로컬 문서 디렉토리)에 접근 가능해야 함
- 원격 URL(배포된 사이트, GitHub 원시 콘텐츠)에 대해 WebFetch 권한이 구성되어 있어야 함
- 로컬 문서가 인식 가능한 경로(
docs/,claudes-docs/,internal/)에 저장되어 있어야 함
지침
- 소스 발견 — 빌드 디렉토리(
dist/,build/,public/,out/,_site/), GitHub README/CONTRIBUTING 파일, 로컬 문서 폴더를 스캔합니다:find . -maxdepth 3 -name "README*" -o -name "CONTRIBUTING*" | head -20 ls -d docs/ claudes-docs/ internal/ 2>/dev/null - 각 소스에서 구조화된 데이터 추출: 버전 번호, 기능 설명, 제품명, 태그라인, 연락처 정보, URL, 기술 요구사항:
grep -rn 'v[0-9]\+\.[0-9]\+' docs/ README.md grep -rn -i 'features\|capabilities' docs/ README.md - 추출 확인 — 소스당 최소 3개의 데이터 포인트를 확인합니다. 소스가 비어 있으면 계속하기 전에 오류 처리 표를 확인하십시오.
- 비교 매트릭스 구축 — 각 소스를 다른 모든 소스와 쌍으로 비교합니다(웹사이트 vs GitHub, 웹사이트 vs 로컬 문서, GitHub vs 로컬 문서):
diff <(grep -i 'version' README.md) <(grep -i 'version' docs/overview.md) - 불일치 분류:
- 치명적(Critical): 상충되는 버전 번호, 모순되는 기능 목록, 일치하지 않는 연락처 정보, 깨진 상호 참조
- 경고(Warning): 일관되지 않은 용어(예: "plugin" 대 "extension"), 한 소스에서 누락된 정보, 오래된 날짜
- 정보(Informational): 스타일 차이, 플랫폼별 표현, 상세 수준 차이
- 신뢰도 우선순위 적용: 웹사이트(가장 권위 있음) > GitHub(개발자 대상) > 로컬 문서(내부용)
- 보고서 생성 — Markdown 형식으로: 실행 요약, 쌍별 비교 테이블, 용어 일관성 매트릭스, 파일 경로와 라인 번호가 포함된 우선순위별 조치 항목
- 저장 —
consistency-reports/YYYY-MM-DD-HH-MM-SS.md에 저장합니다.
보고서 형식
# 일관성 보고서 — YYYY-MM-DD
## 실행 요약
| 심각도 | 개수 |
|----------|-------|
| 치명적 | 2 |
| 경고 | 5 |
| 정보 | 3 |
## 웹사이트 vs GitHub
| 필드 | 웹사이트 | GitHub | 심각도 |
|-------------|---------------|---------------|----------|
| 버전 | v2.1.0 | v2.0.0 | 치명적 |
| 기능 X | 나열됨 | 누락됨 | 경고 |
## 조치 항목
1. **치명적** — `README.md:14` 버전을 v2.0.0 → v2.1.0으로 업데이트
2. **경고** — "기능 X"를 `README.md` 기능 목록에 추가
오류 처리
| 오류 | 원인 | 해결 방법 |
|---|---|---|
| 웹사이트 콘텐츠에 접근 불가 | URL이 4xx/5xx를 반환하거나 빌드 디렉토리 없음 | 사이트가 배포되었는지 확인하거나 로컬 빌드 실행; WebFetch 권한 확인 |
| GitHub API 속도 제한 | 짧은 시간 내 너무 많은 요청 | 일시 중지 후 재설정 시간이 지나면 재시도; 인증된 요청 사용 |
| 문서 디렉토리 없음 | 예상 경로가 존재하지 않음 | 작업 디렉토리 확인; 문서 경로를 명시적으로 지정 |
| 빈 콘텐츠 추출 | 클라이언트 측 렌더링이 fetch에 표시되지 않음 | 라이브 URL 대신 로컬 빌드 출력 디렉토리 사용 |
| diff 명령 실패 | 파일 경로에 특수 문자가 포함됨 | diff 및 grep에 전달되는 모든 파일 경로를 따옴표로 감싸기 |
리소스
- 콘텐츠 소스 발견 로직:
${CLAUDE_SKILL_DIR}/references/how-it-works.md - 신뢰도 우선순위 및 검증 타이밍:
${CLAUDE_SKILL_DIR}/references/best-practices.md - 사용 사례 워크스루:
${CLAUDE_SKILL_DIR}/references/example-use-cases.md