CLAUDE.md · Rules · Hooks · Skills · Agents — 클로드 코드 설정 파일 다섯 가지

다섯 개가 각각 무엇을 맡나

클로드 코드를 처음 설치하면 대화창 하나만 보인다. 그 상태로도 일은 되지만, 며칠 쓰다 보면 같은 말을 매번 다시 적고 있는 자신을 발견한다. 이 프로젝트는 이걸로 실행한다, 이 폴더는 건드리지 마라, 커밋 전에는 테스트를 돌려라.

그 반복을 없애는 장치가 다섯 개다. 이름만 보면 비슷해 보이지만 성격이 완전히 다르다. 갈리는 축은 두 가지다. 언제 읽히는가, 그리고 지시인가 강제인가.

먼저 전체 지도를 놓고 시작하자. 아래 표가 이 글 전체의 요약이다.

my-project/
├── CLAUDE.md                  # 매 세션 먼저 읽히는 설명서
└── .claude/
    ├── settings.json          # 훅을 적는 곳
    ├── rules/
    │   ├── testing.md
    │   └── api.md             # paths 로 조건을 걸 수 있다
    ├── skills/
    │   └── deploy/SKILL.md    # /deploy 로 불린다
    └── agents/
        └── code-reviewer.md   # 리뷰를 딴 창에서 시킨다

CLAUDE.md — 세션이 시작될 때 가장 먼저 읽히는 파일

이름 그대로 파일 하나다. 프로젝트 폴더에 CLAUDE.md 라는 이름으로 만들어 두면, 클로드 코드가 켜질 때마다 그 내용을 먼저 읽고 대화를 시작한다.

왜 필요한가. 언어 모델은 지난 대화를 기억하지 못한다. 기억하는 것처럼 보이는 이유는 매번 저장해 둔 내용을 프롬프트와 함께 다시 보내기 때문이고, 그 저장해 둔 내용이 바로 이 파일이다. 어제 알려 준 빌드 명령을 오늘 다시 알려 주고 싶지 않다면 여기에 적는다.

무엇을 적나. 다시 설명하게 될 것을 적는다. 같은 실수를 두 번째로 봤을 때, 같은 정정을 지난 세션에도 쳤을 때, 새 팀원이라면 똑같이 물어봤을 내용일 때가 추가 신호다. 구체적으로는 프로젝트가 무엇을 하는 것인지, 어떤 기술로 만들었는지, 어떤 명령으로 실행·테스트·배포하는지, 그리고 절대 하지 말아야 할 것이 무엇인지다.

파일은 네 자리에 둘 수 있고 넓은 범위부터 좁은 범위 순으로 전부 합쳐져 읽힌다. 조직 전체에 배포하는 관리 정책 파일, 내 계정 전체에 적용되는 ~/.claude/CLAUDE.md, 팀과 공유하는 프로젝트의 CLAUDE.md, 그리고 나만 쓰는 CLAUDE.local.md 다. 마지막 것은 .gitignore 에 넣어 커밋되지 않게 둔다.

빈 화면에서 시작하기 어렵다면 터미널에서 /init 을 치면 된다. 클로드가 코드베이스를 훑어 빌드 명령·테스트 방법·발견한 관례를 담은 초안을 만들어 준다. 이미 파일이 있으면 덮어쓰지 않고 개선안을 제안한다.

여기서 초보자가 가장 많이 하는 실수가 길이다. 자기소개서처럼 길게 쓰는 것인데, 공식 문서는 파일 하나당 200줄 아래를 권한다. 이 파일은 매 세션 통째로 컨텍스트에 올라가므로 길수록 토큰을 먹고, 길수록 지켜지는 확률이 떨어진다. 표현도 검증 가능할 만큼 구체적인 편이 낫다. 코드를 깔끔하게 포맷하라보다 들여쓰기는 공백 2칸을 쓴다가 실제로 지켜진다.

그리고 반드시 알아야 할 사실이 하나 있다. CLAUDE.md 는 설정이 아니라 맥락이다. 시스템 프롬프트가 아니라 사용자 메시지 형태로 전달되므로 클로드가 읽고 참고할 뿐, 반드시 지킨다는 보장이 없다. 무조건 막아야 하는 것이 있다면 그건 뒤에 나올 훅의 몫이다.

파일이 실제로 읽혔는지 확인하려면 세션에서 /context 를 쳐 메모리 파일 목록을 본다. 파일을 열어 고치려면 /memory 다.

다른 도구용으로 AGENTS.md 를 이미 쓰고 있다면 클로드 코드는 그 파일을 읽지 않는다. CLAUDE.md 를 만들어 첫 줄에 @AGENTS.md 라고 적어 불러오면 한 벌로 관리된다.

# my-shop

## 프로젝트
Next.js 15 + Supabase 로 만든 온라인 주문 페이지.

