CLAUDE.md 분리 방법, 200줄 넘으면 폴더 4곳으로 나누는 법
CLAUDE.md 분리는 클로드 코드(Claude Code, 터미널에서 코드를 읽고 고치는 앤트로픽의 AI 코딩 도구)에게 주는 지침 파일이 길어졌을 때, 내용을 성격별로 rules·

CLAUDE.md를 200줄 안으로 줄이는 이유
클로드 코드 공식 문서는 CLAUDE.md를 200줄 안으로 쓰라고 권합니다. 길어질수록 규칙을 잘 따르지 않기 때문입니다.
CLAUDE.md(클로드 코드가 대화를 시작할 때마다 자동으로 읽는 프로젝트 설명서)는 매번 통째로 읽힙니다. 줄이 늘수록 매 대화의 앞부분을 차지하고, 중요한 규칙이 다른 문장 사이에 묻힙니다. 그래서 파일 안에 쌓인 내용을 성격별로 4개 폴더에 나눠 옮깁니다.
한 줄로 줄이면, CLAUDE.md에는 "매번 알아야 하는 사실"만 남기고 나머지는 규칙 → rules, 절차 → skills, 강제 → hooks, 긴 작업 → agents로 보냅니다.
1. rules 폴더: 주제가 하나인 규칙
테스트 규칙, API 규칙처럼 주제가 하나인 규칙은 룰스 폴더에 파일로 따로 뺍니다. 파일 위에 경로를 적어 두면 그 경로에 진입할 때만 불러옵니다.
클로드 코드에서는 프로젝트 안 .claude/rules/ 폴더에 마크다운 파일을 두고, 파일 맨 위 머리말(frontmatter, --- 두 줄 사이에 적는 설정)에 paths.claude/rules/api.md
---
paths:
- "src/api/**/*.ts"
---
# API 규칙
- 모든 응답은 { data, error } 형태로 돌려준다.
- 새 엔드포인트에는 입력값 검증을 반드시 넣는다.
src/api/**/*.tspaths
2. skills 폴더: 배포 순서 같은 절차
CLAUDE.md 안에 배포 순서 같은 절차가 적혀 있다면 스킬로 옮깁니다. 스킬은 평소엔 설명 한 줄만 올라가 있다가 쓸 때만 본문을 읽기 때문입니다.
스킬은 .claude/skills/스킬이름/SKILL.md 파일 하나로 만듭니다. 머리말의 description.claude/skills/deploy/SKILL.md---
---
name: deploy
description: 스테이징·운영 서버 배포 순서. 배포해 달라는 요청을 받았을 때 사용한다.
---
1. main 브랜치가 최신인지 확인한다.
2. 테스트를 모두 실행하고 실패가 있으면 멈춘다.
3. 스테이징에 먼저 배포하고 접속 확인을 보고한다.
4. 사용자가 확인하면 운영에 배포한다.
description은 "언제 쓰는지"가 드러나게 씁니다. 클로드 코드가 이 한 줄을 보고 스킬을 꺼낼지 판단하기 때문입니다. 채팅창에서 /deploy
3. hooks: 절대 어기면 안 되는 규칙
절대 어기면 안 되는 규칙은 부탁으로 적지 말고 훅으로 막습니다. 훅은 클로드 코드가 뭘 판단하든 동작 자체를 차단합니다.
훅(hook, 특정 동작 직전·직후에 자동으로 실행되는 스크립트)은 .claude/settings.json.claude/hooks/ 폴더에 둡니다. 아래는 ".env 파일(비밀번호·키를 담는 설정 파일)은 절대 고치지 않는다"를 훅으로 막는 예시입니다. 먼저 .claude/settings.json
{
"hooks": {
"PreToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{ "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-env.sh" }
]
}
]
}
}
다음은 .claude/hooks/protect-env.sh
#!/bin/bash
file=$(jq -r '.tool_input.file_path // empty')
if [[ "$file" == *.env* ]]; then
echo ".env 파일은 수정할 수 없습니다." >&2
exit 2
fi
exit 0
PreToolUsematcherEdit|Writeexit 2
-
터미널에서 프로젝트 폴더로 이동한 뒤
mkdir -p .claude/hooks로 폴더를 만듭니다. -
위 스크립트를
.claude/hooks/protect-env.sh로 저장합니다. -
chmod +x .claude/hooks/protect-env.sh로 실행 권한을 줍니다. 주의: 스크립트가
jq(JSON을 읽는 명령줄 도구)를 씁니다. 맥에서는brew install jq로 설치합니다. -
.claude/settings.json에 위 설정을 넣습니다. 파일이 이미 있으면 "hooks"부분만 합칩니다. -
클로드 코드를 다시 실행하고
/hooks를 입력해 등록됐는지 확인합니다. 확인: PreToolUse 아래에 방금 넣은 훅이 보인다.
4. agents 폴더: 출력이 긴 일
테스트 돌리기처럼 출력이 긴 일은 서브 에이전트에게 맡깁니다. 서브 에이전트는 자기 컨텍스트(AI가 한 번에 기억하며 작업하는 대화 공간)에서 일하고 요약만 돌려줍니다. 그래서 메인 대화가 가벼워집니다.
서브 에이전트는 .claude/agents/이름.md 파일로 정의합니다. 클로드 코드 안에서 /agents.claude/agents/test-runner.md
---
name: test-runner
description: 테스트를 실행하고 실패한 항목만 요약해 돌려준다. 테스트 실행이 필요할 때 사용한다.
tools: Bash, Read, Grep
---
프로젝트의 테스트를 실행한다.
전체 로그를 그대로 돌려주지 말고, 실패한 테스트 이름과 원인 한 줄, 관련 파일 경로만 목록으로 보고한다.
분리하고 나서 CLAUDE.md에 남는 것
프로젝트 소개나 자주 쓰는 명령어처럼 매번 알아야 하는 사실만 남깁니다. 나눈 뒤 모습은 대략 이렇습니다.
# 프로젝트 소개
- 쇼핑몰 관리자 웹앱. 프론트는 Next.js, 서버는 Node.js.
# 자주 쓰는 명령어
- 개발 서버: npm run dev
- 테스트: npm test
# 어디에 무엇이 있나
- 주제별 규칙: .claude/rules/
- 절차: .claude/skills/
- 강제 규칙: .claude/settings.json 의 hooks
- 긴 작업 담당: .claude/agents/
CLAUDE.md 분리 기준 한눈에 보기
- CLAUDE.md는 200줄 안으로(클로드 코드 공식 문서 권장)
- 단일 주제 규칙은 rules 폴더 파일로
- 절차는 skills로
- 어기면 안 되는 규칙은 hooks로 차단
- 출력이 긴 일은 agents(서브 에이전트)로
- CLAUDE.md에는 "매번 알아야 하는 사실"만(예: 프로젝트 소개·자주 쓰는 명령어)
CLAUDE.md 분리를 실제로 해 볼 때
내 CLAUDE.md가 몇 줄인지 확인하기
터미널에서 프로젝트 폴더로 이동한 뒤 아래 명령을 입력합니다. 숫자가 줄 수입니다.
wc -l CLAUDE.md
클로드 코드 안에서 /memory
분류를 클로드 코드에게 맡기는 프롬프트
줄마다 직접 나누기 번거롭다면 먼저 분류표만 받아 보고, 확인한 뒤 옮기게 합니다.
CLAUDE.md를 200줄 안으로 줄이고 싶어.
각 줄을 아래 다섯 가지로 분류한 표를 먼저 보여 줘. 아직 파일은 고치지 마.
1) 매번 알아야 하는 사실 → CLAUDE.md에 남김
2) 주제가 하나인 규칙 → .claude/rules/
3) 순서가 있는 절차 → .claude/skills/
4) 절대 어기면 안 되는 규칙 → hooks 후보
5) 출력이 긴 작업 → .claude/agents/
막히는 지점
- 옮긴 규칙이 안 먹는 것 같다: rules 파일의
paths경로가 실제 폴더 구조와 맞는지 확인합니다. 경로를 비워 두면 항상 읽힙니다. - 스킬이 저절로 안 불린다: description에 "언제 쓰는지"가 빠진 경우가 많습니다. "배포해 달라는 요청을 받았을 때 사용"처럼 상황을 적습니다.
- 훅이 동작하지 않는다: 스크립트 실행 권한(
chmod +x)과 jq 설치 여부, settings.json의 쉼표·괄호 오류를 먼저 봅니다. - 전부 훅으로 막고 싶다: 훅은 "절대"인 규칙에만 씁니다. 너무 많이 걸면 정상 작업까지 자꾸 막혀 오히려 느려집니다.
언제 나눌지 판단하기
모든 규칙을 옮길 필요는 없습니다. 200줄 안쪽이고 클로드 코드가 규칙을 잘 따르고 있다면 그대로 둬도 됩니다. 규칙을 자꾸 어긴다거나, 파일이 길어져 어디에 뭐가 있는지 사람도 헷갈릴 때가 분리할 시점입니다. 규칙을 부탁이 아니라 시스템으로 지키게 만들고 싶다면 3번의 훅부터 하나 걸어 보는 것이 출발점입니다.
자주 묻는 질문
CLAUDE.md는 몇 줄까지 써야 하나요?
클로드 코드 공식 문서 기준으로 200줄 안이 권장됩니다. 길어질수록 규칙을 잘 따르지 않기 때문입니다. 줄 수는 터미널에서 wc -l CLAUDE.md
rules와 skills는 무엇이 다른가요?
rules는 지켜야 할 규칙이고, skills는 순서가 있는 절차입니다. rules는 지정한 경로의 파일을 다룰 때 불려 오고, skills는 평소 설명 한 줄만 올라가 있다가 필요할 때 본문을 읽습니다.
훅은 CLAUDE.md 규칙과 어떻게 다른가요?
CLAUDE.md의 규칙은 부탁이라 클로드 코드가 판단에 따라 어길 수 있습니다. 훅은 스크립트가 동작 자체를 막기 때문에 판단과 상관없이 차단됩니다. 그래서 절대 어기면 안 되는 규칙에만 씁니다.
서브 에이전트를 쓰면 무엇이 좋아지나요?
긴 출력이 메인 대화에 쌓이지 않습니다. 서브 에이전트가 자기 공간에서 테스트 같은 일을 하고 요약만 돌려주기 때문에 메인 대화가 가벼워집니다.
이 글의 본문은 아래 원본 유튜브 영상의 내용을 바탕으로 쓸모연구소가 다시 정리해 쓴 것입니다. 세부 내용과 최신 정보는 원본 영상과 공식 안내에서 확인해 주세요.
원본 영상 보러가기 ↗