오픈비 : 삽질은없다

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 무시)

포함 가이드라인:

좋은 예시:

# 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 필드

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 유형

4. SKILL vs Subagent 차이점

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

핵심 차이 비교

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

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 서버

6. Hooks 자동화

Hook이란?

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

주요 Hook 이벤트

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. 핵심 모범 사례

검증 가능한 작업 지시

구체적인 프롬프트

컨텍스트 관리

• 작업 간 /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