Claude Health: Claude Code 구성 건강을 6-레이어로 체계적으로 감사하는 스킬

“Claude Code를 쓰다 보면 이런 게 고민입니다.” tw93 (@AiTw93)은 이 문제를 직접 겪었습니다.

• “내 CLAUDE.md가 제대로 구성되어 있나?”
• “rules/가 제대로 있나?”
• “스킬이 안전하나?”
• “훅이 필요한가?”
• “MCP가 너무 많은가?”

단일 구성 요소의 문제가 아니었습니다. 이 모든 레이어가 서로 영향을 미치며, 누락된 것이 있으면 전체 시스템의 성능과 안전성이 저하됩니다.

Claude Health는 이 모든 레이어를 체계적으로 검사하는 감사 스킬입니다. 6-레이어 프레임워크, 4개 병렬 진단 에이전트, 우선순위별 보고서가 준비되어 있습니다.

탄생 배경: 복잡성의 압박

Claude Code의 구성은 단순하지 않습니다.

1. CLAUDE.md — 프로젝트 맥락, 규칙, 지침
2. rules/ — 언어별, 파일별 규칙
3. skills/ — 자동 호출되는 스킬
4. hooks — 파일 유형별 훅
5. subagents — 하위 에이전트 구성
6. verifiers — 검증 프로세스

여기에 MCP 서버까지 더해지면, 전체 구성의 복잡도는 급격히 증가합니다. 하나의 레이어가 누락되거나 잘못 구성되면, 다른 레이어들도 영향을 받습니다.

tw93은 이 문제를 해결하기 위해 6-레이어 프레임워크를 설계했습니다. 각 레이어를 체계적으로 검사하고, 누락된 것을 찾아내며, 위험 요소를 식별합니다.

2026년 3월 12일, 이 접근 방식이 담긴 Claude Health가 공개되었습니다. 97개 이상의 스타를 받으며 Claude Code 사용자들 사이에서 관심을 모았습니다.

6-레이어 프레임워크: 체계적 검사

Claude Health는 6개의 레이어를 각각 다른 관점에서 검사합니다.

Layer 1: CLAUDE.md

시그널 대 잡음비 — 핵심 정보가 명확한지 확인합니다.

체크 항목:

• 시그널 대 잡음비: 핵심 지침이 명확한가?
• 누락된 Verification/Compact Instructions: 필수 지침이 있는가?
• 산문 팽창: 불필요한 설명이 있는가?

일반적인 문제:

• 너무 긴 설명으로 인해 모델이 핵심을 놓침
• 중요한 규칙이 산문에 묻혀 있음
• Verification 지침이 누락됨

Layer 2: rules/

언어별 규칙 배치 — 각 언어/파일 유형에 적절한 규칙이 있는지 확인합니다.

체크 항목:

• 언어별 규칙 배치: TypeScript, Python, Go 등 각 언어에 규칙이 있는가?
• 커버리지 간격: 어떤 언어/파일 유형이 누락되었는가?

일반적인 문제:

• 새로운 언어 추가 시 규칙 누락
• 파일 유형별 훅과 규칙의 불일치

Layer 3: skills/

스킬 품질 — 스킬의 효율성과 안전성을 평가합니다.

체크 항목:

• 설명 토큰 수: 스킬이 너무 많은 토큰을 소비하는가?
• 트리거 명확성: 스킬이 언제 호출되는지 명확한가?
• 자동 호출 전략: 불필요한 자동 호출이 있는가?
• 빈도 기반 최적화: 자주 사용되지 않는 스킬이 있는가?
• 스킬 보안: 프롬프트 인젝션, 데이터 엑스필트레이션 등 보안 이슈가 있는가?

일반적인 문제:

• 너무 많은 토큰을 사용하는 스킬로 인해 컨텍스트 압박
• 모호한 트리거로 인한 예기치 않은 호출
• 안전하지 않은 스킬로 인한 보안 위험

Layer 4: 훅 (hooks)

파일 유형 커버리지 — 각 파일 유형에 적절한 훅이 있는지 확인합니다.

체크 항목:

