wesammustafa/Claude-Code-Everything-You-Need-to-Know

Claude Code에 대한 실용적인 가이드 — 첫 번째 프롬프트부터 멀티 에이전트 자동화 (multi-agent automation), 훅 (hooks), MCP, 그리고 팀 워크플로 (team workflows)까지. 마케팅 용어가 아닌 명확한 멘탈 모델 (mental models)과 실제 사례를 중심으로 구축되었습니다.

npm install -g @anthropic-ai/claude-code

대상 독자: Claude Code를 사용 중이거나 사용할 예정인 개발자. 초보자는 안내된 경로를 따라갈 수 있으며, 숙련된 사용자는 기술 (Skills), 훅 (Hooks), MCP, 그리고 에이전트 팀 (Agent Teams)에 대한 심도 있는 내용을 얻을 수 있습니다.

| 당신은… |
|---|---|---|
| 🚀 Claude Code 초보자 |
| 설정 (Setup) → 프롬프트 엔지니어링 (Prompt Engineering) → 첫 번째 기술 (First Skill) | ~15분 |
| ⚡ 이미 사용 중이며 심화 학습을 원하는 경우 |
| 기술 (Skills) · 훅 (Hooks) · MCP | 각 ~30분 |
| 🧠 팀 또는 자동화를 구축하는 경우 |
| 에이전트 팀 (Agent Teams) · Super Claude · BMAD | 가변적 |

Claude Code의 네 가지 확장 지점 (extension points) 비교:

