consistency-check

name	consistency-check
description	백엔드 면접 가이드 레포지토리의 구조적 일관성을 검증하는 스킬. README 목차와 실제 파일 간의 불일치, 깨진 링크, 누락 파일, 목차 정합성을 확인한다. '목차 확인해줘', '파일 구조 검증해줘', '링크 깨진 거 없는지 확인해줘', '일관성 체크해줘' 등의 요청에 트리거. 새 문서 추가 후 전체 구조를 점검할 때 반드시 사용할 것. 콘텐츠의 기술적 품질 리뷰에는 트리거하지 않는다 — content-review 스킬을 사용할 것.

Consistency Check — 구조 일관성 검증

면접 가이드 레포지토리의 README 목차, 파일 구조, 문서 간 참조의 일관성을 검증하는 스킬.

트리거 범위

이 스킬은 레포지토리의 구조적 일관성 검증에만 트리거한다.

• 트리거 O: "목차 확인해줘", "파일 구조 검증해줘", "링크 깨진 거 확인해줘"
• 트리거 X: "이 문서 기술적으로 검토해줘" → content-review (품질 리뷰)
• 트리거 X: "이 문서 보강해줘" → content-generation (콘텐츠 수정)
• 트리거 X: "문서 만들고 구조까지 점검해줘" → interview-guide (다단계 워크플로우)

검증 항목

1. README ↔ 파일 매핑

프로젝트 구조를 동적으로 발견한다 (하드코딩 금지):

1. Glob("*/README.md")로 카테고리 디렉토리를 식별 (.claude/, _workspace/, scripts/ 등 비콘텐츠 디렉토리 제외)
2. 루트 README.md의 ## 목차에서 카테고리 링크를 추출하여 비교
3. 각 카테고리 README.md의 목차에서 참조하는 .md 파일이 실제로 존재하는지 확인
4. 카테고리 디렉토리의 .md 파일 중 README에 등록되지 않은 것이 있는지 확인

2. 문서 내 앵커 링크 검증

각 문서의 목차(## 목차)에 있는 앵커 링크가 문서 내 실제 헤딩과 일치하는지 확인한다.

검증 방법:

1. 목차의 [텍스트](#앵커) 패턴을 추출
2. 문서 내 #, ##, ### 헤딩을 추출
3. 앵커가 해당 헤딩으로 변환 가능한지 확인

3. 문서 간 상호 참조

문서 내에서 다른 문서를 참조하는 상대 링크가 유효한지 확인한다.

검증 대상:

• [텍스트](파일명.md) 형식의 같은 디렉토리 내 참조
• [텍스트](../다른카테고리/파일명.md) 형식의 카테고리 간 참조

4. Front Matter 검증

모든 콘텐츠 .md 파일(README 포함)에 YAML front matter가 존재하는지 확인한다.

콘텐츠 문서 필수 필드: title, description, parent, nav_order

• parent 값이 해당 카테고리 README의 title과 정확히 일치하는지
• 같은 카테고리 내 nav_order 중복이 없는지

카테고리 README 필수 필드: title, description, nav_order, has_children, has_toc, permalink

5. 파일명 컨벤션

규칙	패턴	예시
소문자	[a-z][a-z0-9-]*\.md	caching.md
하이픈 구분	복합어는 하이픈	cloud-computing.md
영문	한국어 파일명 금지	messaging-system.md
README	카테고리 인덱스	README.md (대문자)

6. AGENTS.md 규칙 검증

• 미작성 문서에 대한 링크가 없는지 (링크 대신 "작성 예정"으로 텍스트만 나열해야 함)
• README.md가 카테고리 인덱스로서의 기본 구조(# 제목 → ## 소개 → ## 목차)를 따르는지

워크플로우

Step 1: 스크립트 우선 실행

python3 scripts/check_markdown_links.py

이 스크립트는 앵커 링크와 파일 링크의 존재 여부를 자동 검증한다. 결과:

• "OK" → 링크/앵커 문제 없음. Step 3으로 이동.
• 오류 목록 → Step 2에서 처리.

Step 2: 스크립트 발견 문제 분류 및 처리

문제 유형	자동 수정	처리 방법
앵커 링크 불일치	가능	앵커를 실제 헤딩에 맞게 수정
존재하지 않는 파일 링크	경우에 따라	오타면 수정, 미작성이면 링크를 텍스트로 변경
미등록 파일	가능	README 목차에 추가

Step 3: 의미적 검증 (스크립트 범위 밖)

스크립트가 잡지 못하는 항목을 수동 확인:

1. 파일명 컨벤션 준수 여부
2. Front matter 존재 여부 및 필수 필드 정합성 (title, description, parent, nav_order)
3. README 형식 일관성 (front matter 포함)
4. 루트 README ↔ 카테고리 디렉토리 일치
5. "작성 예정" 항목의 형식 (AGENTS.md 규칙)
6. 카테고리 간 중복 주제 여부

Step 4: 자동 수정 실행

수정 가능한 문제를 직접 수정한다. 수정 후 스크립트를 다시 실행하여 검증한다.

주의: 콘텐츠 파일 누락은 수정하지 않고 보고만 한다 (content-writer 영역).

Step 5: 보고서 생성

검증 결과를 구조화된 보고서로 출력한다. content-reviewer 에이전트의 Output Contract 참조.

에러 핸들링

• 빈 디렉토리는 보고서에 명시한다
• 바이너리 파일은 건너뛴다
• README가 없는 카테고리 디렉토리는 경고로 보고한다
• scripts/check_markdown_links.py가 실행되지 않으면 수동으로 전체 검증한다