Claude Code 완전 정복 가이드 Part 3: Skills 시스템 - 온디맨드 전문가 활용하기

---
name: skill-name
description: 이 스킬이 무엇을 하는지, 언제 사용하는지 설명
---

# Skill 제목

여기에 Claude가 따라야 할 상세 지침을 작성합니다.

## 섹션 1
...

## 섹션 2
...

---
name: explain-code
description: 코드를 시각적 다이어그램과 비유로 설명합니다.
             코드 동작 방식을 설명하거나, 코드베이스를 가르치거나,
             "이게 어떻게 동작해?" 질문에 사용합니다.
---

# 코드 설명 Skill

코드를 설명할 때 항상 다음 구조를 따르세요:

## 1. 비유로 시작
코드를 일상생활의 무언가에 비유하여 시작합니다.

## 2. 다이어그램 그리기
ASCII 아트로 흐름, 구조, 관계를 시각화합니다.

## 3. 단계별 설명
코드가 어떻게 동작하는지 단계별로 설명합니다.

## 4. 주의점 하이라이트
흔한 실수나 오해를 짚어줍니다.

## 예시

사용자: "이 함수 어떻게 동작해?"

응답:
"이 함수는 식당의 주문 시스템과 비슷합니다.

---
name: java-test-writer
description: Java 테스트 코드를 작성합니다.
             JUnit 5, MockK, Given-When-Then 패턴을 사용합니다.
             "테스트 작성해줘", "테스트 코드", "단위 테스트" 요청 시 사용.
---

# Java Test Writing Skill

## 테스트 클래스 구조

@ExtendWith(MockKExtension.class)
class {TargetClass}Test {

    @MockK
    private lateinit var dependency: DependencyType

    @InjectMockKs
    private lateinit var sut: TargetClass  // System Under Test

    @BeforeEach
    fun setUp() {
        // 공통 설정
    }

    @Test
    fun `should 결과 when 조건`() {
        // Given
        val input = ...

        // When
        val result = sut.methodUnderTest(input)

        // Then
        assertThat(result).isEqualTo(expected)
    }
}

## 네이밍 규칙

- 클래스: `{대상클래스}Test`
- 메서드: `should_{기대결과}_when_{조건}` (백틱 사용)
- 변수: `sut` (System Under Test)

## Given-When-Then 패턴

@Test
fun `should return user when valid id provided`() {
    // Given - 테스트 데이터 및 Mock 설정
    val userId = 1L
    val expectedUser = User(id = userId, name = "John")
    every { userRepository.findById(userId) } returns expectedUser

    // When - 테스트 대상 메서드 실행
    val result = userService.getUser(userId)

    // Then - 결과 검증
    assertThat(result).isEqualTo(expectedUser)
    verify(exactly = 1) { userRepository.findById(userId) }
}

## Mock 사용 규칙

- MockK 사용 (Mockito 금지)
- `every { }` / `verify { }` 구문
- `answers { }` for complex stubbing

## 금지 사항

- `@Autowired` in tests (use `@InjectMockKs`)
- Real database connections
- Thread.sleep() for async tests

---
name: go-error-handling
description: Go 에러 처리 패턴을 적용합니다.
             에러 래핑, 커스텀 에러, 센티넬 에러 작업 시 사용.
             "에러 처리", "error handling", "에러 래핑" 요청 시 활성화.
---

# Go Error Handling Patterns

## 기본 원칙

1. 에러는 즉시 처리하거나 래핑하여 반환
2. 에러 메시지에 컨텍스트 추가
3. 절대로 에러를 무시하지 않음

## 에러 래핑 패턴

// ✅ 좋은 예: 컨텍스트 추가
if err != nil {
    return fmt.Errorf("failed to create user %s: %w", username, err)
}

// ❌ 나쁜 예: 컨텍스트 없음
if err != nil {
    return err
}

// ❌ 최악: 에러 무시
result, _ := someFunction()

## 커스텀 에러 타입

// 도메인 에러 정의
type UserNotFoundError struct {
    UserID int64
}

func (e *UserNotFoundError) Error() string {
    return fmt.Sprintf("user not found: %d", e.UserID)
}

// 사용
func GetUser(id int64) (*User, error) {
    user, err := repo.Find(id)
    if err != nil {
        if errors.Is(err, sql.ErrNoRows) {
            return nil, &UserNotFoundError{UserID: id}
        }
        return nil, fmt.Errorf("failed to get user: %w", err)
    }
    return user, nil
}

## 센티넬 에러

// 패키지 레벨에 정의
var (
    ErrNotFound     = errors.New("not found")
    ErrUnauthorized = errors.New("unauthorized")
    ErrInvalidInput = errors.New("invalid input")
)

