💻 Claude Code Tutorial-2

🤖 실전 튜터리얼 2편

PART 02 / 02

Skills &
병렬 에이전트 완전 정복

CLAUDE.md·Plan Mode·Hooks를 익혔다면 이제 다음 단계로 — 재사용 가능한 Skills와 동시 실행 에이전트로 개발 속도를 극대화합니다.

← 1편: CLAUDE.md · Plan Mode · Hooks · @ 파일 참조

2 핵심 기능

4x 병렬 실행

∞ 재사용 가능

1편 복습 — 오늘 이것들을 알고 있다고 가정합니다

📋CLAUDE.md

🔍Plan Mode

@파일 참조

🪝Hooks

목차

• 01 Skills란 무엇인가
• 02 SKILL.md 구조 이해
• 03 첫 Skill 직접 만들기
• 04 실수: Unknown skill 에러
• 05 병렬 에이전트란
• 06 병렬 실행 직접 해보기
• 07 Task vs Explore 에이전트
• 08 전체 로드맵 총정리

STEP 01

Skills란 무엇인가

Skills는 Claude에게 특정 작업 방법을 가르쳐두는 재사용 가능한 지식 패키지입니다. CLAUDE.md와 헷갈리기 쉬운데, 역할이 명확히 다릅니다.

구분	CLAUDE.md	Skills
역할	프로젝트 정체성·규칙	특정 작업의 실행 방법
로딩	항상 자동 로딩	필요할 때만 로딩
범위	전체 프로젝트	특정 작업 유형
스크립트	불가	Python·Shell 번들 가능
저장 위치	.claude/CLAUDE.md	.claude/skills/이름/SKILL.md

💡 언제 만드나? 같은 프롬프트를 여러 대화에서 반복해서 타이핑하고 있다면, Skill을 만들 때가 된 겁니다. "코드 리뷰해줘", "PR 요약해줘" 같은 반복 작업이 대표적입니다.

---

STEP 02

SKILL.md 구조 이해

모든 Skill은 폴더 안의 SKILL.md 파일로 정의됩니다. 파일명이 아닌 폴더명이 Skill 이름이 됩니다.

.claude/skills/ └── code-reviewer/ ← 폴더명 = Skill 이름 ├── SKILL.md ← 필수 ├── scripts/ ← 번들 스크립트 (선택) │ └── lint.sh └── resources/ ← 참고 자료 (선택) └── checklist.md

SKILL.md 기본 형식

.claude/skills/code-reviewer/SKILL.md

---

name: code-reviewer

description: Python 코드 품질 리뷰. 타입힌트·docstring·

예외처리를 검토할 때 사용.

---

↑ frontmatter: Claude가 언제 이 Skill을 쓸지 판단하는 기준

## 코드 리뷰 체크리스트

리뷰 시 반드시 아래 순서로 확인한다:

1. 타입 힌트 — 모든 함수에 있는지

2. Docstring — Args, Returns, Raises 포함 여부

3. 예외 처리 — ValueError/TypeError 적절히 발생하는지

...

↑ 본문: 실제 Claude에게 주입되는 지시사항

⚙️ 작동 원리: Claude Code는 SKILL.md의 frontmatter를 스캔해서 사용 가능한 Skill 목록을 만들고, 실제 호출 시 SKILL.md 본문을 대화 컨텍스트에 주입합니다. 메인 프롬프트를 항상 가볍게 유지하면서 필요할 때만 로딩하는 구조입니다.

---

STEP 03

첫 Skill 직접 만들기

계산기 프로젝트에 코드 리뷰어 Skill을 만들어봅니다. 순서가 중요합니다.

1단계 — 폴더 먼저 생성 (터미널에서)

Terminal — Claude Code 밖에서

mkdir -p .claude/skills/code-reviewer

2단계 — Claude Code 세션에서 SKILL.md 작성

Claude Code

