CLAUDE.md 분리 방법, 200줄 넘으면 폴더 4곳으로 나누는 법

CLAUDE.md 분리는 클로드 코드(Claude Code, 터미널에서 코드를 읽고 고치는 앤트로픽의 AI 코딩 도구)에게 주는 지침 파일이 길어졌을 때, 내용을 성격별로 rules·skills·hooks·agents 4개 폴더에 나눠 옮기는 방법입니다. 마일드코드 채널의 50초짜리 쇼츠가 "무엇을 어디로" 보낼지 네 가지 기준을 알려 줬고, 이 글은 쇼츠가 말하지 않은 "어떻게", 즉 폴더 경로와 파일 형식, 훅 설정 예시까지 채워 넣었습니다.

CLAUDE.md를 200줄 안으로 줄이라는 이유

쇼츠 첫 문장은 이렇습니다. 클로드 코드 공식 문서가 CLAUDE.md를 200줄 안으로 쓰라고 하며, 길어질수록 규칙을 잘 따르지 않는다는 겁니다. 문서 링크는 영상에 나오지 않습니다.

CLAUDE.md(클로드 코드가 대화를 시작할 때마다 자동으로 읽는 프로젝트 설명서)는 매번 통째로 읽힙니다. 줄이 늘수록 매 대화의 앞부분을 차지하고, 중요한 규칙이 다른 문장 사이에 묻힙니다. 그래서 파일 안에 쌓인 내용을 성격별로 4개 폴더에 나눠 옮기라는 권고 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/**/*.ts는 "src/api 아래 모든 하위 폴더의 .ts 파일"이라는 뜻입니다. 이 경로의 파일을 다룰 때만 규칙이 불려 옵니다. paths를 적지 않은 규칙 파일은 항상 읽힙니다.

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

PreToolUse는 "도구를 쓰기 직전", matcher의 Edit|Write는 "파일 수정·작성 도구일 때"라는 뜻입니다. 스크립트가 exit 2로 끝나면 그 동작이 막히고, 이유 문장이 클로드 코드에게 전달됩니다. 따라 할 때는 아래 순서로 합니다.

1. 터미널에서 프로젝트 폴더로 이동한 뒤 mkdir -p .claude/hooks로 폴더를 만듭니다.

2. 위 스크립트를 .claude/hooks/protect-env.sh로 저장합니다.

3. chmod +x .claude/hooks/protect-env.sh로 실행 권한을 줍니다.

   주의: 스크립트가 jq(JSON을 읽는 명령줄 도구)를 씁니다. 맥에서는 brew install jq로 설치합니다.

4. .claude/settings.json에 위 설정을 넣습니다. 파일이 이미 있으면 "hooks" 부분만 합칩니다.

5. 클로드 코드를 다시 실행하고 /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/

쇼츠가 권한 4가지 기준

• CLAUDE.md는 200줄 안으로(공식 문서 기준이라는 쇼츠의 말이고, 문서 링크는 영상에 없습니다)
• 단일 주제 규칙은 rules 폴더 파일로
• 절차는 skills로
• 어기면 안 되는 규칙은 hooks로 차단
• 출력이 긴 일은 agents(서브 에이전트)로
• CLAUDE.md에는 "매번 알아야 하는 사실"만(쇼츠 예시: 프로젝트 소개·자주 쓰는 명령어)

wc -l CLAUDE.md

CLAUDE.md를 200줄 안으로 줄이고 싶어.
각 줄을 아래 다섯 가지로 분류한 표를 먼저 보여 줘. 아직 파일은 고치지 마.
1) 매번 알아야 하는 사실 → CLAUDE.md에 남김
2) 주제가 하나인 규칙 → .claude/rules/
3) 순서가 있는 절차 → .claude/skills/
4) 절대 어기면 안 되는 규칙 → hooks 후보
5) 출력이 긴 작업 → .claude/agents/

출처: youtube.com/…