Claude Code 컴포넌트 완벽 가이드: 실전 워크플로우

 

Understanding Claude Code Components: A Practical Guide

위 내용을 한국어로 정리했습니다. 

들어가며

대부분의 개발자는 Claude Code를 단순한 채팅 인터페이스처럼 사용합니다. 질문하고, 답변 받고, 코드를 복사-붙여넣기 하죠. 하지만 이는 Claude Code가 제공하는 자동화 기능의 20%만 활용하는 것입니다.

많은 엔지니어들이 혼란스러워하는 질문들:

• Commands와 Agents는 언제 사용하나요?
• Tools와 Skills의 차이는 무엇인가요?
• Plugins은 왜 필요한가요?

이 글에서는 실제 팀에서 사용하는 워크플로우를 통해 Claude Code의 각 컴포넌트를 언제, 어떻게 사용하는지 명확하게 설명하겠습니다.

Claude Code 컴포넌트 개요

Claude Code는 7가지 핵심 컴포넌트로 구성되어 있습니다:

1. Commands - 사용자가 입력하는 진입점 (/define-task, /plan-task)
2. Agents - 복잡한 추론 작업 수행 (code-planning, code-review)
3. Tools - 직접적인 작업 실행 (파일 편집, bash 실행)
4. Skills - 재사용 가능한 기능 (go-testing, api-design)
5. MCPs - 외부 서비스 연결 (Jira, Brave Search, Context7)
6. Plugins - 특정 워크플로우용 번들 패키지
7. Hooks - 이벤트 기반 자동화 (저장 시 포맷팅, 커밋 시 테스트)

실전 예제: API 엔드포인트에 페이지네이션 추가하기

실제 Golang HTTP 서비스에 페이지네이션을 추가하는 과정을 통해 각 컴포넌트의 역할을 살펴보겠습니다.

1단계: 계획 수립 (Planning Phase)

작업 정의하기

/define-task PROJ-123

무슨 일이 일어나는가?

• Command가 Jira MCP를 통해 티켓 정보를 가져옴
• 자동으로 명확한 질문을 던져 완료 조건(Definition of Done) 작성
• 브라우저 전환 없이 Jira 티켓이 업데이트됨

예제 결과:

작업: /api/users 엔드포인트에 페이지네이션 추가

완료 조건:
✓ page와 limit 파라미터를 받는 핸들러 수정
✓ OFFSET/LIMIT을 사용한 데이터베이스 쿼리 업데이트
✓ 응답에 메타데이터 추가 (총 개수, 현재 페이지)
✓ 유닛 테스트 및 통합 테스트 작성

작업 계획하기

/plan-task PROJ-123
# 또는 프롬프트로
plan task PROJ-123

Agent의 역할:

• code-planning agent가 Linus Method를 적용하여 구현을 단계별로 분해
• 각 단계마다 시작점, 실행 세부사항, 완료 기준 명시
• 필요한 컨텍스트 자동 수집:
  • Context7 MCP: 최신 Go 라이브러리 문서
  • Brave Search MCP: Stack Overflow 관련 토론
  • Zen MCP: 각 추론 작업에 적합한 모델 선택

생성된 계획 예시:

1. 핸들러 시그니처 수정
   - 시작: handlers/users.go 파일 열기
   - 실행: GetUsers 함수에 page, limit 파라미터 추가
   - 완료: 파라미터가 정수로 파싱되고 유효성 검사됨

2. 데이터베이스 쿼리 업데이트
   - 시작: repository/users.go 파일 열기
   - 실행: SELECT 쿼리에 OFFSET/LIMIT 절 추가
   - 완료: 쿼리가 페이지네이션 파라미터를 올바르게 적용

3. 응답 메타데이터 추가
   - 시작: models/response.go 확인
   - 실행: PaginatedResponse 구조체 생성
   - 완료: 총 개수와 페이지 정보가 응답에 포함

4. 테스트 작성
   - 시작: 기존 테스트 패턴 분석
   - 실행: 유닛 및 통합 테스트 작성
   - 완료: go test ./... 통과

계획이 완료되면 Agent가 자동으로 Jira 티켓을 업데이트합니다. 수동 복사-붙여넣기 불필요!