.claude/skills/code-reviewer/SKILL.md 파일을 만들어줘:

---

name: code-reviewer

description: Python 코드 품질 리뷰. 타입힌트·docstring·

예외처리·Pythonic 코드를 검토할 때 사용.

---

## 코드 리뷰 체크리스트

1. 타입 힌트 [심각도: 상/중/하]

2. Docstring

3. 예외 처리

4. Pythonic 스타일

5. 로깅 (print 금지)

각 항목에 수정 코드 예시를 함께 제시한다.

3단계 — 세션 재시작 (필수!)

Terminal

Claude Code 종료 후 재시작 — Skills는 세션 시작 시 로딩됨

claude

4단계 — Skill 호출

Claude Code

code-reviewer skill을 사용해서 @calculator.py 를 리뷰해줘

Skill(code-reviewer) — Successfully loaded skill

1. 타입 힌트 [심각도: 하] — 모든 함수 양호

2. Docstring [심각도: 중] — absolute 스타일 불일치

3. 예외 처리 [심각도: 중] — float == 0 비교 관행

4. Pythonic [심각도: 하] — math.pow → ** 권장

5. 로깅 [심각도: 하] — 전부 logger.debug() 사용 양호

---

STEP 04

실수: Unknown skill 에러

처음 Skill을 만들 때 거의 모두가 이 에러를 만납니다. 원인과 해결법을 정확히 알아두세요.

에러 상황

Skill(code-reviewer)

Error: Unknown skill: code-reviewer

리뷰는 됐지만 Skill은 로딩 안 됨 → 그냥 Claude가 직접 한 것

❌ 흔한 실수 Claude Code 세션 안에서만 파일 생성 후 바로 호출 or 세션 재시작 없이 호출 → Unknown skill 에러 발생

✅ 올바른 순서 1. mkdir -p .claude/skills/이름 2. SKILL.md 파일 생성 3. Claude Code 종료 4. claude 재시작 5. Skill 호출 → Successfully loaded skill ✓

⚠️ 핵심: Skills는 세션 시작 시 로딩됩니다. 파일을 직접 추가했다면 반드시 세션을 재시작해야 합니다. 또는 /agents 명령어로 즉시 로딩할 수도 있습니다.

---

STEP 05

병렬 에이전트란 무엇인가

서브에이전트는 메인 세션이 특정 작업을 위해 생성하는 독립적인 Claude 인스턴스입니다. 각각 자신만의 200k 컨텍스트 창을 갖고 동시에 실행됩니다.

순차 실행 vs 병렬 실행 비교

순차 실행

Task A → Task B → Task C → Task D

병렬 실행

Task A

Task B

Task C

Task D

동시 실행 → 최대 4배 빠름 · 각 에이전트 독립 200k 컨텍스트

언제 병렬 에이전트를 쓰나?

상황	예시
대형 리팩토링	75개 파일의 함수명 변경 → 파일별 병렬 처리
멀티 서비스 분석	backend / frontend / infra 동시 분석
테스트 생성	각 모듈별 테스트 파일 병렬 작성
로그 분석	3개 마이크로서비스 로그 동시 분석 후 종합
코드 탐색	대형 코드베이스 디렉토리별 동시 탐색

---

STEP 06

병렬 실행 직접 해보기

Claude Code는 기본적으로 보수적으로 동작합니다. 병렬화를 최대화하려면 프롬프트에서 명시적으로 요청해야 합니다.

핵심 — 명시적으로 요청하기

❌ 병렬 안 됨 calculator.py 분석하고 테스트 커버리지도 확인하고 프로젝트 구조도 봐줘 → 순차적으로 하나씩 실행

✅ 병렬 실행 4개의 parallel 서브에이전트로 동시에 아래 작업을 해줘: 1. add/subtract 성능 분석 2. multiply/divide 성능 분석 3. 테스트 커버리지 분석 4. 프로젝트 구조 분석 → 4개 동시 실행

