스킬 감사 (Parallel Agent-based Audit)

이 스킬은 프로젝트의 스킬과 문서가 실제 코드베이스와 동기화되어 있는지를 병렬 에이전트를 사용하여 대규모로, 정확하게 검증한다.

감사 대상

현재 프로젝트의 활성 스킬 목록 (CLAUDE.md 라우팅 테이블 참조):

감사 실행 방법

1. 병렬 에이전트 감사 (권장)

각 스킬에 대해 독립적인 Explore 에이전트를 병렬로 실행하여 감사한다. 토큰을 아끼지 않고 철저하게 검증하는 것이 핵심이다.

각 스킬에 대해 Agent(subagent_type="Explore")를 병렬 실행:

에이전트 프롬프트 템플릿:
"스킬 '{skill_name}'의 감사를 수행한다.

1. 스킬 문서 읽기: .claude/skills/{skill_name}/SKILL.md 및 references/ 전체
2. 소스 코드 탐색: 스킬이 다루는 소스 경로의 실제 코드 확인
3. 다음 항목을 검증:
   - 스킬에 기술된 파일 경로가 실제로 존재하는가?
   - 스킬에 기술된 함수/클래스/타입이 실제 코드와 일치하는가?
   - 스킬에 기술된 동작 방식이 실제 구현과 일치하는가?
   - 스킬에 누락된 중요 코드 변경이 있는가?
4. 결과를 다음 형식으로 보고:
   - 정확한 항목 (코드와 일치)
   - 불일치 항목 (코드와 다름) + 구체적 차이점
   - 누락 항목 (코드에는 있지만 문서에 없음)
   - 삭제 필요 (문서에는 있지만 코드에서 삭제됨)"

2. 빠른 타임스탬프 확인

간단한 시간 기반 확인이 필요할 때:

# 전체 스킬 최신성 한 줄 확인
for f in .claude/skills/*/SKILL.md; do
  echo "$(basename $(dirname $f)): $(git log -1 --format='%ar' -- "$f")"
done

# 소스 vs 스킬 수정일 비교
git log -1 --format='%ar' -- packages/server/  # 소스
git log -1 --format='%ar' -- .claude/skills/deploying-server/  # 스킬

3. 구조적 품질 검증

스킬 구조가 올바른지 확인하는 체크리스트:

• YAML frontmatter에 name과 description 존재
• description의 trigger 키워드가 CLAUDE.md 라우팅 테이블과 일치
• references/ 파일이 SKILL.md에서 참조됨
• 존재하지 않는 파일 경로를 참조하지 않음

소스-스킬 매핑

위 매핑에 없는 소스 경로는 스킬이 아닌 코드베이스 직접 탐색으로 해결한다.

자동화: lefthook pre-commit

lefthook.yml의 docs-freshness 커맨드가 staged 파일 중 packages/**/*.{ts,tsx} 또는 .claude/skills/** 변경 감지 시 .claude/scripts/check-docs-freshness.sh를 호출하여 대응 스킬의 최종 수정일 확인 (경고만, 블록하지 않음).

감사 결과 처리

감사 결과에서 불일치가 발견되면:

1. 불일치 항목: 스킬 문서를 실제 코드에 맞게 수정
2. 누락 항목: 중요한 변경이면 스킬 문서에 추가
3. 삭제 필요: 코드에서 제거된 기능은 스킬 문서에서도 제거
4. 정확한 항목: 변경 불필요

상세 참조

• references/audit-methodology.md — 감사 방법론, 에이전트 프롬프트 상세, 판정 기준
• references/troubleshooting.md — 감사 중 자주 발생하는 오류 해결