2026.02.28 / 동준상.넥스트플랫폼
Google Cloud Generative AI Leader
이번 포스트는 Claude Code 생태계 내에서 컨텍스트를 제공하는 두 가지 핵심 메커니즘인 CLAUDE.md와 SKILL.md의 아키텍처적 차이점을 상세히 분석합니다. 이 두 파일은 ‘정적 지속성’과 ‘동적 호출’이라는 근본적으로 다른 논리에 기반하여 작동하며, 각각의 역할과 효율성을 이해하는 것은 개발 환경 최적화에 필수적입니다.
Sponsored by
핵심 요약 (Executive Summary)
- Claude Code 내에서
CLAUDE.md와SKILL.md는 상호 보완적인 역할을 수행 CLAUDE.md는 프로젝트의 “영구적인 시스템 프롬프트”로 기능하며, 모든 세션에서 자동으로 로드되어 코딩 표준 및 빌드 명령과 같은 전역적인 규칙을 정의SKILL.md는 특정 작업이 필요할 때만 호출되는 “전문가 도구”로, 데이터베이스 마이그레이션이나 배포와 같은 복잡하고 구체적인 워크플로우를 담당- 성능 측면에서
CLAUDE.md는 AI가 별도의 판단 없이 즉각적으로 정보를 활용할 수 있다는 장점, 매번 컨텍스트 윈도우를 소비한다는 단점 SKILL.md는 필요할 때만 로드되어 토큰 효율성이 높고 모듈화된 재사용이 가능하다는 장점
CLAUDE.md, SKILL.md 주요 특성 비교
두 메커니즘의 기능적, 운영적 차이점은 다음과 같습니다.
| 기능 | CLAUDE.md (프로젝트 메모리) | SKILL.md (에이전트 스킬) |
| 로드 방식 | 모든 세션 시작 시 항상 로드 | 관련성이 있거나 수동으로 호출될 때만 로드 |
| 범위 | 프로젝트 전반의 규칙, 표준, 디렉토리 정보 | 특정 작업 전문 지식, 워크플로우, 복잡한 절차 |
| 토큰 효율성 | 낮음 (매번 컨텍스트 윈도우 소비) | 높음 (트리거 전까지는 설명만 인덱싱됨) |
| 이식성 | 특정 리포지토리/폴더에 고정됨 | 모듈식 (플러그인 또는 재사용 가능한 “플레이북”으로 공유 가능) |
| 트리거 방식 | 자동 (항상 존재) | 자동 (설명 일치 시) 또는 /skill-name 명령 |
| 핵심 논리 | 정적 지속성 (Static Persistence) | 동적 호출 (Dynamic Invocation) |
CLAUDE.md: 프로젝트의 영구적 “메모리”
CLAUDE.md는 특정 리포지토리를 위한 시스템 프롬프트 역할을 합니다. Claude가 해당 환경 내에서 올바르게 작동하기 위해 반드시 알고 있어야 하는 정보를 담습니다.
- 주요 포함 내용:
- 빌드 및 테스트 명령 (예:
npm test) - 코드 스타일 규약 (예: “항상 탭 사용”)
- 상위 수준의 프로젝트 맵 및 구조 정보
- 빌드 및 테스트 명령 (예:
- 성능 및 효율성:
- Vercel의 최근 평가에 따르면, 일반적인 프로젝트 컨텍스트의 경우
CLAUDE.md(또는 업계 표준인AGENTS.md)와 같이 “항상 켜져 있는” 파일이 스킬보다 성능이 뛰어난 경우가 많습니다. 이는 AI가 정보를 찾아볼지 여부를 스스로 “결정”할 필요가 없기 때문입니다. - 단점으로는 항상 컨텍스트를 점유하므로 대규모 프로젝트에서는 토큰 관리에 주의가 필요합니다.
- Vercel의 최근 평가에 따르면, 일반적인 프로젝트 컨텍스트의 경우
SKILL.md: 전문화된 “에이전트 스킬” 도구
“스킬”은 SKILL.md 파일과 선택적인 지원 자산(스크립트, 템플릿, 참조 문서)을 포함하는 디렉토리 형태의 구조체입니다. 평소에는 컨텍스트를 “오염”시키지 않으면서 필요할 때만 전문 지식을 제공합니다.
- 주요 포함 내용:
- 복잡한 워크플로우 (예: 데이터베이스 마이그레이션 방법)
- 특정 가이드라인 (예: API 문서 작성 지침)
- 운영 절차 (예: 프로덕션 배포 단계)
- 고급 기능 및 확장성:
- 실행 가능 스크립트: 스킬은 작업을 직접 수행하는 실행 스크립트를 포함할 수 있습니다.
- MCP 브릿지: 단순한 프롬프팅과 전체 Model Context Protocol(MCP) 서버 사이의 가교 역할을 수행할 수 있습니다.
- 모듈성: 특정 프로젝트에 종속되지 않고 공유 가능한 플러그인 형태로 구성할 수 있습니다.
결론: 최적의 활용 전략
Claude Code의 잠재력을 극대화하기 위해 두 메커니즘을 다음과 같이 결합하여 사용할 것이 권장됩니다.
- 역할 분담:
- “일하는 방식(Global Rules)”은
CLAUDE.md에 작성 - “특정 작업 수행 방식(Specialized Procedures)”은
SKILL.md에 작성
- “일하는 방식(Global Rules)”은
- 목차 전략(Table of Contents): 많은 개발자들이
CLAUDE.md를 프로젝트의 전역 지도로 사용하면서, 동시에 특정 스킬들을 가리키는 목차로 활용하고 있습니다. 이를 통해 Claude는 프로젝트의 전체적인 지도를 파악하고 있다가, 특정 작업이 발생했을 때만 구체적인 “지침서(Skill)”를 찾아보게 됩니다.
참고자료 다운로드
다운로드 | CLAUDE.md 대 SKILL.md 아키텍처 비교 (슬라이드)
https://drive.google.com/file/d/1151sQcngjc-VqaIXGoU7eHLTv0a9y2or/view?usp=sharing
