Claude Code 완전 정복 3편 — CLAUDE.md, 스킬, 서브에이전트, 훅, MCP로 내 프로젝트에 맞추기

매번 같은 설명을 반복하고 있다면

Claude Code를 며칠 쓰다 보면 같은 말을 반복하게 됩니다. "패키지 매니저는 yarn이야", "테스트는 이 명령으로 돌려", "커밋 메시지는 이 형식으로 써". 세션이 바뀔 때마다 Claude는 이 내용을 처음부터 모릅니다.

Claude Code에는 이런 반복을 없애는 장치가 다섯 가지 있습니다. 이 글은 Claude Code 시리즈 3편으로, 각 장치가 무엇이고 언제 쓰는지를 정리합니다.

장치	한 줄 설명	저장 위치 (예)
CLAUDE.md	매 세션 시작할 때 읽는 지침서	프로젝트 루트, ~/.claude/
스킬(Skill)	필요할 때 꺼내 쓰는 작업 매뉴얼	.claude/skills/<이름>/SKILL.md
서브에이전트	별도 맥락에서 일하는 전문 조수	.claude/agents/<이름>.md
훅(Hook)	특정 시점에 반드시 실행되는 스크립트	.claude/settings.json
MCP	외부 서비스(Notion, DB 등) 연결	claude mcp add로 등록

1. CLAUDE.md: 매번 읽는 지침서

CLAUDE.md는 Claude Code가 세션을 시작할 때마다 자동으로 읽는 마크다운 파일입니다. 빌드 명령, 코드 규칙, 프로젝트 구조처럼 매번 알려 줘야 하는 내용을 여기에 적습니다.

어디에 두나

범위	위치	공유 대상
개인 (모든 프로젝트)	~/.claude/CLAUDE.md	나만
프로젝트	./CLAUDE.md 또는 ./.claude/CLAUDE.md	git으로 팀 전체
프로젝트 개인용	./CLAUDE.local.md (.gitignore에 추가)	나만

시작하는 법

처음이라면 /init을 실행하세요. Claude가 코드베이스를 분석해서 빌드 명령, 테스트 방법, 발견한 규칙을 담은 초안을 만들어 줍니다. 이미 CLAUDE.md가 있으면 개선점을 제안합니다.

1# 프로젝트 규칙
2
3- 패키지 매니저는 yarn을 사용한다 (npm 금지)
4- 개발 서버: `yarn dev`, 테스트: `yarn test`
5- 컴포넌트는 `src/components/<이름>/index.tsx` 구조를 따른다
6- 커밋 메시지 형식: `<type>(<scope>): <subject>`
7
8API 명세는 @docs/api.md 참고

마지막 줄의 @docs/api.md처럼 @경로를 쓰면 다른 파일을 불러올 수 있습니다.

잘 쓰는 요령

• 200줄 이하로 유지합니다. 공식 문서의 권장 기준입니다. 길어질수록 맥락을 많이 차지하고, 중요한 규칙이 묻혀서 오히려 잘 안 지킵니다.
• Claude가 이미 잘하는 건 지웁니다. 지시가 없어도 잘 지키는 내용은 공간만 차지합니다.
• "반드시" 지켜야 하는 규칙은 훅으로 옮깁니다. CLAUDE.md는 지침이라 가끔 놓칠 수 있습니다. 강제가 필요하면 아래의 훅을 씁니다.

참고로 Claude Code에는 자동 메모리(auto memory) 기능도 있습니다. 내가 고쳐 준 내용이나 선호를 Claude가 스스로 기록해서 다음 세션에 활용합니다. CLAUDE.md는 내가 쓰는 규칙, 자동 메모리는 Claude가 쌓는 노트라고 생각하면 됩니다.

2. 스킬: 필요할 때만 꺼내는 매뉴얼

CLAUDE.md는 매번 전부 읽힙니다. 반면 스킬은 이름과 설명만 미리 알고 있다가, 필요할 때 전체 내용을 불러옵니다. 그래서 가끔 쓰는 긴 절차(배포, 릴리스 노트 작성, 특정 형식의 리뷰)는 스킬로 만드는 편이 맥락을 아낍니다.

예를 들어 변경 내용을 요약하는 스킬은 이렇게 만듭니다.

1mkdir -p ~/.claude/skills/summarize-changes

~/.claude/skills/summarize-changes/SKILL.md:

1---
2description: 커밋하지 않은 변경 사항을 요약하고 위험 요소를 짚는다. 무엇이 바뀌었는지 묻거나 커밋 메시지가 필요할 때 사용.
3---
4
5## 현재 변경 사항
6
7!`git diff HEAD`
8
9## 지시
10
11위 변경 사항을 2~3개 항목으로 요약하고, 빠진 에러 처리나 하드코딩된 값,
12업데이트가 필요한 테스트 같은 위험 요소를 나열한다.

두 가지가 눈에 띕니다.

• description이 중요합니다. Claude는 이 설명을 보고 언제 이 스킬을 쓸지 스스로 판단합니다. "무엇이 바뀌었어?"라고 물으면 알아서 이 스킬을 씁니다.
• !`git diff HEAD`는 스킬이 실행될 때 명령 결과로 바뀌어 들어갑니다. 최신 diff를 들고 시작하는 셈입니다.

직접 부를 수도 있습니다. 폴더 이름이 명령이 되어 /summarize-changes로 실행됩니다. 예전의 커스텀 슬래시 명령(.claude/commands/)도 스킬로 합쳐져서 같은 방식으로 동작합니다.

3. 서브에이전트: 맥락을 나눠 쓰는 조수