// 사용
if errors.Is(err, ErrNotFound) {
    // 404 처리
}

## 에러 체크 패턴

// errors.Is - 에러 체인에서 특정 에러 찾기
if errors.Is(err, sql.ErrNoRows) { ... }

// errors.As - 특정 타입으로 캐스팅
var notFoundErr *UserNotFoundError
if errors.As(err, &notFoundErr) {
    log.Printf("User %d not found", notFoundErr.UserID)
}

## 금지 패턴

// ❌ panic 남용
panic("something went wrong")  // 복구 불가능한 경우만 사용

// ❌ 에러 문자열 비교
if err.Error() == "not found" { ... }  // errors.Is 사용

// ❌ 에러 로그 후 반환
log.Println(err)
return err  // 중복 로깅 발생, 한 곳에서만 로그

---
name: redis-cache-patterns
description: Redis 캐시 구현 패턴을 제공합니다.
             캐시 키 설계, TTL 전략, Cache-Aside 패턴 작업 시 사용.
             "Redis", "캐시", "caching" 관련 요청 시 활성화.
---

# Redis Cache Patterns

## 캐시 키 네이밍 규칙

{service}:{entity}:{identifier}:{optional-suffix}

예시:
- user-service:user:12345
- payment:transaction:uuid-here:status
- inventory:product:SKU123:stock

## 키 프리픽스 상수화

public class CacheKeys {
    public static final String USER_PREFIX = "user-service:user:";
    public static final String SESSION_PREFIX = "user-service:session:";

    public static String userKey(Long userId) {
        return USER_PREFIX + userId;
    }
}

## Cache-Aside 패턴

public User getUser(Long userId) {
    String key = CacheKeys.userKey(userId);

    // 1. 캐시 조회
    User cached = redisTemplate.opsForValue().get(key);
    if (cached != null) {
        return cached;
    }

    // 2. DB 조회
    User user = userRepository.findById(userId)
        .orElseThrow(() -> new UserNotFoundException(userId));

    // 3. 캐시 저장
    redisTemplate.opsForValue().set(key, user, Duration.ofHours(1));

    return user;
}

## TTL 전략

| 데이터 유형 | TTL | 이유 |
|------------|-----|------|
| 세션 | 30분 | 보안 |
| 사용자 프로필 | 1시간 | 자주 변경되지 않음 |
| 상품 정보 | 5분 | 재고 등 변경 가능 |
| 설정값 | 24시간 | 거의 변경 없음 |

## 캐시 무효화

// 단일 키 삭제
public void evictUser(Long userId) {
    redisTemplate.delete(CacheKeys.userKey(userId));
}

// 패턴으로 삭제 (주의: 프로덕션에서 KEYS 명령 지양)
public void evictUserCache() {
    Set<String> keys = redisTemplate.keys("user-service:user:*");
    if (keys != null && !keys.isEmpty()) {
        redisTemplate.delete(keys);
    }
}

// 권장: SCAN 사용
public void evictByPattern(String pattern) {
    ScanOptions options = ScanOptions.scanOptions()
        .match(pattern)
        .count(100)
        .build();

    try (Cursor<String> cursor = redisTemplate.scan(options)) {
        while (cursor.hasNext()) {
            redisTemplate.delete(cursor.next());
        }
    }
}

## 주의사항

- 프로덕션에서 `KEYS *` 명령 금지 (블로킹)
- 대량 삭제 시 `SCAN` + 배치 삭제 사용
- 캐시 워밍업 전략 고려

---
name: api-conventions
description: REST API 설계 컨벤션을 제공합니다.
             API 엔드포인트 설계, 응답 형식, 에러 처리 시 사용.
             "API 만들어줘", "엔드포인트", "REST" 요청 시 활성화.
---

# REST API Design Conventions

## URL 설계 원칙

GET    /api/v1/users          # 목록 조회
GET    /api/v1/users/{id}     # 단일 조회
POST   /api/v1/users          # 생성
PUT    /api/v1/users/{id}     # 전체 수정
PATCH  /api/v1/users/{id}     # 부분 수정
DELETE /api/v1/users/{id}     # 삭제

# 하위 리소스
GET    /api/v1/users/{id}/orders
POST   /api/v1/users/{id}/orders

# 액션 (동사가 필요한 경우)
POST   /api/v1/users/{id}/activate
POST   /api/v1/orders/{id}/cancel

## 응답 형식

### 성공 응답

{
  "success": true,
  "data": {
    "id": 1,
    "name": "John Doe",
    "email": "john@example.com"
  },
  "meta": {
    "requestId": "req-uuid",
    "timestamp": "2025-01-23T10:00:00Z"
  }
}

### 목록 응답 (페이징)