| 도구 |
|---|---|---|---|
| 기술 (Skills, 슬래시 명령어) |
| 동일한 프롬프트나 워크플로를 3회 이상 반복할 때 | 일회성 작업일 때 | .claude/commands/*.md |
| 훅 (Hooks) |
| 도구 사용, 세션 시작 시 코드가 자동으로 실행되기를 원할 때 | 수동 트리거만 원하는 경우 | .claude/settings.json |
| 서브에이전트 (Subagents) |
| 하위 작업이 별도의 격리된 컨텍스트 (isolated context)가 필요할 만큼 클 때 | 작업이 메인 세션 내에서 처리 가능할 때 | .claude/agents/*.md |
| MCP 서버 |
| Claude가 외부 도구 (브라우저, DB, API)를 사용해야 할 때 | 모든 데이터가 로컬 파일에 있을 때 | 프로젝트별로 구성 |

💡 이 네 가지는 서로 보완적입니다. 가장 정교한 워크플로는 보통 2~3개를 결합하여 사용합니다.

기초 (Fundamentals) — Claude Code란 무엇인가? · 설정 (Setup) · 프롬프트 엔지니어링 (Prompt Engineering)

워크플로 확장 (Workflow extensions) — 슬래시 명령어 (Slash Commands) · 기술 (Skills) · 훅 (Hooks)

멀티 에이전트 및 통합 (Multi-agent & integration) — 서브에이전트 (Subagents) · 에이전트 팀 (Agent Teams) · MCP

생산성 및 프레임워크 (Productivity & frameworks) — 노력 수준 (Effort levels) · 패스트 모드 (Fast Mode) · Super Claude · BMAD 방식

참조 (Reference) — 슬래시 명령어 치트 시트 (Slash Command Cheatsheet) · 노력 수준 (Effort Levels) · FAQ · 업데이트 및 지원 중단 (Updates & Deprecations) · 추가 읽을거리

Claude Code는 터미널에서 Claude와 작업할 수 있도록 Anthropic에서 제공하는 공식 CLI (Command Line Interface)입니다. 프로젝트를 지정하면 Claude가 코드를 읽고, 계획을 세우고, 파일을 편집하고, 명령어를 실행하며, 커밋 (commit)까지 — 이 모든 과정을 프롬프트 라인에서 수행합니다.

채팅 UI가 할 수 없는 세 가지 기능:

실제 저장소 (repo) 읽기— 복사해서 붙여넣은 코드 조각이 아닙니다. Claude는 파일 트리 (file tree)를 확인하고, grep을 실행하며, 임포트 (import)를 따라가고, 실제 문맥 (context)에 기반하여 답변을 제공합니다.

제자리 편집 및 테스트 실행— 차이점 (diff)을 인식하여 편집한 후, 변경 사항을 검증하기 위해 즉석에서 pytest / vitest / go test를 실행합니다.

기존 스택과의 결합— 슬래시 명령어 (slash commands), 훅 (hooks), 서브 에이전트 (sub-agents), MCP 서버, 그리고 일반적인 git/shell 워크플로우와 함께 작동합니다.

Copilot이나 Cursor를 사용해 보셨다면, Claude Code를 그들의 "터미널 내 에이전트 (agent in your terminal)" 동료라고 생각하세요. 개념은 같지만 인터페이스가 다를 뿐이며, 특정 에디터에 종속되지 않습니다.

claude # 현재 저장소에서 세션 시작
> explain what this codebase does
> fix the failing test in src/api.test.ts
...

Claude Opus 4.7은 Claude 4 제품군 (2026년 5월 기준)의 현재 플래그십 모델입니다. 동일한 가격에 Opus 4.6보다 더 날카로운 적응형 사고 (adaptive thinking), 더 나은 긴 문맥 기반 (long-context grounding), 그리고 더 신뢰할 수 있는 도구 호출 (tool calling) 기능을 제공합니다. 200K 컨텍스트 (API를 통한 1M 베타), 128K 최대 출력량을 지원합니다.

모델 선택 — 빠른 가이드:

모델	이럴 때 사용하세요…
Opus 4.7	복잡한 추론, 대규모 리팩토링 (refactor), 다중 파일 분석, 프로덕션 크리티컬 코드
Sonnet 4.6	균형 잡힌 일상 업무 — 대부분의 코딩 작업이 여기에 해당합니다
Haiku 4.5	빠르고 가벼운 작업 — 간단한 질문, 문서 업데이트
Opus 4.6 (legacy)	특정 빌드를 고정할 때; 또한 Fast Mode (/fast)의 기반 모델

⏱️

5분 설정. 아무것도 없는 상태에서 첫 번째 AI 지원 커밋 (commit)까지 도달하세요.

npm install -g @anthropic-ai/claude-code

Node.js 18 이상이 필요합니다. 다른 설치 방법 (Homebrew, curl, 네이티브 바이너리)은 공식 설치 가이드를 참조하세요.

claude

처음 실행할 때, Claude Code는 Anthropic 계정(Pro, Max 또는 API 키 모두 가능)으로 로그인하기 위해 브라우저를 엽니다. 그 후에는 Claude 내부에서 /auth login을 통해 언제든지 다시 인증할 수 있습니다.

어떤 프로젝트 디렉토리에서든:

cd ~/your-project
claude

Claude Code가 실행되면, 다음 중 하나를 시도해 보세요:

explain what this codebase does

— Claude가 저장소 (repo)를 읽고 요약합니다. add a README section about installation

— 프로젝트를 기반으로 콘텐츠를 생성합니다. find and fix the failing test in src/api.test.ts

— 진단 및 즉시 수정합니다.

/init

Claude가 매 세션마다 읽는 프로젝트 수준의 지침 파일(instruction file), 즉 프로젝트의 "가이드라인 (house rules)"을 생성합니다. 이에 대한 자세한 내용은 Prompt Engineering Deep Dive에서 다룹니다.

이 저장소 자체의 .claude/ 디렉토리는 완전히 구성된 Claude Code 프로젝트의 작동 예시입니다. 잘 다듬어진 설정이 어떤 모습인지 참고용으로 살펴보세요:

경로	역할
.claude/settings.json	프로젝트 수준의 Claude Code 설정 — 권한 (permissions), 훅 (hooks), MCP 통합
.claude/agents/	5개의 특화된 서브 에이전트 (subagents) (프론트엔드, 테크 리드, PM, UX 디자이너, 코드 리뷰어)
.claude/commands/	8개의 커스텀 스킬 (custom skills) — /pr, /review, /tdd, /test, /five, /ux, /todo, /mermaid. 전체 가이드는 Skills를 참조하세요.
.claude/hooks/	Python 훅 스크립트 (pre_tool_use.py, post_tool_use.py, notification.py, stop.py, subagent_stop.py) — Hooks를 참조하세요

💡

다음 단계: 기초가 익숙해지면, Claude Skills로 넘어가 3분 만에 재사용 가능한 슬래시 명령어 (slash commands)를 만들어 보세요.

📖 Claude 초기화 (Initialization)
/init 명령어를 실행하여 CLAUDE.md 파일을 자동으로 생성하세요. CLAUDE.md 파일은 Claude의 프롬프트 (prompts)의 일부가 되므로, 자주 사용하는 프롬프트와 마찬가지로 정교하게 다듬어야 합니다. 흔히 하는 실수는 효과를 반복적으로 검증하지 않고 방대한 내용을 추가하는 것입니다. 시간을 들여 실험하며 모델로부터 최선의 지침 준수 (instruction following)를 이끌어내는 방법을 결정하세요.

복잡한 문제를 위한 다재다능한 워크플로우 (workflow).

탐색 (Explore): 관련 파일/이미지/URL을 읽습니다. 검증을 위해 서브 에이전트 (subagents)를 사용하세요. 아직 코드를 작성하지 마세요.
계획 (Plan): Claude에게 계획을 세우도록 요청하세요. "think", "think hard", "think harder", 또는 "ultrathink"를 사용하세요.

프롬프트 내에서 깊이를 유도하기 위해 사용하세요 — 전체적인 추론 다이얼(reasoning dial)에 대한 상세 내용은 Effort 레벨을 참조하세요. 선택적으로 향후 참조를 위해 계획(plan)을 저장할 수 있습니다.

Code (코드 작성): 솔루션을 구현합니다; 진행하면서 타당성을 검증합니다.
Commit (커밋): 결과를 커밋하고, 풀 리퀘스트(pull requests)를 생성하며, README/변경 로그(changelogs)를 업데이트합니다.

• Claude에는 두 가지 기본 모드가 있습니다:
  Plan Mode (계획 모드)

및

Accept Edits Mode (편집 수락 모드)

Shift + Tab 키를 사용하여 이 모드들 사이를 전환할 수 있습니다.

💡 프로 팁: 복잡한 작업의 경우 연구 및 계획을 먼저 수행하면 성능이 크게 향상됩니다.

단위 테스트(unit tests) 또는 통합 테스트(integration tests)로 검증 가능한 변경 사항에 이상적입니다.

Write Tests (테스트 작성): 예상되는 입력/출력을 기반으로 테스트를 생성합니다; TDD(테스트 주도 개발)로 표시합니다.
Run & Fail Tests (테스트 실행 및 실패 확인): 테스트가 실패하는지 확인합니다; 아직 구현은 하지 않습니다.
Commit Tests (테스트 커밋): 만족스러우면 테스트를 커밋합니다.
Write Code (코드 작성): 테스트를 통과하도록 코드를 구현합니다; 서브 에이전트(subagents)를 통한 검증과 함께 반복합니다.
Commit Code (코드 커밋): 모든 테스트를 통과한 후 최종 커밋합니다.

🔹 명확한 목표(테스트, 모크(mocks))는 반복(iteration) 효율성을 높입니다.

• 스크린샷 또는 시각적 모크(visual mocks)를 제공합니다.
• 코드를 구현하고, 스크린샷을 찍으며, 출력이 모크와 일치할 때까지 반복합니다.
• 만족스러우면 커밋합니다.

🔹 반복은 출력 품질을 크게 향상시킵니다 (보통 2~3회 정도면 충분합니다).

멘탈 모델(Mental model): Effort는 토큰 예산(token budget)이 아니라 행동 다이얼(behavioural dial)입니다 — 이는 사고의 깊이, 도구 호출(tool-call) 욕구, 응답 길이, 그리고 Claude가 다단계 작업을 얼마나 끈기 있게 밀고 나가는지를 변화시킵니다. 더 높다고 해서 반드시 더 똑똑한 것은 아닙니다; 컨텍스트(context)의 품질이 종종 더 중요합니다.

5가지 레벨이 존재합니다 (대부분의 사용자는 4가지를 가정합니다):

레벨	이럴 때 사용하세요…
low	사용자가 직접 유도하는 빠른 대화형 쿼리 — 파일 이름 변경, 간단한 grep
medium	일반적인 코딩, 작은 규모의 리팩토링(refactors), 계획이 명확한 자율 세션
high	다중 파일 리팩토링, 복잡한 디버깅 — Anthropic이 Sonnet 4.6 / Opus 4.6에 권장하는 기본값
xhigh (Opus 4.7 전용)	긴 자율 에이전트(agentic) 세션 — Anthropic이 Opus 4.7에 권장하는 기본값
max	아키텍처, 미묘한 버그, 보안 검토 — 진정으로 어려운 문제에만 사용

현재 기본값 (2026년 5월): Opus 4.7 → xhigh

; Opus 4.6 + Sonnet 4.6 → high

모든 플랜에 적용됩니다. (“성능이 낮아진 기본값을 사용하는 Pro/Max 사용자”에 대한 설은 ~2026년 3월에서 4월 말까지 사실이었으나, Claude Code v2.1.117에서 수정되었습니다. /effort 명령어로 본인의 설정을 확인하세요.)

지속성 순서에 따른 설정 방법:

# 이번 턴에만 적용 — 컨텍스트 내 힌트를 추가함 (API effort를 변경하지 않음)
> ultrathink — 마이그레이션 전략 설계
# 이번 세션에 적용 — 인자 없는 슬라이더, 인자가 있는 레벨 이름
...

⚠️ 알아두어야 할 세 가지 주의사항:

1. Anthropic이 권장하는 Opus 4.7 max 설정: "일상적인 작업에는 수익 체감(diminishing returns) 현상이 나타나며 과도한 생각(overthinking)에 빠지기 쉽습니다." 따라서 기본값으로 사용하지 마세요. — 오직 "effortLevel": "max"만 사용하세요.
2. settings.json에서 CLAUDE_CODE_EFFORT_LEVEL=max를 설정하면 조용히 다운그레이드됩니다. 환경 변수(env var)를 사용해야 max가 유지됩니다. 컨텍스트(Context)의 품질이 더 많은 노력(effort)보다 효과적인 경우가 많습니다. 만약 필요하지 않은 작업에 max를 사용하고 있다면, 약 80%의 경우 해결책은 상위 단계에 있습니다 — 더 정교한 CLAUDE.md, 원자적 계획(atomic plan), 명확한 파일 이름 지정 등이 필요합니다. 상세 분석 →
3. 💡 패턴: Opus로 계획하고 / Sonnet으로 실행하기. Opus의 xHigh 또는 Max 레벨에서 계획을 세우고, 모호함이 없는 원자적 계획을 낮은 effort 레벨의 Sonnet에게 전달하여 실행하게 하세요. Sonnet은 명확한 계획을 이탈 없이 따르므로, 계획이 날카롭다면 저렴한 실행 비용으로도 신뢰할 수 있는 결과를 얻을 수 있습니다.

Claude Code는 약 30개의 내장 슬래시 명령어(slash commands)와 함께, 사용자가 직접 스킬 (skills) ( .claude/commands/ 디렉토리 내의 마크다운 파일)로 정의할 수 있는 기능을 제공합니다. 이 두 가지는 함께 작동합니다 — 내장 명령어는 일반적인 작업에, 커스텀 스킬은 팀의 워크플로우에 사용됩니다.

명령어	목적
/init	프로젝트를 위한 CLAUDE.md 생성 — Claude가 매 세션마다 읽는 "가이드라인(house rules)"
/help	사용 가능한 모든 명령어 목록 표시
/clear	대화 기록을 초기화하여 깨끗한 상태로 시작
/cost	이번 세션의 토큰 사용량 추적
/model	Opus 4.7, Sonnet 4.6, Haiku 4.5 간 전환 (4.6/4.5는 여전히 사용 가능)

→ 전체 슬래시 명령어 참조: docs/reference/commands.md (/auth, /fast, /hooks, /mcp, /teleport, … 를 포함한 약 30개의 명령어)

자주 사용하는 프롬프트를 마크다운 (markdown) 파일로 한 번 정의해 두면, /skill-name을 통해 영구적으로 호출할 수 있습니다.

:

mkdir -p .claude/commands
echo "Analyze this code for performance issues and suggest optimizations:" \
> .claude/commands/optimize.md

💡

다음 단계: 커스텀 슬래시 명령어 (custom slash commands)와 스킬 (Skills)은 동일한 것입니다. 내장 스킬 (built-in skills), 이 저장소의 7가지 커스텀 스킬, 워크플로 레시피 (workflow recipes), 그리고 직접 작성하는 방법 등 심층적인 내용은 Claude Skills 섹션으로 이동하여 확인하세요.

~3분 분량 · 전체 가이드는 docs/skills.md에서 확인 가능 →

멘탈 모델 (Mental model): 스킬은 하나의 워크플로를 마크다운 파일로 패키징한 것입니다. 두 가지 유형이 있습니다:

슬래시 스킬 (Slash skills)—.claude/commands/<name>.md 파일이며, /<name>으로 호출합니다.

에이전트 스킬 (Agent Skills)—YAML 프론트매터 (frontmatter)가 포함된 .claude/skills/<name>/SKILL.md 파일이며, 설명 (description)이 작업과 일치할 때 Claude가 자동으로 호출합니다.

⚠️ 보안: 스킬은 사용자의 셸 (shell) 권한으로 실행되는 실행 가능한 명령입니다. 서싱 (sourcing)하기 전에 셸 스크립트를 검토하는 것과 똑같이, 서드파티 스킬을 추가하기 전에 반드시 모든 내용을 읽어보세요.

mkdir -p .claude/commands
cat > .claude/commands/analyze.md << 'EOF'
# Code Analysis
...

이것으로 끝입니다 — 작동하는 슬래시 스킬이 완성되었습니다. 나중에 이 파일을 .claude/skills/analyze/SKILL.md로 이동하고 name / description 프론트매터를 추가하여 에이전트 스킬 (Agent Skill)로 격상시킬 수 있습니다.

docs/skills.md에 있는 전체 스킬 가이드는 다음 내용을 다룹니다:

• 이 저장소의 .claude/commands/에 있는 7가지 커스텀 슬래시 스킬: /pr, /review, /tdd, /test, /five, /ux, /todo
• 2가지 내장 스킬 (/keybindings-help, /mermaid)
• 슬래시 스킬 vs 에이전트 스킬 — 각각의 사용 시점, 프론트매터 규약 (frontmatter contract), 전환 경로
• 워크플로 레시피 (Workflow recipes) — TDD + PR을 활용한 기능 개발, 버그 조사, UX 우선 개발
• 자신만의 스킬을 작성하는 방법 (파일 형식, 범위, 예시)
• 스킬 FAQ, 문제 해결 (troubleshooting), 그리고 모범 사례 (best practices)

커뮤니티는 수천 개의 에이전트 스킬을 구축해 왔습니다. 둘러보기 시작할 세 곳은 다음과 같습니다:

리소스 (Resource)	제공 내용
anthropics/skills	Anthropic의 공식 스킬 (skills) — PDF, 슬라이드, 브랜드 가이드라인, 문서 생성
SkillHub · SkillsMP · Smithery	검색 가능한 마켓플레이스 — GitHub에서 인덱싱된 수천 개의 커뮤니티 에이전트 스킬 (Agent Skills)
travisvn/awesome-claude-skills · ComposioHQ/awesome-claude-skills	높은 신호 (high-signal)를 가진 엄선된 리스트

주요 커뮤니티 스킬: skill-creator, skill-installer, mcp-builder, systematic-debugging, pair-programming, github-code-review, pptx, react, frontend-design, prompt-engineering-patterns, superpowers, brainstorming, market-research-reports, senior-data-engineer 등 다수 — 분류된 표와 설치 경로를 확인하려면 docs/skills.md의 전체 에코시스템 (ecosystem) 섹션을 참조하세요.