큰 코드베이스에서 "이 기능이 어디서 쓰이는지 전부 찾아줘"라고 하면 Claude가 수십 개 파일을 읽으면서 대화 맥락이 가득 찹니다. 서브에이전트는 별도의 맥락에서 일하고 결과만 요약해서 돌려줍니다. 메인 대화는 깔끔하게 유지됩니다.

~/.claude/agents/code-improver.md:

1---
2name: code-improver
3description: 가독성, 성능, 모범 사례 관점에서 코드를 검토하고 개선안을 제안한다. 코드를 작성하거나 수정한 뒤 사용.
4tools: Read, Grep, Glob
5model: sonnet
6---
7
8당신은 코드 개선 전문가입니다. 발견한 문제마다 문제점, 현재 코드,
9개선된 코드를 함께 제시하세요.

• tools로 쓸 수 있는 도구를 제한할 수 있습니다. 위 예시는 읽기 도구만 줘서 파일을 고칠 수 없게 했습니다.
• model로 이 조수만 다른 모델을 쓰게 할 수 있습니다.
• ~/.claude/agents/에 두면 모든 프로젝트에서, 프로젝트의 .claude/agents/에 두면 그 프로젝트에서만 쓸 수 있습니다.

굳이 파일을 만들지 않아도 "서브에이전트를 써서 조사해줘"라고 요청하면 Claude가 알아서 별도 맥락에서 조사를 맡깁니다.

4. 훅: 반드시 실행되는 규칙

CLAUDE.md에 "파일 수정 후 Prettier를 돌려"라고 적어도 Claude가 가끔 잊을 수 있습니다. 훅은 Claude의 판단과 상관없이 정해진 시점에 항상 실행되는 스크립트입니다.

예시 1: 파일을 고칠 때마다 Prettier 실행

프로젝트의 .claude/settings.json:

1{
2  "hooks": {
3    "PostToolUse": [
4      {
5        "matcher": "Edit|Write",
6        "hooks": [
7          {
8            "type": "command",
9            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
10          }
11        ]
12      }
13    ]
14  }
15}

PostToolUse는 "도구를 쓴 직후", matcher의 Edit|Write는 "파일을 고치거나 썼을 때만"이라는 뜻입니다. 훅은 실행할 때 입력값을 JSON으로 받기 때문에 jq로 파일 경로를 꺼냅니다. Mac에 jq가 없다면 brew install jq로 설치합니다.

예시 2: 중요한 파일 수정 막기

PreToolUse 훅은 도구를 쓰기 직전에 실행되고, 스크립트가 종료 코드 2로 끝나면 그 작업을 막습니다. 이걸 이용하면 .env나 lock 파일을 Claude가 건드리지 못하게 할 수 있습니다. 막힌 이유는 Claude에게 전달되기 때문에, Claude가 다른 방법을 찾습니다.

자주 쓰는 훅 시점은 이렇습니다.

이벤트	실행 시점
SessionStart	세션이 시작되거나 재개될 때
UserPromptSubmit	내가 메시지를 보낸 직후, Claude가 처리하기 전
PreToolUse	도구 실행 직전 (막을 수 있음)
PostToolUse	도구 실행 성공 직후
Notification	Claude가 알림을 보낼 때 (2편의 알림 설정)
Stop	Claude가 응답을 마쳤을 때

5. MCP: 외부 서비스 연결

MCP(Model Context Protocol)는 Claude가 외부 도구와 데이터에 접근하게 해 주는 표준 연결 방식입니다. Notion 문서를 읽거나, DB를 조회하거나, 이슈 트래커를 다루는 식입니다.

원격 서버는 한 줄로 추가합니다.

1claude mcp add --transport http notion https://mcp.notion.com/mcp

등록 범위는 세 가지입니다.

범위	옵션	적용 대상
local (기본값)	생략	추가한 프로젝트에서 나만
project	--scope project	프로젝트의 .mcp.json에 저장, git으로 팀과 공유
user	--scope user	내 Mac의 모든 프로젝트

연결이 잘 됐는지는 claude mcp get <이름>으로 확인합니다.

6. 플러그인: 묶음으로 설치하기

스킬, 훅, 서브에이전트, MCP 서버를 하나로 묶어 설치하는 것이 플러그인입니다. 세션 안에서 /plugin을 실행하면 마켓플레이스를 둘러보고 설치할 수 있습니다. 다른 사람이 만든 설정을 그대로 가져다 쓰고 싶을 때 편합니다.

다만 플러그인은 내 컴퓨터에서 명령을 실행할 수 있는 훅이나 MCP 서버를 포함할 수 있습니다. 출처를 믿을 수 있는 것만 설치하는 것이 좋습니다.

무엇을 언제 쓸까

• 매번 알아야 하는 짧은 규칙 → CLAUDE.md
• 가끔 쓰는 긴 절차 → 스킬
• 많이 읽어야 하는 조사, 독립적인 검토 → 서브에이전트
• 예외 없이 지켜야 하는 규칙 → 훅
• 코드 밖의 서비스와 데이터 → MCP

핵심 한 줄

반복해서 하는 설명은 CLAUDE.md와 스킬로, 반드시 지켜야 하는 규칙은 훅으로 옮기면 됩니다. 그러면 Claude Code는 세션마다 처음부터 다시 가르쳐야 하는 도구가 아니라, 내 프로젝트를 아는 동료처럼 일하게 됩니다.

다음 편에서는 계획 모드, 병렬 세션, 자동화까지 Claude Code를 끝까지 활용하는 방법을 다룹니다.

참고 자료

• 메모리와 CLAUDE.md
• 스킬
• 서브에이전트
• 훅 가이드
• MCP