• 패턴 필드 존재: 훅의 패턴이 올바르게 정의되었는가?
• 파일 유형 커버리지: 모든 주요 파일 유형이 커버되었는가?
• 오래된 엔트리: 사용하지 않는 훅이 남아 있는가?

일반적인 문제:

• 새로운 파일 유형 추가 시 훅 누락
• 오래된 훅으로 인한 혼란

Layer 5: MCP

MCP 오버헤드 — MCP 서버의 수와 토큰 비용을 평가합니다.

체크 항목:

• 서버 수: 너무 많은 MCP 서버가 있는가?
• 토큰 비용 추정: MCP가 컨텍스트를 얼마나 차지하는가?
• 컨텍스트 압력 감지: MCP로 인한 컨텍스트 압박이 있는가?

일반적인 문제:

• 너무 많은 MCP 서버로 인한 컨텍스트 압박
• 비용 효율이 낮은 MCP 사용

Layer 6: allowedTools & Prompt Cache

도구 관리 — 허용된 도구와 캐시 효율을 확인합니다.

체크 항목:

• 위험하거나 오래된 일회용 명령어: 불필요한 도구가 있는가?
• 동적 타임스탬프: 캐시를 깨는 패턴이 있는가?
• 툴 재정렬: 캐시 효율을 저하하는 패턴이 있는가?
• 세션 중간 모델 스위칭: 캐시가 무효화되는 패턴이 있는가?

프로젝트 계층 자동 감지

Claude Health는 프로젝트의 복잡도를 자동으로 감지합니다.

Simple 프로젝트:

• 최소 구성
• 핵심 레이어만 검사
• 누락된 레이어가 있어도 경고하지 않음

Standard 프로젝트:

• 일반적인 구성
• 모든 레이어 검사
• 누락된 레이어를 경고

Complex 프로젝트:

• 고급 구성
• 모든 레이어 심층 검사
• 누락된 레이어를 심각한 문제로 표시

이 방식은 프로젝트 크기에 맞게 체크를 보정합니다. 필요하지 않은 레이어가 누락되어 있어도 플래그하지 않습니다.

4개 병렬 진단 에이전트

Claude Health는 4개의 진단 에이전트를 병렬로 실행하여 결과를 종합합니다.

에이전트 1: 구조 분석

• 파일 구조 검사
• 누락된 파일 식별
• 구조적 일관성 확인

에이전트 2: 보안 감사

• 스킬 보안 검사
• 프롬프트 인젝션 탐지
• 데이터 엑스필트레이션 위험 확인

에이전트 3: 성능 분석

• 토큰 사용량 분석
• 컨텍스트 압력 측정
• 캐시 효율 평가

에이전트 4: 품질 평가

• 설명 품질
• 트리거 명확성
• 규칙 커버리지

각 에이전트의 결과는 우선순위별로 그룹화되어 보고서로 출력됩니다.

우선순위별 보고서: 3-계층 방어

Claude Health는 문제를 3가지 우선순위로 분류합니다.

Critical (지금 수정)

규칙 위반, 위험한 권한, 캐시 깨는 패턴과 같은 즉각적인 위험.

포함 항목:

• 규칙 위반
• 위험한 권한
• 캐시 깨는 패턴
• MCP 오버헤드 > 12.5%
• 스킬 보안 이슈 (프롬프트 인젝션, 데이터 엑스필트레이션 등)

Structural (곧 수정)

잘못된 콘텐츠, 누락된 훅, 단일 계층 중요 규칙과 같은 구조적 문제.

포함 항목:

• 잘못된 콘텐츠
• 누락된 훅
• 단일 계층 중요 규칙
• 스킬 품질 이슈 (팽창된 콘텐츠, 깨진 레퍼런스)

Incremental (있으면 좋음)

컨텍스트 위생, HANDOFF.md 채택, 스킬 빈도 튜닝과 같은 개선 제안.

포함 항목:

• 컨텍스트 위생
• HANDOFF.md 채택
• 스킬 빈도 튜닝
• 스킬 출처 (심링크 소스, 버전 트래킹)

3-계층 방어: Critical rules 보호

Critical rules는 CLAUDE.md, Skill, Hook 세 계층에서 함께 보호됩니다.

예시:

