vlv-code/scan-meta-project

저장소 메타 지식 무결성 검사기 (메타 프로젝트 스캐너)

파괴적인 재초기화 없이 기존 메타 프로젝트 설정을 빠르게 검사하거나 심층적으로 감사하는 운영 스킬입니다.

이 스킬은 두 가지 모드로 작동합니다:

• --shallow (빠른 상태 확인): 루트 AGENTS.md의 존재와 내용 확인, 5개의 지식 슬라이스 확인, 경계 게이트(check_boundaries.py --audit-tree)를 실행하여 100% 파일 커버리지 검증, 작업 최신 상태 확인.
• --deep (핵심 심층 감사 및 드리프트 확인): 모든 얕은 검사 실행, 주요 런타임 모듈에 대한 핵심 검사 체크리스트 호출, sync-architecture에 구성 요소/데이터 흐름 동기화 위임, weak_spots.md의 기술 부채 감사, 로컬 무결성 테스트 실행.

---

스킬 호출 시기

• 사용자가 "scan-meta-project", "scan meta project", "인스펙션 메타-지식", "커버리지 확인", "audit meta-knowledge", "check boundaries coverage", "블라인드 스팟 찾기", "verify slices" 와 같이 요청하는 경우.
• 릴리스 전 검증, PR 리뷰, 또는 에이전트 세션 외부에서 광범위한 변경 후 개발 재개 시.
• init-meta-project 완료 시 자동으로 호출됨.
• 주요 지정 역할: agent-quality-guardian (컴팩트 트리오 토폴로지) 또는 agent-meta-guardian (확장 역할 토폴로지), 또는 사용자가 직접 호출.

---

실행 단계

1단계: 모드 결정 및 대상 확인

1. 사용자 프롬프트에서 호출 모드를 확인하거나 기본값 --shallow 사용:
   • --shallow: 일상적인 무결성 검사, 경계 커버리지 검증, 작업 최신 상태 확인.
   • --deep: 전체 아키텍처 드리프트 탐지, 핵심 검사 체크리스트, 테스트 실행.
2. 경계 게이트 스크립트 찾기:
   • .agents/scripts/check_boundaries.py 우선 (대상 저장소 레이아웃).
   • 대안: scripts/check_boundaries.py (메타 프로젝트 레이아웃).
   • 두 스크립트 모두 없으면 boundaries.md의 글로브 패턴을 기준으로 수동으로 경계 확인.

---

2단계: 얕은 검사 (--shallow)

1. 패스포트 무결성:
   • 루트 AGENTS.md 존재 확인.
   • 섹션 1에 North Stars 및 불변 조건(Circuit Breaker, Default Deny)이 포함되어 있는지 확인.
   • 섹션 2, 3, 4, 5가 플레이스홀더 태그({{...}}) 없이 채워져 있는지 확인.
2. 지식 슬라이스 감사:
   • .agents/project_knowledge/ 아래 5개의 표준 슬라이스 확인:
     • architecture.md (구성 요소 및 데이터 흐름).
     • boundaries.md (책임 영역).
     • weak_spots.md (취약한 모듈 및 위험).
     • observations.md (5열 관찰 테이블).
     • tasks.md (활성 목표 및 체크리스트).
3. 경계 커버리지 (Zero Unmapped Dirs 규칙):
   • 자동화된 경계 게이트 감사 실행:

     python .agents/scripts/check_boundaries.py --audit-tree
     # 대안: python scripts/check_boundaries.py --audit-tree
     

   • 매핑되지 않은 파일이나 디렉토리가 보고되면 블랙 존 위반으로 처리합니다. 즉시 boundaries.md에 포함하도록 플래그 지정.
4. 작업 등록부 확인 (tasks.md):
   • 활성 목표가 명확하고 완료된 항목이 - [x]로 표시되어 있는지 확인.

---

3단계: 심층 검사 (--deep)

--deep으로 실행 시 에이전트는 모든 2단계 검사를 실행한 후 다음을 수행합니다:

1. 핵심 검사 체크리스트 (주요 모듈):
   • 데이터베이스 및 저장소: 기본 모델/저장소 파일 읽기. 스키마 결합, 마이그레이션 및 모놀리식 성장 검사.
   • 외부 클라이언트 및 API: 통합( AI SDK, HTTP 클라이언트) 읽기. 타임아웃 설정, 회로 차단기 및 오류 전파 확인.
   • 컨테이너화 및 CI: Dockerfile, docker-compose*.yml, .github/workflows/ 읽기. 빌드 매트릭스 및 보안 플래그 확인.
   • 진입점 및 UI: 주요 라우터, CLI 진입점 및 명령 처리기 읽기. 플랫폼 페이로드 제약 조건 및 입력 유효성 검사 확인.
2. 아키텍처 드리프트 탐지 (sync-architecture에 위임):
   • 맞춤형 코드 구문 분석 로직을 중복 구현하지 마십시오. 절차적 스킬 sync-architecture를 호출:
     • sync-architecture는 모든 local_repo_data 블록을 사전 보존(Pre-Flight Preservation)합니다.
     • 현재 구성 요소와 종단 간 데이터 흐름으로 .agents/project_knowledge/architecture.md를 업데이트합니다.
3. 위험 및 부채 재조정 (weak_spots.md):
   • weak_spots.md의 기존 항목 확인: 이전에 기록된 기술 부채가 해결되었으면 해결됨으로 표시하거나 제거.
   • 핵심 검사 중 새로운 취약한 결합이나 아키텍처 병목 현상이 발견되면 기록.
4. 자동화된 테스트 실행:
   • 표준 테스트 검색을 사용하여 프로젝트 테스트 스위트 실행:

     python -m unittest discover -s tests -p "test_*.py" -v
     # 또는 스택별 실행기 (예: pytest, npm test, cargo test)
     

---

4단계: 기회적 갱신 및 보고서

1. 식별된 격차 백필 (읽기 + 기회적 갱신):
   • 발견된 매핑되지 않은 경로를 boundaries.md ( <!-- local_repo_data:boundaries --> 내)에 원자적으로 기록.
   • 새로운 하위 작업 또는 완료된 이정표로 tasks.md 업데이트.
   • 새로 해결된 환경 특이 사항을 observations.md에 기록.
2. 스캔 보고서 제공: 사용자에게 간결한 요약 제시:

   ### 🔍 스캔 보고서 (메타 프로젝트 스캐너)
   - **모드:** `--shallow` | `--deep`
   - **패스포트 및 슬라이스:** 5/5 슬라이스 존재, AGENTS.md 유효
   - **경계 커버리지:** 100% 매핑됨 (또는 N개의 매핑되지 않은 경로 탐지됨)
   - **아키텍처 드리프트:** 동기화됨 (또는 sync-architecture를 통해 업데이트됨)
   - **식별된 조치 항목:** [있는 경우 1~3개의 구체적인 권장 사항 목록]