Claude Code의 CLAUDE.md와 Skills를 구분하여 사용하기 ― 상시 규칙과 태스크별 절차 설계

본 기사는 Claude Code (Anthropic)를 활용하여 작성되었습니다.

검증 가능한 범위 내에서 공개 정보를 정리한 것이지만,

코드 예시 등은 실제 환경에서의 동작 확인을 권장합니다.

CLAUDE.md에 무엇이든 써넣다 보니 500행을 넘어 제어할 수 없게 되었다 ― 그런 상황을 피하기 위해, 공식 문서에서는 "항상 지켜야 할 규칙은 CLAUDE.md, 특정 태스크의 절차는 Skills"라는 역할 분담을 명확히 권장하고 있다. 이 기사에서는 양자의 설계 사상과 설정 방법을 공개 정보로부터 정리한다. 읽고 난 뒤에 "어디에 쓸 것인가"에 대한 고민을 줄이는 것이 목적이다.

CLAUDE.md는 Claude Code가 세션 시작 시 매번 자동으로 읽어들이는 설정 파일이다. 리포지토리 루트(Repository root)에 두면 해당 프로젝트 전체에 적용되며, ~/.claude/CLAUDE.md에 두면 모든 프로젝트에 걸친 글로벌(Global) 설정이 된다.

공식 문서가 권장하는 기재 내용은 다음 세 가지다:

빌드·테스트 커맨드 (Build/Test Command): npm run build, pytest -x 등 팀에서 매번 사용하는 커맨드

코딩 규약 (Coding Convention): 타입 정의 방식, 명명 규칙, 임포트 순서

프로젝트 고유의 아키텍처 개요 (Project-specific Architecture Overview): 디렉토리 구조의 의미, 외부 서비스로의 접속 방법

초기 파일은 /init 커맨드로 생성할 수 있다. Claude Code가 코드베이스를 분석하여 빌드 시스템이나 테스트 프레임워크를 자동으로 감지하고, 골격을 생성해 준다. 이를 템플릿으로 삼아 깎아가며 키워나가는 것이 Best practices에서의 권장 절차다.

사이즈의 기준은 500행 이하이다. 이를 초과하면 매 세션의 컨텍스트 (Context) 소비가 늘어나고, 모델의 주의력이 분산되기 쉽다. "이 지시, 매번 필요한가?"를 자문하며 정기적으로 정리하는 것이 베스트다.

Skills는 .claude/skills/ 아래에 두는 SKILL.md 파일군이다. CLAUDE.md와 달리, description이 일치할 때에만 읽히는 조건부 설정 모듈로서 기능한다.

각 SKILL.md의 서두에 YAML 프론트매터 (YAML Frontmatter)를 기술한다.

---
name: "code-review"
description: "Pull Request의 코드 리뷰를 실시한다. 지적 항목의 우선순위 지정·코멘트 문체·자동 수정 가능 여부를 정의하고 있다. 코드 리뷰를 의뢰받았을 때, 또는 리뷰 코멘트를 정리하고 싶을 때 사용한다."
...

description이 가장 중요한 필드이며, Claude는 이 내용을 보고 스킬을 자동으로 발동할지 판단한다. 250자를 초과하면 잘리기 때문에, "무엇을 하는 스킬인가"와 "언제 사용해야 하는가"라는 트리거 (Trigger) 조건을 전반부에 응축할 필요가 있다.

v2.1.152부터 disallowed-tools 필드도 이용할 수 있다. 스킬 실행 중에 금지할 도구를 지정할 수 있으며, 의도하지 않은 파일 조작이나 외부 요청을 스킬 단위로 제어할 수 있게 되었다 (릴리스 노트). disallowed-tools: ["Bash", "WebFetch"]와 같이 작성하면, 해당 스킬이 유효한 동안에는 셸 실행이나 외부 페치 (Fetch)가 무효화된다.

관점	CLAUDE.md	Skills
읽기 타이밍	매 세션 자동	description이 일치할 때
위치	CLAUDE.md (루트) 또는 ~/.claude/CLAUDE.md	.claude/skills/ 또는 ~/.claude/skills/

판단의 심플한 기준은 다음과 같다:

모든 작업에 필요한 규칙 → CLAUDE.md에 작성

특정 커맨드나 상황에서만 사용하는 절차 → Skills로 분리

CLAUDE.md가 비대해지기 시작하면 "이 규칙은 특정 태스크에만 관계되는가?"를 자문한다. Yes라면 Skills로 이동하는 것이 공식 문서의 권장 사항이다 (스킬로 Claude를 확장한다).

스킬의 재로드 (Reloading Skills): v2.1.152부터 /reload-skills 커맨드를 사용할 수 있게 되었다. SKILL.md를 편집한 후에 실행하면, 재시작 없이 변경 사항을 반영할 수 있다. 개발 중에는 이를 활용하면 시행착오를 빠르게 줄일 수 있다.

글로벌 vs 프로젝트: ~/.claude/skills/

에 두면 모든 프로젝트에서 유효하게 된다. 개인적인 범용 절차는 글로벌(Global)에, 팀 고유의 절차는 리포지토리(Repository)의 .claude/skills/에 두는 운영 방식이 정리하기 쉽다 (스킬 저작(Skill Authoring)의 베스트 프랙티스).

description의 품질이 전체를 좌우한다: 스킬이 자동으로 발동되지 않는 경우, 먼저 description을 재검토하라. "무엇을 하는가"뿐만 아니라 "언제 사용해야 하는가"에 대한 트리거(Trigger) 조건을 작성하면 발동 정밀도가 높아진다. 250자라는 제한을 의식하여, 중요한 정보를 전반부에 집중시켜라.

CLAUDE.md는 "매 세션마다 읽히는 설계서", Skills는 "호출되었을 때만 전개되는 절차서"다. CLAUDE.md를 500행 이내로 억제하고 태스크(Task)별 절차를 Skills로 분리함으로써, 컨텍스트(Context)의 낭비를 방지하면서 Claude의 동작을 안정시킬 수 있다.

/init으로 토대를 만들고, /reload-skills로 빠르게 반복하며, description을 다듬어 나가는 사이클이 현실적인 육성 방법이다. 공식 문서(Official Documentation)는 code.claude.com/docs에 정리되어 있으므로, 실제로 설정을 구성하기 전에 살펴보면 설계 시의 망설임을 줄일 수 있다.