## 명령
- 개발 서버: `npm run dev`
- 테스트: `npm test`
- 배포: `vercel deploy --prod`

## 규칙
- 결제 금액 계산은 `src/lib/price.ts` 한 곳에서만 한다.
- 커밋 전에 반드시 `npm test` 를 돌린다.
- `.env` 파일은 절대 열지도 커밋하지도 않는다.

Rules — CLAUDE.md 가 길어지면 여기로 쪼갠다

200줄 아래로 유지하라는 말은 곧 넘치는 것을 어디로 보낼지의 문제를 만든다. 그 자리가 .claude/rules/ 다.

만드는 법은 단순하다. 프로젝트에 .claude/rules/ 폴더를 만들고 그 안에 마크다운 파일을 주제별로 넣는다. testing.md, api-design.md, security.md 처럼 파일 이름만 봐도 무슨 규칙인지 알 수 있게 둔다. 하위 폴더로 더 나눠도 전부 찾아 읽는다.

여기까지만 하면 CLAUDE.md 를 여러 파일로 나눈 것과 다르지 않다. 진짜 차이는 다음 기능에서 나온다.

파일 맨 위에 paths 를 적으면 조건부가 된다. 아래 예시처럼 글롭 패턴을 적어 두면, 클로드가 그 패턴에 맞는 파일을 실제로 열었을 때만 그 규칙이 컨텍스트에 올라온다. 프런트엔드를 고치는 동안 API 규칙 서른 줄이 자리를 차지하지 않는다는 뜻이다.

paths 가 없는 규칙 파일은 조건 없이 세션 시작 때 전부 읽힌다. 우선순위는 .claude/CLAUDE.md 와 같다.

패턴은 흔한 글롭 문법이다. **/*.ts 는 모든 타입스크립트 파일, src/**/* 는 src 아래 전부, *.md 는 루트의 마크다운 파일, src/components/*.tsx 는 그 폴더의 리액트 컴포넌트만 가리킨다. src/**/*.{ts,tsx} 처럼 중괄호로 확장자를 묶을 수도 있다.

프로젝트가 아니라 나에게 붙는 규칙도 있다. ~/.claude/rules/ 에 두면 내 모든 프로젝트에 적용된다. 읽는 순서는 개인 규칙이 먼저이고 프로젝트 규칙이 나중이라, 프로젝트 쪽이 더 센 위치를 갖는다.

한 가지 구분만 기억하면 된다. 규칙은 항상, 또는 해당 파일을 만질 때 자동으로 컨텍스트에 올라온다. 반면 다음에 나올 스킬은 부를 때만 올라온다. 늘 지켜야 하는 문장이면 규칙, 특정 작업을 할 때만 필요한 절차면 스킬이다.

---
paths:
  - "src/api/**/*.ts"
---

# API 작성 규칙

- 모든 엔드포인트는 입력값 검증을 거친다.
- 오류 응답은 정해진 형식 하나만 쓴다.
- 새 엔드포인트에는 OpenAPI 주석을 단다.

Hooks — 지키라고 부탁하는 대신 코드로 막는다

앞의 둘은 모두 지시였다. 클로드가 읽고 참고하지만 안 지킬 수도 있다. 반드시 지켜져야 하는 것이 있다면 성격이 다른 장치가 필요하고, 그것이 훅이다.

훅은 정해진 사건이 일어날 때마다 자동으로 실행되는 셸 명령이다. 클로드가 판단해서 실행하는 것이 아니라, 조건이 맞으면 무조건 돈다. 그래서 이것만이 강제다.

적는 곳은 .claude/settings.json 이다. 구조는 세 겹이다. 어떤 사건에 걸 것인지, 그 사건 안에서 무엇에만 걸 것인지, 그리고 실행할 명령이 무엇인지.

사건의 이름은 여럿인데 처음에는 다섯만 알면 충분하다. SessionStart 는 세션이 시작될 때, UserPromptSubmit 는 내가 프롬프트를 보낼 때, PreToolUse 는 도구가 실행되기 직전, PostToolUse 는 실행된 직후, Stop 은 클로드가 답을 마칠 때다.

matcher 는 그 사건 안에서 대상을 좁히는 값이다. 도구 계열 사건에서는 도구 이름으로 거른다. Bash 라고 적으면 Bash 도구에만, Edit|Write 처럼 세로줄로 나열하면 둘 다에 걸린다. 비워 두거나 * 를 적으면 전부에 걸린다.

실행된 명령은 표준입력으로 JSON 을 받는다. 그 안에 어떤 사건인지, 어떤 도구인지, 그 도구에 어떤 인자가 들어갔는지가 담겨 있다. 아래 예시가 그 값을 읽어 강제 푸시를 막는 훅이다.

