| name | consistency-check |
| description | 백엔드 면접 가이드 레포지토리의 구조적 일관성을 검증하는 스킬. README 목차와 실제 파일 간의 불일치, 깨진 링크, 누락 파일, 목차 정합성을 확인한다. '목차 확인해줘', '파일 구조 검증해줘', '링크 깨진 거 없는지 확인해줘', '일관성 체크해줘' 등의 요청에 트리거. 새 문서 추가 후 전체 구조를 점검할 때 반드시 사용할 것. 콘텐츠의 기술적 품질 리뷰에는 트리거하지 않는다 — content-review 스킬을 사용할 것. |
Consistency Check — 구조 일관성 검증
면접 가이드 레포지토리의 README 목차, 파일 구조, 문서 간 참조의 일관성을 검증하는 스킬.
트리거 범위
이 스킬은 레포지토리의 구조적 일관성 검증에만 트리거한다.
- 트리거 O: "목차 확인해줘", "파일 구조 검증해줘", "링크 깨진 거 확인해줘"
- 트리거 X: "이 문서 기술적으로 검토해줘" → content-review (품질 리뷰)
- 트리거 X: "이 문서 보강해줘" → content-generation (콘텐츠 수정)
- 트리거 X: "문서 만들고 구조까지 점검해줘" → interview-guide (다단계 워크플로우)
검증 항목
1. README ↔ 파일 매핑
프로젝트 구조를 동적으로 발견한다 (하드코딩 금지):
Glob("*/README.md")로 카테고리 디렉토리를 식별 (.claude/, _workspace/, scripts/ 등 비콘텐츠 디렉토리 제외)- 루트
README.md의 ## 목차에서 카테고리 링크를 추출하여 비교
- 각 카테고리
README.md의 목차에서 참조하는 .md 파일이 실제로 존재하는지 확인
- 카테고리 디렉토리의
.md 파일 중 README에 등록되지 않은 것이 있는지 확인
2. 문서 내 앵커 링크 검증
각 문서의 목차(## 목차)에 있는 앵커 링크가 문서 내 실제 헤딩과 일치하는지 확인한다.
검증 방법:
- 목차의
[텍스트](#앵커) 패턴을 추출
- 문서 내
#, ##, ### 헤딩을 추출
- 앵커가 해당 헤딩으로 변환 가능한지 확인
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: 의미적 검증 (스크립트 범위 밖)
스크립트가 잡지 못하는 항목을 수동 확인:
- 파일명 컨벤션 준수 여부
- Front matter 존재 여부 및 필수 필드 정합성 (
title, description, parent, nav_order)
- README 형식 일관성 (front matter 포함)
- 루트 README ↔ 카테고리 디렉토리 일치
- "작성 예정" 항목의 형식 (AGENTS.md 규칙)
- 카테고리 간 중복 주제 여부
Step 4: 자동 수정 실행
수정 가능한 문제를 직접 수정한다. 수정 후 스크립트를 다시 실행하여 검증한다.
주의: 콘텐츠 파일 누락은 수정하지 않고 보고만 한다 (content-writer 영역).
Step 5: 보고서 생성
검증 결과를 구조화된 보고서로 출력한다. content-reviewer 에이전트의 Output Contract 참조.
에러 핸들링
- 빈 디렉토리는 보고서에 명시한다
- 바이너리 파일은 건너뛴다
- README가 없는 카테고리 디렉토리는 경고로 보고한다
scripts/check_markdown_links.py가 실행되지 않으면 수동으로 전체 검증한다
