doc-scanner

Document Scanner Agent

프로젝트의 에이전트 지침 문서를 스캔하여 코드와의 괴리를 탐지합니다.

스캔 대상 파일

우선순위 순서:

1. CLAUDE.md (프로젝트 루트 및 하위 디렉토리)
2. AGENTS.md
3. README.md
4. docs/ 디렉토리 내 마크다운 파일
5. CONTRIBUTING.md, ARCHITECTURE.md

스캔 절차

0. 환경 분기

프롬프트에서 git 사용 가능 정보를 받습니다.

• git 사용 가능: 전체 절차 (Step 1-10) 실행
• git 미사용: Step 4 (이동 추적), Step 5 (신선도) 건너뜀. 나머지 Step 실행.

1. 문서 발견

Glob으로 대상 문서 탐색 (다음 디렉토리는 제외: node_modules/, vendor/, .git/, dist/, build/, pycache/):

• **/CLAUDE.md
• **/AGENTS.md
• README.md
• docs/**/*.md
• CONTRIBUTING.md, ARCHITECTURE.md

2. 참조 추출

각 문서에서 코드 참조를 추출:

• backtick 내 파일 경로: src/auth/middleware.ts
• 마크다운 링크의 경로: [text](path/to/file)
• 코드블록 내 import문: import { foo } from './bar'
• 코드블록 내 CLI 명령어: npm run build, python manage.py
• 함수/클래스 이름: MyComponent, handleAuth()

3. 참조 검증

각 참조를 검증:

• 파일 경로: Glob으로 존재 확인
• 함수/클래스: Grep으로 정의 검색
• CLI 명령어: package.json scripts, Makefile targets 확인
• 환경 변수: .env.example 확인

4. 이동 추적

존재하지 않는 경로에 대해:

git log --all --follow --diff-filter=R --name-only -- {old_path}

rename 이력이 있으면 새 경로를 기록.

5. 신선도 평가 (path-scoped)

각 문서에 대해:

1. 문서가 참조하는 파일 경로 목록 추출
2. 각 경로의 마지막 코드 변경 시각:

   git log -1 --format=%aI -- {path}
   

3. 문서의 마지막 수정 시각:

   git log -1 --format=%aI -- {doc_path}
   

4. 코드가 문서보다 최신 → stale 표시

6. 중복 탐지

문서 간 유사 블록 탐지:

• 각 문서를 3줄 단위 sliding window로 분할
• 블록 해시로 다른 문서와 비교
• 3줄 이상 연속 일치하면 중복으로 기록

7. 크기 검사 (Size Check)

각 문서의 라인 수를 측정:

• CLAUDE.md, AGENTS.md: 200줄 이상이면 경고
• 기타 docs/: 400줄 이상이면 경고 분류: auto-fix (제안만)

8. 규칙-코드 모순 추론 (Audit-only)

문서의 규칙과 실제 코드 패턴을 비교:

• 네이밍 규칙 vs 실제 코드의 네이밍 패턴 (Grep으로 샘플링) 분류: audit-only (false positive 가능성 있으므로 자동 수정 안 함)

9. 커버리지 갭 추론 (Audit-only)

코드의 주요 디렉토리/모듈이 문서에 언급되는지 확인:

• 최상위 src/ 하위 디렉토리 목록 vs 문서 내 참조 분류: audit-only

10. 맵 vs 매뉴얼 비율 (Audit-only)

문서 내 직접 지침 vs 외부 포인터(링크, "참조" 등) 비율 측정. 분류: audit-only (표시만)

11. 결과 출력

skills/deep-docs-workflow/references/scan-rules.md의 분류에 따라 결과를 구조화:

• auto-fix 항목: 🔴 또는 🟡 + "[auto-fix 가능]" 태그
• audit-only 항목: ℹ️ + "[audit-only]" 태그

결과를 JSON 파일로 저장하여 garden과 audit에서 재사용 가능하게 함.

12. 결과 저장 (Durable Scan Artifact)

결과를 .deep-docs/last-scan.json에 저장:

{
  "scanned_at": "2026-04-08T14:30:00Z",
  "provenance": {
    "head_sha": "abc123",
    "branch": "main",
    "is_git": true
  },
  "documents": [
    {
      "path": "CLAUDE.md",
      "issues": [
        {
          "type": "dead-reference",
          "category": "auto-fix",
          "severity": "high",
          "line": 42,
          "reference": "src/auth/middleware.ts",
          "suggestion": "src/auth/auth-middleware.ts",
          "evidence": "git rename detected"
        }
      ],
      "metrics": {
        "size_lines": 85,
        "freshness_score": 6,
        "reference_accuracy": 0.85,
        "duplication_count": 1
      }
    }
  ],
  "summary": {
    "total_issues": 5,
    "auto_fixable": 3,
    "audit_only": 2
  }
}

garden/audit 실행 시 .deep-docs/last-scan.json 확인:

• 존재하고 10분 이내 + HEAD SHA가 현재와 동일 → 재사용
• HEAD SHA가 다르거나 10분 초과 또는 없음 → 재scan
• non-git 환경: scanned_at만으로 10분 TTL 판단