여기서 핵심은 종료 코드다. 이 값이 훅의 결정이다. 0 으로 끝나면 통과이고, 2 로 끝나면 그 도구 호출이 취소되면서 stderr 에 적은 문장이 클로드에게 사유로 전달된다. 그 외의 값은 오류로 기록되지만 작업은 그대로 진행된다.

실제로 무엇에 쓰나. 파일을 고친 뒤 자동으로 포맷터를 돌리거나, 특정 폴더 수정을 막거나, 작업이 끝났을 때 알림을 보내는 용도가 흔하다. CLAUDE.md 에 커밋 전에 테스트를 돌려라라고 적어 두었는데 자꾸 건너뛴다면, 그 문장은 훅으로 내려야 할 문장이다.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/no-force-push.sh"
          }
        ]
      }
    ]
  }
}

#!/bin/bash
# 훅은 표준입력으로 JSON 을 받는다. tool_input.command 안에 실행될 명령이 들어 있다.
cmd=$(jq -r '.tool_input.command // ""')

if [[ "$cmd" == *"push --force"* || "$cmd" == *"push -f"* ]]; then
  # 종료 코드 2 = 차단. stderr 에 적은 문장이 클로드에게 사유로 전달된다.
  echo "강제 푸시는 이 저장소에서 금지입니다. --force-with-lease 를 쓰세요." >&2
  exit 2
fi

exit 0

Skills — 반복하는 절차를 슬래시 명령으로

채팅창에 같은 지시 묶음을 반복해서 붙여넣고 있다면, 또는 CLAUDE.md 의 한 대목이 사실이 아니라 절차로 자라 있다면, 그것이 스킬로 옮길 신호다.

만드는 법은 폴더 하나와 파일 하나다. .claude/skills/ 아래에 이름으로 폴더를 만들고 그 안에 SKILL.md 를 둔다. 그 폴더 이름이 그대로 명령어가 되어 /이름 으로 불린다.

SKILL.md 는 두 부분이다. 위쪽 세 줄짜리 구분선 사이에 들어가는 프론트매터, 그리고 그 아래 본문이다. 프론트매터의 필드는 전부 선택이지만 description 은 사실상 필수다. 클로드가 이 설명을 읽고 언제 이 스킬을 쓸지 판단하기 때문이다. 무엇을 하는지와 언제 쓰는지를 함께 적는다.

본문에는 클로드가 따를 지시를 그대로 쓴다. 여기서 스킬의 진짜 장점이 나온다. 본문은 스킬이 실제로 쓰일 때만 읽히므로, 길게 써도 평소 컨텍스트를 전혀 먹지 않는다. CLAUDE.md 에 긴 절차를 넣으면 매 세션 비용이 들지만 스킬은 0이다.

부르는 방법은 둘이다. 직접 /이름 을 치거나, description 에 맞는 요청을 하면 클로드가 알아서 불러온다. 자동 호출을 원치 않고 손으로만 쓰고 싶으면 프론트매터에 disable-model-invocation 을 true 로 둔다.

본문에서 느낌표와 백틱으로 명령을 감싸면 그 자리에 실행 결과가 미리 채워진 채로 전달된다. 아래 예시의 git diff 가 그것이다. 클로드가 스킬을 읽는 시점에 이미 변경분이 안에 들어 있다.

두는 위치는 세 곳이다. ~/.claude/skills/ 는 내 모든 프로젝트에서, 프로젝트의 .claude/skills/ 는 그 프로젝트에서만, 플러그인 안의 skills/ 는 그 플러그인이 켜진 곳에서 쓰인다. 참고로 예전의 .claude/commands/ 는 스킬로 합쳐졌다. 기존 파일은 그대로 동작한다.

파일을 고치면 세션을 껐다 켤 필요 없이 바로 반영된다.

---
description: 바뀐 내용을 요약하고 위험해 보이는 부분을 짚는다. 무엇이 바뀌었는지 묻거나 커밋 메시지를 원할 때 쓴다.
---

## 현재 변경분

!`git diff HEAD`

## 지시

위 변경분을 두세 줄로 요약하고, 빠진 예외 처리·하드코딩된 값·같이 고쳐야 할 테스트가
있으면 목록으로 적는다. 변경분이 비어 있으면 그렇다고만 답한다.

Agents — 딴 일을 딴 창에서 시킨다

앞의 넷이 클로드에게 무엇을 어떻게 하라고 말하는 장치였다면, 마지막 하나는 누가 할지를 나누는 장치다.

서브에이전트는 자기만의 컨텍스트 창을 따로 갖는 보조 클로드다. 일을 넘기면 그쪽 창에서 혼자 진행하고 결과 요약만 돌려준다. 코드베이스를 뒤지느라 쏟아진 검색 결과와 파일 내용이 내 대화창에 쌓이지 않는다는 뜻이다. 컨텍스트 윈도우가 꽉 찰수록 답이 나빠지는 것을 생각하면 이게 왜 도구인지 알 수 있다.

