Claude Code 활용 가이드 2026

Claude Code를 효과적으로 사용하는 방법을 정리한 가이드입니다. 

목차

1. 초기화 및 설정
2. SKILL 시스템
3. Subagents (전문 에이전트)
4. SKILL vs Subagent 차이점
5. MCP 서버 통합
6. Hooks 자동화
7. 핵심 모범 사례
8. Claude Code 작업 가이드라인 (실전 예시)

---

1. 초기화 및 설정

CLAUDE.md 작성 (핵심)

CLAUDE.md는 모든 세션 시작 시 Claude가 읽는 특별 파일입니다.

파일 위치:

• 전역: ~/.claude/CLAUDE.md (모든 프로젝트)
• 프로젝트: ./CLAUDE.md (git 커밋 권장)
• 프로젝트 로컬: ./CLAUDE.local.md (git 무시)

포함 가이드라인:

✅ 포함	❌ 제외
Bash 명령어 (추측 불가능한 것)	코드에서 알 수 있는 것
코드 스타일 (기본값과 다른)	표준 언어 규칙
테스트 지침 및 선호 러너	긴 API 문서
저장소 에티켓 (브랜치 명명, PR 규칙)	자주 변경되는 정보
아키텍처 결정	파일별 코드베이스 설명
개발 환경 특이사항 (필수 env vars)	자명한 것들

좋은 예시:

# Code style
- Use ES modules (import/export) syntax
- Destructure imports when possible

# Workflow
- Typecheck after code changes
- Prefer running single tests for performance

/init 명령어

/init

/init 명령어로 코드베이스를 자동 분석하여 빌드 시스템, 테스트 프레임워크, 코드 패턴을 감지할 수 있습니다.

---

2. SKILL 시스템

Skill이란?

Skills는 Claude의 기능을 확장하는 재사용 가능한 지시사항 모음입니다. 사용자가 직접 호출하거나 Claude가 자동으로 로드할 수 있습니다.

Skill 생성 방법

# 디렉토리 생성
mkdir -p ~/.claude/skills/explain-code

# SKILL.md 작성
cat > ~/.claude/skills/explain-code/SKILL.md << 'EOF'
---
name: explain-code
description: 코드를 시각 다이어그램과 비유로 설명합니다
---

코드 설명 시 포함:
1. **비유로 시작**: 일상생활과 비교
2. **다이어그램**: ASCII art로 흐름 표시
3. **코드 설명**: 단계별 설명
4. **gotcha 강조**: 일반적인 실수
EOF

Skill 실행 방법

• 자동 호출: description과 일치하는 질문
• 직접 호출: /explain-code src/auth/login.ts

Skill Frontmatter 필드

필드	설명
name	슬래시 명령어 이름
description	Claude가 언제 사용할지 결정
disable-model-invocation	true면 사용자만 호출 가능
user-invocable	false면 Claude만 사용 가능
allowed-tools	스킬 활성화 시 승인 없이 사용할 도구
context	fork면 하위 에이전트에서 실행
agent	context: fork 시 사용할 에이전트 타입

---

3. Subagents (전문 에이전트)

Subagent란?

독립된 컨텍스트에서 실행되는 전문화된 에이전트입니다. 메인 컨텍스트를 망치지 않고 방대한 코드베이스를 조사하거나 특정 작업에 집중할 때 유용합니다.

Subagent 생성

mkdir -p ~/.claude/agents

cat > ~/.claude/agents/security-reviewer.md << 'EOF'
---
name: security-reviewer
description: 코드의 보안 취약점을 검토합니다
tools: Read, Grep, Glob, Bash
model: opus
---

보안 엔지니어로서 코드를 검토하세요:
- 인젝션 취약점 (SQL, XSS, 명령어 인젝션)
- 인증 및 인가 결함
- 코드 내 비밀키 또는 자격증명
- 안전하지 않은 데이터 처리
EOF

내장 Subagent 유형