2단계: 실행 (Execution Phase)

implement task PROJ-123

Coding Agent의 작업 흐름:

1. 컨텍스트 스캔
   • 기존 라우트 핸들러 패턴 분석
   • 미들웨어 구조 파악
2. 코드 작성 (Tools 자동 호출)
3. // Agent가 자동으로 작성한 코드 예시 func (h *UserHandler) GetUsers(w http.ResponseWriter, r *http.Request) { page, _ := strconv.Atoi(r.URL.Query().Get("page")) limit, _ := strconv.Atoi(r.URL.Query().Get("limit")) if page < 1 { page = 1 } if limit < 1 || limit > 100 { limit = 20 } offset := (page - 1) * limit users, total, err := h.repo.GetUsersPaginated(offset, limit) // ... 에러 처리 및 응답 생성 }
4. 자동 테스트 실행
   • go test ./... 자동 실행
   • 실패 시 Agent가 수정하고 재시도
5. 진행 상황 업데이트
   • Jira 티켓에 실행 상태 실시간 반영

Tools의 역할:

• Read Tool: 파일 내용 읽기
• Edit Tool: 코드 수정
• Write Tool: 새 파일 생성
• Bash Tool: 테스트 및 빌드 명령 실행

프론트엔드 코드를 다루는 경우, Chrome DevTools MCP가 UI 변경사항을 자동으로 검증합니다. 수동 브라우저 새로고침 사이클이 필요 없습니다.

3단계: 검증 (Validation Phase)

validate task PROJ-123

Validation Agent의 검증 항목:

1. 코드 리뷰 자동화
2. ✓ 아키텍처 일관성 검사 ✓ 기존 코딩 패턴 준수 여부 ✓ 에러 처리 적절성
3. 다운스트림 영향도 분석
4. ✓ 모바일 앱 API 호환성 ✓ 웹 프론트엔드 영향도 ✓ 써드파티 통합 확인
5. 보안 리뷰
6. ✓ SQL 인젝션 취약점 검사 ✓ 입력값 검증 확인 ✓ 인증/인가 요구사항 충족

예제 검증 결과:

검증 결과 - PROJ-123

✅ 코드 품질: PASSED
- 기존 핸들러 패턴과 일관성 유지
- 적절한 에러 처리 구현

⚠️ 성능 고려사항:
- 대용량 데이터셋에서 COUNT(*) 쿼리 성능 이슈 가능
- 제안: 캐싱 레이어 추가 검토

✅ 보안: PASSED
- 입력값 검증 적절히 구현
- SQL 인젝션 방어됨

✅ 하위 호환성: PASSED
- 기존 API 동작 유지
- 모바일 앱 영향 없음

4단계: PR 생성

/create-pr

자동 생성되는 내용:

• 완료 조건(DoD) 체크리스트
• 테스트 결과 요약
• 변경사항 상세 설명
• 관련 Jira 티켓 링크

흔한 실수와 해결방법

실수 1: 시작 시 모든 MCP 로딩

문제점:

# ❌ 나쁜 예
claude-code --load-all-mcps

• 컨텍스트 윈도우 낭비
• 시작 속도 저하
• 불필요한 API 호출

해결책: Plugins 사용

# ✅ 좋은 예
# API 작업용 플러그인
{
  "name": "api-development",
  "mcps": ["jira", "context7", "brave-search"],
  "agents": ["code-planning", "code-review"],
  "skills": ["go-testing", "api-design"]
}

# UI 작업용 플러그인
{
  "name": "ui-development",
  "mcps": ["chrome-devtools", "figma"],
  "agents": ["ui-review"],
  "skills": ["react-testing", "accessibility-check"]
}

실수 2: 슬래시 커맨드만 사용

문제점:

• Agent의 복잡한 추론 능력 미활용
• 반복 작업 수동으로 수행
• 자동화 기회 놓침

해결책:

# ❌ 수동 방식
/edit file.go
/test
/commit

# ✅ Agent 활용
implement task PROJ-123
# Agent가 편집, 테스트, 커밋을 자동으로 수행

실수 3: Skills 무시

문제점:

• 재사용 가능한 로직 중복 작성
• 일관성 없는 테스트 패턴
• Agent 효율성 저하