만드는 법은 마크다운 파일 하나다. .claude/agents/ 아래에 파일을 두고 프론트매터에 네 가지를 적는다. name 은 소문자와 하이픈으로 된 고유 이름, description 은 언제 이 에이전트에게 넘길지, tools 는 쓸 수 있는 도구 목록, model 은 어느 모델로 돌릴지다.

name 과 description 은 필수이고 나머지는 생략할 수 있다. tools 를 비우면 서브에이전트가 쓸 수 있는 도구를 전부 물려받는다. 읽기 전용으로 두고 싶으면 Read, Grep, Glob 정도만 적으면 파일을 고칠 수 없게 된다. model 을 haiku 로 두면 값싼 모델로 돌아 비용이 줄고, 생략하면 본 대화의 모델을 물려받는다.

위치는 두 곳이다. ~/.claude/agents/ 는 내 모든 프로젝트에서 쓰이고, 프로젝트의 .claude/agents/ 는 그 저장소에서만 쓰인다. 후자는 커밋해 두면 팀이 함께 쓰고 함께 고칠 수 있다.

직접 만들지 않아도 이미 들어 있는 것들이 있다. Explore 는 코드베이스를 뒤지는 읽기 전용 에이전트이고, Plan 은 계획 모드에서 조사를 맡고, General-purpose 는 탐색과 수정이 모두 필요한 복합 작업을 맡는다. 클로드는 각 에이전트의 description 을 보고 넘길지 말지를 정하므로, 직접 만들 때는 그 설명을 언제 쓰라는 문장으로 쓰는 것이 중요하다.

파일을 새로 만들었는데 안 보이면 세션을 다시 켠다. agents 폴더 자체가 세션 시작 시점에 없었던 경우에만 생기는 일이다.

---
name: code-improver
description: 파일을 훑어 가독성·성능·관행 측면의 개선점을 제안한다. 코드를 쓰거나 고친 뒤에 쓴다.
tools: Read, Grep, Glob
model: sonnet
---

너는 코드 개선 전문가다. 발견한 문제마다 무엇이 문제인지 설명하고,
현재 코드를 보여 준 뒤, 고친 코드를 제시한다.

다섯 중 무엇을 고를까

이름과 형식을 다 알아도 실제로 막히는 지점은 여기다. 방금 손에 든 이 문장을 어디에 넣어야 하나.

질문 세 개로 갈린다. 첫째, 항상 알고 있어야 하는 사실인가 아니면 특정 작업의 절차인가. 사실이면 CLAUDE.md, 절차면 스킬이다. 둘째, 특정 파일을 만질 때만 필요한가. 그렇다면 paths 를 건 규칙이다. 셋째, 어겨도 되는 권고인가 아니면 반드시 막아야 하는가. 후자면 훅이다.

그리고 넷째가 하나 더 있다. 이 작업이 끝나면 그 과정의 로그를 다시 볼 일이 있나. 없다면 에이전트에게 넘겨 내 대화창을 깨끗하게 둔다.

흔한 실수도 대칭으로 나타난다. 절차를 CLAUDE.md 에 넣어 파일이 300줄로 부풀고 결국 아무것도 안 지켜지는 경우가 하나, 반드시 막아야 할 것을 CLAUDE.md 의 문장으로 적어 두고 안 지켜진다고 답답해하는 경우가 다른 하나다. 앞은 스킬로, 뒤는 훅으로 옮기면 풀린다.

지금 해볼 것

다섯을 한꺼번에 만들 필요는 없다. 순서가 있고, 앞의 것이 넘칠 때 다음 것으로 넘어가는 구조다.

먼저 작업 중인 프로젝트에서 /init 을 친다. 클로드가 코드베이스를 훑어 CLAUDE.md 초안을 만들어 준다. 나온 초안을 열어 명령어가 맞는지 확인하고, 클로드가 알 수 없는 규칙 몇 줄을 손으로 더한다. 여기까지가 첫날 할 일이다.

그다음은 반응형이다. 파일이 200줄에 가까워지면 주제별로 .claude/rules/ 로 쪼개고, 특정 폴더에서만 통하는 것에는 paths 를 건다. 같은 지시 묶음을 세 번째 붙여넣고 있으면 .claude/skills/ 로 옮긴다. 적어 두었는데도 계속 안 지켜지는 문장이 있으면 그건 훅으로 내릴 문장이다. 조사하느라 대화창이 로그로 덮이면 에이전트를 만든다.

확인은 /context 로 한다. 지금 세션에 어떤 파일이 실제로 올라와 있는지, 컨텍스트가 몇 퍼센트 찼는지가 한 화면에 나온다. 적어 두었는데 목록에 없다면 내용 문제가 아니라 위치 문제다.