Claude Code — 실제 실행 결과

4 agents launched

├─ Task (add/subtract 성능 분석)

│ ⎿ Running in the background

├─ Task (multiply/divide 성능 분석)

│ ⎿ Running in the background

├─ Task (테스트 커버리지 분석)

│ ⎿ Running in the background

└─ Explore (프로젝트 구조 분석)

⎿ Running in the background

30초 후...

Agent "add/subtract 성능 분석" completed

→ 모든 에이전트 완료 후 메인 세션에서 결과 종합

💡 "4개의 parallel 에이전트", "동시에" 같은 구체적인 숫자와 명시적 표현이 핵심입니다. 모호하게 요청하면 Claude가 순차 실행을 선택합니다.

---

STEP 07

Task vs Explore 에이전트

병렬 실행 시 Claude가 자동으로 에이전트 유형을 선택합니다. 어떤 에이전트가 언제 선택되는지 알아두면 결과를 예측할 수 있습니다.

Task 에이전트 범용 파일 읽기·쓰기·수정 모두 가능. 성능 분석, 테스트 작성, 코드 수정 같은 실행이 필요한 작업에 자동 선택됩니다.

Explore 에이전트 읽기 전용 파일 읽기만 가능. 코드베이스 탐색, 구조 분석, 개선점 제안 같은 탐색·분석 작업에 자동 선택됩니다.

실제 실행에서 관찰된 패턴

├─ Task (add/subtract 성능 분석) ← 분석 + 결과 작성

├─ Task (multiply/divide 성능 분석) ← 분석 + 결과 작성

├─ Task (테스트 커버리지 분석) ← 파일 읽기 + 계산

└─ Explore (프로젝트 구조 분석) ← 읽기 전용 탐색

Claude가 작업 특성을 보고 자동으로 에이전트 유형 결정

🔍 빌트인 에이전트 외에 .claude/agents/ 폴더에 커스텀 에이전트를 만들 수 있습니다. 예: code-reviewer 에이전트, security-auditor 에이전트 등을 전용 도구 권한과 함께 정의할 수 있습니다.

---

SUMMARY

1·2편 전체 로드맵 총정리

두 편에 걸쳐 배운 Claude Code의 핵심 기능 전체를 한눈에 정리합니다.

Claude Code 마스터 로드맵

# 1편 — 기초 정복 CLAUDE.md — 규칙을 한 번 쓰면 영원히 자동 적용 Plan Mode (Shift+Tab) — 실행 전 계획 검토 /clear — 새 작업마다 컨텍스트 초기화 @ 파일 참조 — 정확한 컨텍스트 타겟팅 프롬프트 패턴 — 역할+제약+검증 세트, TDD Hooks — .claude/settings.json, Write|Edit|MultiEdit
# 2편 — 고급 기능 Skills — .claude/skills/이름/SKILL.md 재사용 지식 패키지 병렬 에이전트 — "N개의 parallel 에이전트로" 명시적 요청
# 다음 단계 MCP 서버 연동 — GitHub·DB 직접 연결 커스텀 서브에이전트 — .claude/agents/ 전문가 팀 구성 CI/CD 파이프라인 통합

🧠 Skills = 재사용 지식 반복하는 작업을 SKILL.md로 정의. 폴더명이 이름. 세션 재시작 필수.

⚡ 병렬 = 명시적 요청 "N개의 parallel 에이전트로 동시에" — 구체적 숫자와 명시적 표현 필수.

🤖 Task vs Explore 실행 작업 → Task 자동 선택. 탐색 분석 → Explore 자동 선택.

📁 저장 위치 원칙 Skills·Hooks·Agents 모두 프로젝트 레벨 .claude/에 저장. 전역 ~/.claude/는 최소화.

Claude Code 실전 튜터리얼 2편 · macOS + Claude Pro 환경 기준
공식 문서: docs.anthropic.com/en/docs/claude-code