• CLAUDE.md: “보안 검사는 필수”라고 명시
• Skill: 보안 검사를 강제하는 스킬
• Hook: 보안 검사가 없는 커밋을 차단

이 3계층 보호는 중요한 규칙이 누락되거나 무시되지 않도록 보장합니다.

설치 및 사용법

설치

npx skills add tw93/claude-health

사용법

/health

또는 자연어로:

Run a health check on my Claude Code config
Claude Code 구성 건강을 체크해줘

요구사항

• Claude Code
• Node.js (skills CLI용)

실제 보고서 예시

# Claude Health Report

## Critical Issues (2)

1. **MCP 오버헤드 > 12.5%**
   - MCP 서버가 15개 컨텍스트를 차지 (최대 12.5% 권장)
   - 영향: 컨텍스트 압박
   - 조치: 자주 사용하지 않는 MCP 서버 제거 고려

2. **스킬 보안 이슈: 프롬프트 인젝션**
   - skills/unsafe-skill/SKILL.md에서 사용자 입력이 직접 프롬프트에 삽입됨
   - 영향: 프롬프트 인젝션 위험
   - 조치: 입력 검증 및 이스케이프 추가

## Structural Issues (3)

1. **누락된 훅: .tsx 파일**
   - hooks/에 .tsx 파일용 훅이 없음
   - 영향: React 파일에서 규칙이 적용되지 않음
   - 조치: .tsx 훅 추가 고려

2. **스킬 품질: 팽창된 콘텐츠**
   - skills/verbose-skill/SKILL.md가 2000+ 토큰 사용
   - 영향: 불필요한 컨텍스트 소비
   - 조치: 스킬 설명 간소화

3. **깨진 레퍼런스**
   - skills/broken-skill/SKILL.md에서 존재하지 않는 파일 참조
   - 영향: 스킬이 제대로 작동하지 않음
   - 조치: 레퍼런스 수정 또는 제거

## Incremental Improvements (2)

1. **HANDOFF.md 채택**
   - 현재 HANDOFF.md가 없음
   - 영향: 세션 간 컨텍스트 전달이 어려움
   - 조치: HANDOFF.md 추가 고려

2. **스킬 빈도 튜닝**
   - skills/rarely-used가 자동 호출됨
   - 영향: 불필요한 토큰 소비
   - 조치: 수동 호출로 변경 고려

---

## Summary

- Critical: 2 issues
- Structural: 3 issues
- Incremental: 2 suggestions

Overall Health: 7/10

왜 Claude Health인가?

기존 접근 방식의 문제

6-레이어의 힘

Claude Code의 구성은 6개 레이어로 구성됩니다. 하나의 레이어만 보는 것으로는 부족합니다.

• CLAUDE.md만 보면 rules/가 누락된 것을 알 수 없습니다.
• **skills/**만 보면 hooks가 누락된 것을 알 수 없습니다.
• MCP만 보면 전체 컨텍스트 압력을 알 수 없습니다.

Claude Health는 이 모든 레이어를 통합적으로 검사합니다.

마치며: 구성 건강의 중요성

Claude Code는 강력한 도구입니다. 하지만 그 구성이 건강하지 않으면, 성능과 안전성이 저하됩니다.

• CLAUDE.md가 명확하지 않으면, 모델이 핵심을 놓칩니다.
• **rules/**가 부족하면, 규칙이 일관되지 않습니다.
• **skills/**가 비효율적이면, 토큰을 낭비합니다.
• MCP가 너무 많으면, 컨텍스트 압박이 심해집니다.

Claude Health는 이 모든 레이어를 체계적으로 검사합니다. 6-레이어 프레임워크, 4개 병렬 진단 에이전트, 우선순위별 보고서가 준비되어 있습니다.

97+ 스타, 실전 검증된 프레임워크, 그리고 체계적인 접근 방식이 이미 준비되어 있습니다.

🔗 관련 정보

• GitHub: https://github.com/tw93/claude-health
• 프레임워크 설명: https://tw93.fun/en/2026-03-12/claude.html
• 개발자: tw93 (@AiTw93)
• 생성일: 2026년 3월 12일
• 언어: TypeScript
• 라이선스: MIT
• 이미지: /images/claude-health-og.png, /images/claude-health-audit.jpg