Claude Code 고급 커스터마이징이란?
Claude Code는 Anthropic의 CLI 기반 AI 코딩 에이전트다. 기본적인 코드 생성과 파일 편집만 사용하면 Claude Code의 10% 정도만 활용하는 셈이다. 진짜 생산성 차이는 CLAUDE.md, Skills, Hooks, MCP 서버, 서브에이전트, Agent Teams 같은 고급 커스터마이징 기능에서 발생한다.
왜 이걸 알아야 하는가? r/ClaudeCode 서브레딧에서 2026년 초 기준 주간 활성 기여자 4,200명 이상이 논의 중인 주제의 핵심이 바로 "워크플로우 아키텍처"다. 단순히 프롬프트를 잘 쓰는 것과 Claude Code의 시스템 레벨 기능을 설계하는 것 사이에는 넘기 어려운 생산성 격차가 있다. SWE-bench에서 77.2%의 해결률을 기록하는 Claude Code의 코드 품질을 프로젝트 맥락에 맞게 정밀 제어하는 것이 이 가이드의 목표다.
이 글의 대상과 난이도
대상 독자: Claude Code 기본 사용(코드 생성, 파일 편집, Git 작업)에 익숙한 개발자. CLI 환경과 JSON 설정 파일 편집에 거부감이 없어야 한다.
난이도: 중급-고급
예상 소요시간: 읽기 25분 / 따라하기 60분 이상
이 가이드에서 다루는 6가지 기능은 서로 독립적으로 도입할 수 있다. 전부 한번에 적용할 필요 없이, 자신의 워크플로우에서 가장 큰 병목을 해소하는 것부터 시작하면 된다.
전체 구조
Claude Code의 고급 기능은 3개 레이어로 구성된다.
- Foundation Layer: CLAUDE.md(프로젝트 컨텍스트), Skills(재사용 워크플로우), Hooks(결정적 자동화). 이 세 가지가 Claude Code가 프로젝트를 "이해"하고 규칙을 "준수"하는 기반이다.
- Integration Layer: MCP Servers(외부 도구 연결), Subagents(격리된 태스크 위임), Agent Teams(멀티 세션 병렬 작업). 외부 세계와 연결하고 복잡한 작업을 분산 처리한다.
- Orchestration Result: 위 레이어가 조합되면 코드 작성, 리뷰, 테스트, 배포를 하나의 병렬 파이프라인으로 실행하는 자동화된 개발 파트너가 된다.
이 가이드에서는 Foundation Layer(Step 1-3)를 가장 상세하게 다루고, Integration Layer(Step 4-6)는 설정과 핵심 사용 패턴 위주로 설명한다. Foundation이 탄탄해야 Integration이 제대로 동작하기 때문이다.
도구 선택
6가지 도구 중 어떤 것을 먼저 도입할지는 팀 상황에 따라 다르다. 핵심 판단 기준은 "준수율"이다.
CLAUDE.md와 Skills는 Claude가 지시를 따를 확률이 약 80% 수준이다. 이 말은 5번 중 1번은 무시할 수 있다는 뜻이다. UX Planet의 분석에 따르면 CLAUDE.md에 150-200개 이상의 지시를 넣으면 준수율이 급격히 떨어지는데, 시스템 프롬프트가 이미 약 50개의 지시를 소비하기 때문이다. 반면 Hooks는 셸 명령어 기반이므로 100% 결정적으로 실행된다. 포맷팅, 보안 검사처럼 예외 없이 실행되어야 하는 규칙은 반드시 Hook으로 구현해야 한다.
선택 원칙: CLAUDE.md로 시작하되 200줄을 넘기지 말 것. 반복 워크플로우가 생기면 Skills로 분리. 100% 준수가 필요한 규칙은 Hooks로 강제. 외부 서비스 연동이 필요하면 MCP. 병렬 작업이 필요하면 Subagents나 Agent Teams.
실전 사용법
Step
1: CLAUDE.md - 프로젝트 컨텍스트 주입 (현재 1/6단계 | ~10분)
CLAUDE.md는 Claude Code가 매 세션 시작 시 자동으로 읽는 프로젝트 설명서다. 여기에 빌드 명령어, 아키텍처 개요, 코딩 컨벤션을 넣으면 Claude가 코드만으로는 알 수 없는 프로젝트 맥락을 이해한다.
CLAUDE.md 파일 위치와 우선순위:
| 위치 | 경로 | 적용 범위 |
|---|---|---|
| 개인 전역 | ~/.claude/CLAUDE.md | 모든 프로젝트 |
| 프로젝트 루트 | ./CLAUDE.md | 이 프로젝트만 |
| 하위 디렉터리 | packages/frontend/CLAUDE.md | 해당 패키지만 |
# 프로젝트 CLAUDE.md 예시 (200줄 이내 권장)
## 빌드 & 실행
- `bun install` -> `bun dev` -> localhost:3000
- 테스트: `bun test` (커밋 전 필수)
## 아키텍처
- Next.js 15 App Router + Prisma + PostgreSQL
- 컴포넌트: packages/ui (공유), apps/web (메인)
## 코딩 컨벤션
- TypeScript strict mode 필수
- 함수형 컴포넌트만 사용 (class 컴포넌트 금지)
- API 응답은 반드시 zod 스키마로 검증
체크포인트: 프로젝트 루트에 CLAUDE.md를 생성하고 Claude Code를 실행한 뒤, "이 프로젝트의 기술 스택이 뭐야?"라고 물어봤을 때 CLAUDE.md에 적은 내용을 답하면 성공.
실패 경로: Claude가 CLAUDE.md 내용을 무시한다면, 파일이 너무 길지 않은지 확인한다. 200줄을 초과하면 중요한 지시가 매몰될 수 있다. 태스크별 상세 지시는 별도 마크다운 파일로 분리하고, CLAUDE.md에는 파일 목록과 간단한 설명만 남기는 것을 권장한다.
Step
2: Skills - 재사용 워크플로우 표준화 (현재 2/6단계 | ~15분)
Skills는 .claude/skills/ 디렉터리에 SKILL.md 파일을 만들면 /슬래시-명령어로 호출할 수 있는 재사용 워크플로우다. 기존의 .claude/commands/와 통합되었으며, Skills가 상위 호환이다.
SKILL.md 기본 구조:
---
name: deploy
description: 프로덕션 배포 실행
disable-model-invocation: true
allowed-tools: Bash
---
배포 절차:
1. bun test 실행 (실패 시 중단)
2. bun run build
3. git push origin main
4. 배포 상태 확인
핵심 프론트매터 필드:
description: Claude가 자동 호출 시기를 판단하는 기준. 250자 이내로 핵심 키워드를 앞에 배치.disable-model-invocation: true: 사용자만 수동 호출 가능. 배포, 커밋 등 부작용이 있는 작업에 필수.user-invocable: false: Claude만 자동 호출 가능. 배경 지식/컨벤션 주입용.allowed-tools: 스킬 실행 중 사용 가능한 도구 제한.Read Grep Glob으로 설정하면 읽기 전용 모드.context: fork: 격리된 서브에이전트에서 실행. 메인 대화 컨텍스트에 영향 없음.
동적 컨텍스트 주입 패턴: 스킬 내용에 !`명령어` 구문을 쓰면 스킬이 로드되기 전에 셸 명령어가 실행되고, 그 출력이 프롬프트에 삽입된다.
---
name: pr-summary
description: PR 변경사항 요약
context: fork
---
## PR 컨텍스트
- 변경된 파일: !`gh pr diff --name-only`
- PR 코멘트: !`gh pr view --comments`
위 내용을 기반으로 PR을 요약해주세요.
번들 스킬: Claude Code에 기본 탑재된 스킬도 있다. /batch는 대규모 변경을 5-30개 단위로 분해해 각각 독립 워크트리에서 병렬 실행한다. /simplify는 최근 변경 파일을 3개 리뷰 에이전트가 병렬로 검토한다.
체크포인트:
.claude/skills/deploy/SKILL.md를 만들고 Claude Code에서/deploy를 입력했을 때 스킬이 실행되면 성공.
Step
3: Hooks - 결정적 자동화 (현재 3/6단계 | ~15분)
Hooks는 Claude Code의 라이프사이클 특정 시점에 자동 실행되는 셸 명령어다. CLAUDE.md가 "권고"라면 Hooks는 "강제"다. 2026년 3월 기준 21개의 라이프사이클 이벤트를 지원한다.
핵심 이벤트:
| 이벤트 | 발생 시점 | 대표 용도 |
|---|---|---|
PreToolUse | 도구 실행 직전 | 위험 명령 차단, 보호 파일 접근 거부 |
PostToolUse | 도구 실행 직후 | 자동 포맷팅, 린팅 |
Notification | 알림 발생 시 | 데스크톱 알림 전송 |
SessionStart | 세션 시작/재개 시 | 컨텍스트 재주입 (compact 후) |
Stop | Claude 응답 완료 | 태스크 완료 검증 |
핸들러 유형: 4가지를 지원한다.
- command: 셸 명령어 실행. stdin으로 JSON 입력, exit code로 결과 전달. 가장 기본적이고 빠르다.
- prompt: 단일 턴 LLM 평가. 판단이 필요한 검증에 적합.
- agent: 멀티 턴 서브에이전트. 파일을 읽고 명령어를 실행해서 조건을 검증.
- http: HTTP 엔드포인트로 POST. 팀 공유 감사 서비스 등에 활용.
실전 설정 예시 - 파일 편집 후 자동 포맷팅:
// .claude/settings.json
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
}
]
}
]
}
}
실전 설정 예시 - 보호 파일 차단:
#!/bin/bash
# .claude/hooks/protect-files.sh
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
PROTECTED=(".env" "package-lock.json" ".git/")
for p in "${PROTECTED[@]}"; do
if [[ "$FILE_PATH" == *"$p"* ]]; then
echo "Blocked: $FILE_PATH matches '$p'" >&2
exit 2 # exit 2 = 차단
fi
done
exit 0
중요한 동작 원리: exit 0은 허용, exit 2는 차단이다. 차단 시 stderr에 쓴 메시지가 Claude에게 피드백으로 전달되어 대안을 찾도록 유도한다. PreToolUse Hook에서 deny를 반환하면 bypassPermissions 모드에서도 차단된다. 즉, Hook은 사용자가 우회할 수 없는 정책 레벨의 강제다.
체크포인트: settings.json에 PostToolUse Hook을 추가하고, Claude에게 파일 편집을 시켰을 때 자동으로 Prettier가 실행되면 성공.
/hooks명령어로 등록 확인 가능.
Step
4: MCP Servers - 외부 도구 연결 (현재 4/6단계 | ~10분)
MCP(Model Context Protocol)는 Anthropic이 2024년 11월에 공개한 오픈 표준으로, Claude Code가 외부 데이터 소스와 도구에 직접 접근하는 프로토콜이다. 2026년 4월 기준 공식 레지스트리에 1,000개 이상의 커뮤니티 빌드 서버가 등록되어 있다.
CLI로 MCP 서버 추가:
# GitHub 서버 추가
claude mcp add github --scope user -- npx -y @modelcontextprotocol/server-github
# 등록된 서버 확인
claude mcp list
# 서버 테스트
claude mcp get github
Tool Search 메커니즘: MCP 서버를 많이 연결해도 컨텍스트 윈도우를 과도하게 소비하지 않는다. 세션 시작 시 도구 이름만 로드하고, Claude가 실제로 필요할 때 전체 스키마를 가져오는 지연 로딩(deferred loading) 방식이다.
주의사항: Reddit 개발자 커뮤니티에서 가장 많이 보고되는 불만 중 하나가 MCP 서버로 인한 컨텍스트 윈도우 소비다. 서버를 10개 이상 연결하면 실질적으로 사용 가능한 컨텍스트가 줄어들 수 있다. 프로젝트에 실제로 필요한 서버만 연결하는 것을 권장한다.
Step
5: Subagents - 격리된 태스크 위임 (현재 5/6단계 | ~5분)
Subagent는 메인 세션 안에서 독립 컨텍스트로 태스크를 실행하고 결과만 돌려주는 경량 워커다. Skills에서 context: fork를 설정하거나, Claude가 자체적으로 Task 도구를 사용해 생성한다.
Skills와 Subagents의 조합:
---
name: deep-research
description: 주제를 깊이 조사
context: fork
agent: Explore
---
$ARGUMENTS에 대해 조사해주세요:
1. Glob과 Grep으로 관련 파일 탐색
2. 코드 분석 후 요약
3. 구체적 파일 참조와 함께 결과 보고
agent: Explore는 읽기 전용 도구(Read, Grep, Glob)에 최적화된 내장 에이전트 타입이다. 외에도 Plan, general-purpose, 또는 .claude/agents/에 정의한 커스텀 에이전트를 지정할 수 있다.
Step
6: Agent Teams - 멀티 세션 병렬 작업 (현재 6/6단계 | ~10분)
Agent Teams는 2026년 2월 v2.1.32부터 실험적으로 제공되는 기능으로, 2-16개의 Claude Code 세션을 하나의 팀 리드가 조율하는 멀티 에이전트 시스템이다.
활성화:
// ~/.claude/settings.json
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}
사용 예시:
PR #142를 에이전트 팀으로 리뷰해줘. 3명의 리뷰어를 생성해:
- 보안 관점 리뷰어
- 성능 관점 리뷰어
- 테스트 커버리지 리뷰어
각자 리뷰 후 결과를 종합해줘.
Subagents와의 차이:
| | Subagents | Agent Teams | |---|---|---| | 컨텍스트 | 독립, 결과만 반환 | 독립, 상호 메시지 교환 | | 통신 | 메인 에이전트에만 보고 | 팀원끼리 직접 소통 | | 조율 | 메인 에이전트가 관리 | 공유 태스크 리스트 + 자기 조율 | | 적합한 작업 | 결과만 중요한 집중 작업 | 토론/탐색이 필요한 복잡한 작업 | | 토큰 비용 | 낮음 | 높음 (세션 수만큼 비례) |
실전 팁: 3-5개 팀원으로 시작하고, 팀원당 5-6개 태스크를 배정하는 것이 최적이다. 같은 파일을 여러 팀원이 동시에 편집하면 덮어쓰기가 발생하므로, 각 팀원이 서로 다른 파일 세트를 담당하도록 설계해야 한다. Git worktree를 조합하면 (isolation: "worktree"), 각 팀원이 별도의 워크트리에서 작업하므로 파일 충돌을 원천 차단할 수 있다.
주의: Agent Teams는 실험적 기능이다. 세션 재개 시 in-process 팀원이 복원되지 않고, 태스크 상태 동기화가 지연될 수 있으며, 팀당 하나의 세션만 운영 가능하다는 제약이 있다.
트러블슈팅
CLAUDE.md 지시가 무시될 때
가장 흔한 원인은 파일 길이다. 200줄을 넘으면 지시 준수율이 급격히 떨어진다. 해결법: (1) CLAUDE.md는 200줄 이내로 유지하고, 상세 지시는 .claude/rules/*.md나 별도 파일로 분리한다. (2) 100% 준수가 필요한 규칙은 CLAUDE.md가 아닌 Hook으로 이동한다.
스킬이 자동 트리거되지 않을 때
description 필드에 사용자가 자연어로 말할 법한 키워드가 있어야 한다. 스킬 디스크립션은 250자에서 잘리므로 핵심 키워드를 앞에 배치한다. What skills are available?로 Claude가 인식하는 스킬 목록을 확인할 수 있다. 스킬이 많으면 디스크립션 예산(컨텍스트 윈도우의 1%, 기본 8,000자)이 부족해질 수 있는데, SLASH_COMMAND_TOOL_CHAR_BUDGET 환경변수로 늘릴 수 있다.
Hook이 실행되지 않을 때
(1) /hooks에서 올바른 이벤트에 등록되었는지 확인. (2) matcher가 도구 이름과 정확히 일치하는지 확인 (대소문자 구분). (3) 스크립트에 실행 권한이 있는지 확인 (chmod +x). (4) 셸 프로필(~/.zshrc)에 조건 없는 echo 문이 있으면 JSON 파싱이 깨지므로, [[ $- == *i* ]] 조건으로 감싸야 한다.
MCP 서버 연결 실패
claude mcp list로 서버 상태를 확인한다. npx 기반 서버는 Node.js 버전 호환성 문제가 잦다. claude mcp get 서버이름으로 상세 진단 가능. 환경변수(API 키 등)가 올바르게 설정되었는지 확인한다.
긴 세션에서 성능 저하
Reddit r/ClaudeCode에서 가장 많이 보고되는 문제 중 하나다. 컨텍스트 윈도우가 가득 차면 compaction이 발생하고, 이 과정에서 중요한 컨텍스트가 유실될 수 있다. 해결법: (1) 짧고 집중된 세션을 유지하고, 자율 작업 전에 체크포인트를 커밋한다. (2) 결과가 잘못되면 앞으로 고치려 하지 말고 롤백한다. (3) SessionStart Hook의 compact matcher를 사용해 compaction 후 핵심 컨텍스트를 자동 재주입한다.
더 알아보기
- Claude Code 공식 문서의 Skills 가이드: https://code.claude.com/docs/en/skills
- Claude Code Hooks 레퍼런스: https://code.claude.com/docs/en/hooks
- Claude Code Agent Teams 문서: https://code.claude.com/docs/en/agent-teams
- MCP 공식 사이트: https://modelcontextprotocol.io
- awesome-claude-code (커뮤니티 스킬/훅 모음): https://github.com/hesreallyhim/awesome-claude-code