에이전트	용도	도구
Explore	코드베이스 탐색	읽기 전용
Plan	구현 계획 수립	모든 도구 (Edit/Write 제외)
general-purpose	일반 작업	모든 도구

---

4. SKILL vs Subagent 차이점

둘 다 병렬 작업이 가능하지만, 목적과 사용 방식에 명확한 차이가 있습니다.

핵심 차이 비교

특징	SKILL	Subagent
목적	재사용 가능한 작업 패턴 정의	독립된 컨텍스트에서 특정 작업 수행
컨텍스트	메인 컨텍스트에서 실행	완전히 분리된 독립 컨텍스트
상태 공유	메인 대화 상태 유지	메인과 상태 분리
실행 방식	description으로 자동 로드 또는 /명령어	Task tool로 명시적 호출
사용 시점	반복적인 작업 패턴이 있을 때	방대한 코드베이스 조사 또는 특정 작업 집중
예시	코드 설명, 리뷰, 테스트 작성 패턴	보안 검토, 코드베이스 탐색, 구현 계획

언제 무엇을 사용해야 할까?

SKILL 사용이 적합한 경우:

• 프로젝트 특정의 반복 작업 (예: "우리 프로젝트의 API 라우트 작성 방법")
• 자주 사용하는 작업의 표준화 (예: 코드 리뷰 체크리스트)
• 사용자가 직접 호출하는 커맨드로 만들 때
• 메인 컨텍스트의 정보가 필요할 때

Subagent 사용이 적합한 경우:

• 방대한 코드베이스를 조사해야 할 때 (메인 컨텍스트 보호)
• 특정 전문 분야 작업 (예: 보안 전문가, 성능 최적화)
• 실험적 작업 (메인 대화에 영향 주지 않음)
• 병렬로 여러 독립 작업 실행

실제 예시:

# SKILL 예시 - 프로젝트 특정 패턴
# ~/.claude/skills/api-route.md
name: api-route
description: Next.js API 라우트 작성

# Subagent 예시 - 보안 검토
# ~/.claude/agents/security-audit.md
name: security-audit
tools: Read, Grep, Glob, Bash

---

5. MCP 서버 통합

MCP란?

Model Context Protocol (MCP)는 Claude가 외부 도구와 데이터 소스에 연결할 수 있는 오픈 소스 표준입니다.

MCP 서버 설정

~/.claude/settings.json 또는 .claude/settings.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    }
  }
}

인기 있는 MCP 서버

서버	설명
@modelcontextprotocol/server-filesystem	파일 시스템 접근
@modelcontextprotocol/server-github	GitHub 통합
@modelcontextprotocol/server-postgres	PostgreSQL 쿼리
@modelcontextprotocol/server-brave-search	웹 검색

---

6. Hooks 자동화

Hook이란?

Hook은 Claude Code 라이프사이클의 특정 지점에서 자동으로 실행되는 셸 명령어입니다.

주요 Hook 이벤트

이벤트	발생 시점
SessionStart	세션 시작 또는 재개
PreToolUse	도구 호출 전 (차단 가능)
PostToolUse	도구 호출 성공 후
Notification	알림 전송 시
Stop	Claude 응답 완료 시

Hook 설정 예시

알림 훅 (Linux):

{
  "hooks": {
    "Notification": [
      {
        "hooks": [{
          "type": "command",
          "command": "notify-send 'Claude Code' '입력 필요'"
        }]
      }
    ]
  }
}

자동 포맷팅:

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{
        "type": "command",
        "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
      }]
    }]
  }
}

---

7. 핵심 모범 사례

검증 가능한 작업 지시

❌ Before	✅ After
이메일 검증 함수 구현	validateEmail 함수 작성. 테스트 케이스: test@example.com은 true, invalid는 false. 구현 후 테스트 실행
대시버드 개선	[스크린샷] 이 디자인 구현. 결과 스크린샷 찍고 원본과 비교

구체적인 프롬프트