해결책: Skills 활용

# go-test.skill.yaml
name: go-testing
description: Go 프로젝트 테스트 자동화
triggers:
  - "테스트 작성"
  - "테스트 실행"
steps:
  - analyze_existing_tests
  - generate_table_driven_tests
  - run_tests_with_coverage
  - report_results

사용 예시:

// Agent가 go-testing skill을 자동으로 호출하여 생성
func TestGetUsersPaginated(t *testing.T) {
    tests := []struct {
        name     string
        page     int
        limit    int
        expected int
        wantErr  bool
    }{
        {"첫 페이지", 1, 10, 10, false},
        {"음수 페이지", -1, 10, 10, false},
        {"제한 초과", 1, 200, 100, false},
    }
    
    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            // ... 테스트 로직
        })
    }
}

실수 4: 수동 실행에만 의존

문제점:

• 반복적인 작업 소요 시간
• 일관성 없는 코드 포맷
• 커밋 전 테스트 누락

해결책: Hooks 설정

# .claude-code/hooks.yaml
hooks:
  pre-commit:
    - name: format-code
      command: gofmt -w .
    - name: run-linter
      command: golangci-lint run
    - name: run-tests
      command: go test -short ./...
  
  post-commit:
    - name: update-docs
      command: godoc -http=:6060
  
  pre-push:
    - name: full-test-suite
      command: go test -race -coverprofile=coverage.out ./...
    - name: security-scan
      command: gosec ./...

컴포넌트 선택 가이드

상황 사용할 컴포넌트 예시

워크플로우 시작	Commands	/define-task, /plan-task
복잡한 추론 필요	Agents	아키텍처 설계, 코드 리뷰
직접 작업 실행	Tools	파일 편집, bash 명령
재사용 로직	Skills	테스트 생성, API 설계
외부 서비스 연동	MCPs	Jira, GitHub, Slack
워크플로우 그룹화	Plugins	API 개발, UI 작업
자동화 트리거	Hooks	커밋 시, 푸시 시

실전 적용 가이드

이번 주 목표: 한 가지 컴포넌트 추가하기

현재 사용하지 않는 컴포넌트 한 가지를 선택하세요:

Commands만 사용 중이라면

# Agent 추가
다음 기능 개발 시:
1. /plan-task 대신 → 자연어로 "plan this feature"
2. code-planning agent가 자동으로 작업 분해
3. 더 상세하고 실행 가능한 계획 획득

Plugins 건너뛰고 있다면

# api-backend.plugin.yaml 생성
name: api-backend
description: 백엔드 API 개발 워크플로우
components:
  mcps:
    - jira
    - context7
    - brave-search
  agents:
    - code-planning
    - code-review
    - validation
  skills:
    - go-testing
    - api-design
    - database-migration

Hooks 무시하고 있다면

# 가장 간단한 Hook부터 시작
hooks:
  pre-commit:
    - name: format
      command: gofmt -w .

효과:

• 포맷팅 일관성 100% 보장
• 수동 작업 시간 절약
• 코드 리뷰 피드백 감소

성공 지표

도입 전

• 작업 정의: 20분 (Jira 왔다갔다)
• 계획 수립: 30분 (문서 작성)
• 구현: 2시간
• 테스트: 30분
• 검증: 40분
• PR 작성: 15분
• 총 4시간 15분

도입 후

• 작업 정의: 5분 (/define-task)
• 계획 수립: 10분 (agent 자동)
• 구현: 1시간 30분 (자동 테스트 포함)
• 검증: 10분 (agent 자동)
• PR 작성: 5분 (/create-pr)
• 총 2시간

생산성 향상: 53%

마치며

Claude Code와 Claude Code 마스터의 차이는 어떤 컴포넌트가 어떤 문제를 해결하는지 아는 것입니다.

당신의 현재 자동화 격차는 무엇인가요?

• 계획 수립 단계?
• 실행 속도?
• 검증 철저함?

하나를 선택해서 이번 주부터 자동화를 시작하세요.

---

추가 리소스

• Commands 문서
• Agents 문서
• Tools 문서
• Skills 문서
• MCPs 문서
• Plugins 문서
• Hooks 문서