claudecode-scan

당신의 Claude Code 설정, 정말 프로덕션 환경에서 쓸 준비가 되어 있나요?

100시간 동안의 자율 AI 운영을 통해 무엇이 가장 먼저 깨지는지 확인했습니다. 이 도구는 20가지 실제 장애 패턴을 기준으로 당신의 설정을 30초 만에 점검합니다.

설치가 필요 없습니다. 어떤 데이터도 당신의 컴퓨터 밖으로 전송되지 않습니다.

왜 이 도구가 존재할까

Claude Code는 몇 시간 동안 자율적으로 실행될 수 있습니다. 하지만 대부분의 설정은 그런 환경을 고려해 만들어지지 않았습니다.

• 파일이 삭제되기도 하고
• 비용이 갑자기 급증하기도 하며
• AI가 오류에 빠져 같은 작업을 반복하기도 하고
• 코드 리뷰 없이 main 브랜치에 바로 푸시되기도 합니다

이건 가상의 문제가 아닙니다. 적절한 가드레일(안전장치)이 없을 때 실제로 발생하는 문제들입니다.

claudecode-scan는 다음을 수행합니다:

• .claude/settings.json과 CLAUDE.md를 스캔
• 20가지 알려진 실패 패턴을 기준으로 점검
• 현재 설정의 점수(score) 제공
• 어떤 부분을 수정해야 하는지 정확히 안내

퀵스타트 (설치필요없음)

웹버전 — CLAUDE.md를 붙여 넣으면 즉시 점수를 확인할 수 있습니다. 👉 https://mdrules.dev/claudecode-scan/

무엇을 점검하나요

| 영역 | 점검 항목 수 | 확인 내용 | |-----------|--------|-------------------| | Safety Guards (안전 장치) | 4 | PreToolUse 훅, 시크릿 관리, 브랜치 보호, 에러 게이트| | Code Quality (코드 품질) | 4 | 문법 검사, 에러 추적, DoD 체크리스트, 출력 검증 | | Monitoring (모니터링) | 3 | 컨텍스트 윈도우 알림, 활동 로그 기록, 일일 요약 | | Recovery (복구) | 3 | 백업 브랜치, 워치독, 루프 감지 | | Autonomy (자율 실행) | 3 | 작업 큐, 질문 차단 메커니즘, 지속 상태 저장 | | Coordination (협업/조정) | 3 | 의사결정 로그, 멀티 에이전트 지원, 교훈 기록 |

출력 예시

  Claude Code Scan Check v1.0
  ═══════════════════════════════════════

  ▸ Safety Guards
    [PASS] PreToolUse 훅이 위험한 명령어를 차단합니다
    [PASS] API 키가 전용 파일에 저장되어 있습니다
    [FAIL] 리뷰 없이 main/master에 푸시하는 것을 방지하는 설정이 없습니다
    [PASS] 에러 인식 게이트가 에러 발생 시 외부 호출을 차단합니다

  Score: 63/100 — Getting There

  Top fixes:
    → 위험한 명령어를 차단하는 PreToolUse 훅을 추가하세요.
    → PostToolUse 훅에서 bash 출력의 에러 패턴을 스캔하세요.

점수 등급

| 점수 | 등급 | |-------|-------| | 80-100 | Production Ready (프로덕션 준비 완료) | | 60-79 | Getting There (거의 다 왔어요) | | 35-59 | Needs Work (개선 필요) | | 0-34 | Critical (위험) |

점수가 낮게 나왔나요?

**claude-code-hooks**는 20개 점검 항목 중 18개를 커버합니다 — 108시간의 실제 자율 운영에서 추출한 즉시 사용 가능한 훅과 템플릿입니다.

# 무엇이 부족한지 확인하기
npx claudecode-scan

# 수정하기
git clone https://github.com/gaebalai/claude-code-hooks

작동 방식

1. ~/.claude/settings.json에서 훅 설정을 읽습니다
2. CLAUDE.md 파일(전역 + 프로젝트)에서 패턴을 스캔합니다
3. 공통 파일(mission.md, proof-log/, task-queue.yaml)의 존재 여부를 확인합니다
4. 각 점검 항목을 채점(통과/실패)하고 영역별 점수를 계산합니다
5. 영향도 순으로 정렬된 실행 가능한 권장 사항을 출력합니다

의존성 없음. 어떤 데이터도 외부로 전송되지 않음. 완전히 로컬에서 실행됩니다.

JSON 출력

npx claudecode-scan --json

점수, 등급, 영역별 결과, 개별 점검 결과가 포함된 구조화된 JSON을 반환합니다. CI 파이프라인, 대시보드, 프로그래밍 방식의 분석에 유용합니다.

README 뱃지

npx claudecode-scan --badge

README에 사용할 수 있는 shields.io 뱃지 URL을 생성합니다:

CI 통합

점수가 60 이상이면 종료 코드 0, 그렇지 않으면 1을 반환합니다.

# .github/workflows/scan.yml
name: Claude Code Scan Check
on:
  push:
    paths: ['.claude/**', 'CLAUDE.md']
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npx claudecode-scan@latest

라이선스

MIT