{
  "success": true,
  "data": [...],
  "pagination": {
    "page": 1,
    "size": 20,
    "totalElements": 100,
    "totalPages": 5
  }
}

### 에러 응답 (RFC 7807 Problem Details)

{
  "success": false,
  "error": {
    "type": "https://api.example.com/errors/validation",
    "title": "Validation Error",
    "status": 400,
    "detail": "The request body contains invalid fields",
    "instance": "/api/v1/users",
    "errors": [
      {
        "field": "email",
        "message": "must be a valid email address"
      }
    ]
  }
}

## HTTP 상태 코드

| 코드 | 의미 | 사용 시점 |
|------|------|----------|
| 200 | OK | GET 성공, PUT/PATCH 성공 |
| 201 | Created | POST 생성 성공 |
| 204 | No Content | DELETE 성공 |
| 400 | Bad Request | 요청 형식 오류, 유효성 검증 실패 |
| 401 | Unauthorized | 인증 필요 |
| 403 | Forbidden | 권한 없음 |
| 404 | Not Found | 리소스 없음 |
| 409 | Conflict | 중복, 상태 충돌 |
| 422 | Unprocessable Entity | 비즈니스 규칙 위반 |
| 500 | Internal Server Error | 서버 오류 |

## 쿼리 파라미터

# 페이징
GET /api/v1/users?page=1&size=20

# 정렬
GET /api/v1/users?sort=createdAt,desc

# 필터링
GET /api/v1/users?status=active&role=admin

# 검색
GET /api/v1/users?q=john

## 버전 관리

- URL 경로: `/api/v1/`, `/api/v2/`
- 주요 변경 시에만 버전 증가
- 이전 버전 최소 6개월 지원

---
name: codebase-visualizer
description: 코드베이스의 인터랙티브 트리 시각화를 생성합니다.
             "코드 구조 보여줘", "프로젝트 구조 시각화" 요청 시 사용.
---

# Codebase Visualizer

코드베이스 구조를 시각화하려면 번들된 스크립트를 실행하세요:

python ~/.claude/skills/codebase-visualizer/scripts/generate-tree.py

생성된 HTML 파일을 브라우저에서 열어 인터랙티브하게 탐색할 수 있습니다.

---
name: api-scaffold
description: 새 API 엔드포인트를 위한 Controller, Service, DTO를 생성합니다.
             "새 API 만들어줘", "CRUD 생성" 요청 시 사용.
---

# API Scaffolding

템플릿 파일들을 참조하여 일관된 구조로 생성하세요:

- Controller: `resources/controller-template.java`
- Service: `resources/service-template.java`
- DTO: `resources/dto-template.java`

## 생성 순서

1. DTO 먼저 생성 (Request, Response)
2. Service 인터페이스 및 구현체
3. Controller
4. 테스트 코드

---
name: dangerous-operation
description: 위험한 작업을 수행합니다.
disable-model-invocation: true  # 자동 호출 비활성화
---

# 이 Skill은 /dangerous-operation으로만 호출 가능

---
name: safe-analyzer
description: 코드를 분석합니다 (수정 없음).
allowed-tools: Read, Grep, Glob
---

# Code Analyzer

이 Skill은 코드를 읽고 분석만 합니다. 수정 권한이 없습니다.

# CLAUDE.md (200줄)

## 프로젝트 정보
...

## 빌드/테스트
...

## Go 에러 처리 규칙 (50줄)
- 에러는 즉시 처리
- fmt.Errorf로 래핑
- ... (상세 규칙들)

## API 설계 규칙 (60줄)
- REST 원칙
- 응답 형식
- ... (상세 규칙들)

## 테스트 작성 규칙 (40줄)
- Given-When-Then
- ... (상세 규칙들)

# User Service

Go 1.22 기반 사용자 관리 서비스

## 빌드 및 테스트

- 빌드: `go build ./cmd/server`
- 테스트: `go test ./...`
- 린트: `golangci-lint run`

## 프로젝트 구조

cmd/server/    # 진입점
internal/      # 내부 패키지
pkg/           # 공개 패키지
api/           # OpenAPI specs

## 핵심 규칙

IMPORTANT: 에러 처리, API 설계, 테스트 작성 시
해당 Skills가 자동으로 활성화됩니다.

---
name: go-error-handling
description: Go 에러 처리 패턴. 에러 래핑, 커스텀 에러 작업 시 사용.
---

(Part 4.2의 내용)

---
name: api-conventions
description: REST API 설계 규칙. 엔드포인트, 응답 형식 설계 시 사용.
---

(Part 4.4의 내용)

---
name: go-test-writer
description: Go 테스트 작성. 테이블 기반 테스트, Mock 사용 시.
---

(테스트 관련 상세 규칙)