❌ Before	✅ After
foo.py에 테스트 추가	foo.py에 사용자 로그아웃 엣지 케이스 covering 테스트 작성. mock 사용 금지
ExecutionFactory API가 이상한 이유	ExecutionFactory의 git 히스토리를 살펴보고 API가 어떻게 되었는지 요약

컨텍스트 관리

• 작업 간 /clear 사용
• Esc + Esc 또는 /rewind로 특정 지점부터 요약
• SessionStart hook으로 컴팩션 후 컨텍스트 재주입

---

8. Claude Code 작업 가이드라인 (실전 예시)

1. 접근 방식 (Before Writing Code)

❌ 나쁜 예:

"사용자 인증 기능 구현해줘"

✅ 좋은 예:

사용자 인증 기능을 구현하고 싶습니다. 제 생각에는 다음과 같이 하면 될 것 같은데 확인 부탁드립니다:

1. JWT 토큰 방식 사용 (access token + refresh token)
2. 로그인 시 토큰 발급, 헤더에 실어 보내기
3. src/api/auth.ts에 인증 관련 함수 작성
4. src/middleware/auth.ts에 미들웨어 작성

이 접근방식이 괜찮을까요?

2. 작업 분할 (3 Files+ Rule)

❌ 나쁜 예:

"전자상거래 시스템 만들어줘" (수십 개 파일 필요)

✅ 좋은 예:

전자상거래 시스템은 크네요. 먼저 다음과 같이 나누어 진행하면 어떨까요?

Task 1: 상품 목록 조회 API (src/api/products.ts)
Task 2: 장바구니 기능 (src/api/cart.ts)
Task 3: 결제 기능 (src/api/payment.ts)

Task 1부터 시작할까요?

3. 테스트 중심 개발

❌ 나쁜 예:

코드만 작성하고 끝

✅ 좋은 예:

코드를 작성했습니다. 이 코드에서 발생할 수 있는 문제점:

1. 네트워크 실패: API 호출 실패 시 처리
2. 잘못된 입력: null, undefined, 빈 문자열
3. 경합 조건: 동시 요청 시 데이터 충돌

이를 covering하는 테스트 작성을 제안합니다:

• src/auth/__tests__/login.test.ts
• mocking 사용하여 네트워크 실패 시나리오 테스트

4. 버그 수정 TDD

❌ 나쁜 예:

버그 리포트를 보고 코드를 수정하기 시작

✅ 좋은 예:

버그 재현 테스트부터 작성하겠습니다:

// src/auth/__tests__/bug-reproduce.test.ts
test('로그인 후 바로 로그아웃하면 토큰이 남아있는 버그', async () => {
  const user = await login('test@example.com', 'password');
  await logout();
  const token = localStorage.getItem('token');
  expect(token).toBeNull(); // 이 테스트가 현재 실패함
});

이 테스트를 통과할 때까지 수정하겠습니다.

5. 지속적 개선 (CLAUDE.md 업데이트)

실제 예시:

# CLAUDE.md - 프로젝트 가이드

## 테스트 작성 규칙
- 모든 API 함수는 `__tests__` 디렉토리에 테스트 작성
- mocking은 msw 라이브러리 사용
- 네트워크 실패 케이스 항상 포함

## API 라우트 작성 패턴
```typescript
// 항상 이 패턴 따르기
export async function POST(req: Request) {
  try {
    // 1. 입력 검증
    // 2. 비즈니스 로직
    // 3. 응답 반환
  } catch (error) {
    // 4. 에러 처리
  }
}

 

참고 자료

공식 문서

• Best Practices for Claude Code
• Extend Claude with skills
• Automate workflows with hooks
• Connect Claude Code to tools via MCP

커뮤니티 리소스

• GitHub: Complete Claude Code CLI Guide
• Medium: Complete ClaudeCode Slash Command Reference
• DataCamp: Claude Code Hooks Tutorial
• Claude Fast: Sub-Agent Best Practices
• Ultimate Guide to Claude MCP Servers & Setup | 2026
• 50+ Best MCP Servers for Claude Code in 2026

50+ Best MCP Servers for Claude Code in 2026