CLAUDE CODE DEEP DIVE WORKSHOP · 시리즈 1/6
① Overview — Claude Code 전체 그림 잡기
터미널에서 동작하는 에이전틱 코딩 도구, Claude Code의 정체와 설치·인증·핵심 도구·메모리·워크플로까지 한 번에 정리합니다.
1. What is Claude Code
자동완성(Copilot)이나 IDE 채팅(Cursor)과 달리, Claude Code는 파일을 직접 읽고·수정하고·명령을 실행하며 여러 단계 작업을 자율 수행합니다. 대표적인 5가지 활용:
- 디버깅 — 에러를 주면 원인 추적 → 수정 → 검증
- 리팩토링 — 구조 개선을 다중 파일에 안전하게 반영
- 신기능 개발 — 계획 후 구현
- 코드베이스 학습 — 낯선 프로젝트 구조·역할 파악
- 테스트 작성 — 커버리지 보강
2. Architecture — Agentic Harness의 내부 구조
Claude Code의 본질은 Agentic Harness입니다 — 맥락 수집 → 행동(도구 실행) → 검증을 반복하는 루프죠. 이 루프를 아래 3계층이 떠받칩니다.
- Client Layer (Agent SDK) — CLI/IDE/SDK 진입점
- Tool System — Read·Edit·Write·Bash·Grep·Glob·Web 등을 에이전트가 스스로 선택 호출
- Permission Model — 도구 실행 시 승인 요청으로 안전성 확보
3. Installation
- npm —
npm install -g @anthropic-ai/claude-code - Native Installer — OS별 독립 설치본
- Node 버전 관리자 — nvm/fnm/Volta 사용 시
sudo불필요(권장) - Docker / WSL2 / Devcontainer — 격리·팀 표준 환경
검증: claude --version, claude doctor(System/Network/Auth/Config 자가 진단).
4. Authentication — 인증 경로 (최신 에디션 6경로)
| 방식 | 특징 |
|---|---|
| ① OAuth (구독) | Max/Pro 계정 브라우저 로그인, 가장 빠름. 사용량 모니터링 제공 |
| ② Anthropic API Key | ANTHROPIC_API_KEY 환경변수, 종량제 |
| ③ AWS Bedrock | CLAUDE_CODE_USE_BEDROCK=1 + IAM 정책, AWS 청구 |
| ④ Vertex AI | GCP 프로젝트 + ADC 자격증명 |
세션 내 /login·/logout으로 전환. (구독 로그인 시 "Max/Pro required"가 뜨면 계정 등급 문제입니다.)
🆕 최신 20260703 에디션은 인증을 6경로로 확장합니다 — 위 4가지 + ⑤ LLM Gateway(사내 프록시, ANTHROPIC_BASE_URL) + ⑥ Enterprise SSO 흐름. 자세한 표는 아래 심화 섹션 참고.
5. Quick Start
- 대화형 REPL 진입(
claude), 핵심 명령:/init /help /status /clear - 3대 시나리오: 디버깅 / 기능 추가(Plan 모드) / 리팩토링
- Plan 모드 — 실행 전 계획 제시(
Shift+Tab) - 세션 관리 —
/resume,--continue
6. Core Capabilities — 핵심 도구
- 파일: Read(라인 범위·멀티모달) · Edit(찾기-바꾸기·다중 파일) · Write · NotebookEdit
- 실행: Bash(백그라운드 포함)
- 탐색: Grep(정규식) · Glob · WebSearch · WebFetch
- Git: 워크플로·커밋 메시지·PR 생성 자동화
- 권한 모드: allow/deny → ask(매번 확인) → auto-accept → yolo(전체 자동, 위험)
7. Interfaces — IDE 통합
- VS Code — 확장 설치, 명령 팔레트, 선택 영역을 컨텍스트로 전달
- JetBrains — 플러그인 설치
- 외부 에디터 — Vim / Emacs / Neovim 연동
8. CLAUDE.md & Memory
- 메모리 계층: Enterprise → User(~/.claude) → Project(./CLAUDE.md) → Local, 우선순위로 병합
- 매 세션 자동 로드되어 규칙·명령·컨벤션 주입
- 생성/편집:
/init·/memory·#(빠른 추가),@경로import - 적정 분량 500~1500 단어, 실행 가능한 명령 위주로 간결하게
9. Workflow Patterns — 실무 패턴 10선
① 기본 프롬프트 · ② TDD · ③ 코드 리뷰 · ④ 멀티 에이전트 · ⑤ Visual(스크린샷) · ⑥ Headless(-p) · ⑦ Pipeline/JSON 출력 · ⑧ CI/CD 통합 — 여기에 최신 에디션은 ⑨ 컨텍스트 관리(/clear·/compact)와 ⑩ 비용 최적화(모델 선택)를 더해 실무 패턴 10선으로 정리합니다. Cost Management는 --model haiku·도구 제한으로 비용 절감.
실습 체크리스트
☐ Claude Code 설치 + 본인 계정 인증
☐ ch1-overview 스니펫 10개 파트 직접 실행
☐ 샘플 프로젝트에 CLAUDE.md 작성
☐ Plan 모드로 기능 하나를 계획 → 승인 → 실행
☐ git log로 chore→fix→feat 커밋 이력 남기기
🧪 핸즈온 랩 — 설치부터 Headless까지 (약 40분)
작업 폴더 ~/claude-lab/ch1. 설치·인증 → 버그 수정 → 자동화까지 end-to-end로 진행합니다.
| Task | 내용 | 체크포인트 |
|---|---|---|
| 00 사전 준비 | OS/Node18+/Git 확인 | node -v, git -v 정상 |
| 01 설치·검증 | claude --version, claude doctor | errors 0 |
| 02 인증 | 4방식 중 택1 → /status | Auth 항목 표시 |
| 03 프로젝트·첫 세션 | 샘플 생성(의도된 버그) → Read/Glob 관찰 | Read 도구 호출 관찰 |
| 04 CLAUDE.md | /init → 규칙 편집 → 새 세션서 반영 | 규칙 근거로 답함 |
| 05 디버깅·Plan | 에러 전달 → Read→Grep→Edit→Bash → Plan 모드 soft delete | npm test 전부 PASS |
| 06 Headless | claude -p + --output-format json + review.sh | review.md 생성 |
산출물 — CLAUDE.md 포함 프로젝트 + Plan 모드 기능(soft delete) + Headless 스크립트(review.sh)
🧪 핸즈온 상세 실습 기록
진행 요약
| Task | 내용 | 상태 |
|---|---|---|
| 00 사전 준비 | node v24.13.0 · git 2.50.1 확인 | ✅ |
| 01 설치·검증 | claude --version → 2.1.220 | ✅ |
| 02 인증 | 앱 세션 인증 사용(구독 로그인 등급 이슈 확인) | ✅ |
| 03 프로젝트·첫 세션 | 샘플 생성 + 의도된 버그 재현 | ✅ |
| 04 CLAUDE.md | 프로젝트 규칙 작성 | ✅ |
| 05 디버깅·Plan | 버그 수정 + soft delete 기능 | ✅ |
| 06 Headless | claude -p 패턴 학습 | ✅ |
Task 00–01 · 환경 확인
node --version # v24.13.0 (요구 18+ 충족)
git --version # 2.50.1
claude --version # 2.1.220
claude doctor # System/Network/Auth/Config 자가 진단Task 03 · 실습 프로젝트 (의도된 버그)
src/userService.js의 getUserPlan이 profile 없는 사용자(id 3, Park)에서 크래시:
TypeError: Cannot read properties of undefined (reading 'plan')
at getUserPlan (src/userService.js:9)Test 1(pro)·Test 2(free)는 PASS, Test 3(profile 없음)에서 크래시 — 이걸 Task 5에서 고칩니다.
Task 04 · CLAUDE.md 작성
5개 섹션(Overview / Stack / Commands / Conventions / Don't)으로 규칙 정의. 특히 두 규칙이 이후 설계를 좌우했습니다:
- Conventions: "존재하지 않는 데이터는 예외를 던지지 말고 기본값을 반환"
- Don't: "src/users.js의 데이터 구조를 임의로 변경하지 않기"
Task 05 · 디버깅 + Plan 모드
① 버그 수정 (Read → Grep → Edit → Bash)
옵셔널 체이닝 + 기본값으로 수정:
// Before
return user.profile.plan;
// After
return user?.profile?.plan ?? "unknown";→ npm test 3개 전부 PASS. 커밋 931292e (fix).
② Plan 모드로 soft delete 추가
계획 검토 → 승인 → 구현. CLAUDE.md의 "Don't(users.js 변경 금지)" 규칙과 충돌을 감지해, 데이터 구조를 건드리지 않고 런타임에 deletedAt을 부여하는 방식으로 설계:
export function getUser(id) {
return users.find((u) => u.id === id && !u.deletedAt); // 삭제 제외
}
export function removeUser(id) {
const user = users.find((u) => u.id === id);
if (!user) return false;
user.deletedAt = new Date().toISOString(); // soft delete
return true;
}test.js에 삭제 시나리오 2개 추가 → 5/5 PASS. 커밋 4daada8 (feat).
Task 06 · Headless 자동화
# 기본
claude -p "이 프로젝트의 구조를 3줄로 요약" --output-format text
# 읽기전용 도구 제한 + JSON
claude -p "코드 품질 이슈 분석" \
--allowed-tools "Read,Grep,Glob" --output-format json > report.json
# 자동화 스크립트 (직전 커밋 diff 리뷰)
DIFF=$(git diff HEAD~1); echo "$DIFF" | \
claude -p "이 diff를 코드 리뷰" --allowed-tools "" > review.md🔒 --allowed-tools "Read,Grep,Glob" = 읽기 전용만 허용 → 무인 실행 중 파일 수정 차단. 💰 간단한 작업은 --model haiku.
최종 산출물 & 커밋 이력
4daada8 feat: soft delete 기능 추가 (removeUser)
931292e fix: getUserPlan에 옵셔널 체이닝으로 profile 없는 사용자 처리
f0a5e90 chore: initial lab project1. 좋은 프롬프트 = 대상·목표·제약·검증
2. CLAUDE.md는 살아있는 규칙 — "Don't" 한 줄이 설계를 바꿈
3. 큰 변경은 Plan 모드, 작은 수정은 Auto
4. Headless는 읽기전용 도구 제한이 안전장치
📚 심화 · 비교 · 트러블슈팅 · FAQ
🆚 Copilot · Cursor · Claude Code, 뭐가 다른가
| 구분 | GitHub Copilot | Cursor | Claude Code |
|---|---|---|---|
| 형태 | 에디터 자동완성 | AI 내장 IDE | 터미널 에이전트 |
| 작업 단위 | 줄/블록 제안 | 파일 편집 | 다단계 작업 자율 수행 |
| 도구 실행 | ✕ | 일부 | 파일·Bash·Git·Web 직접 호출 |
| 자동화(CI) | ✕ | ✕ | Headless(-p)로 파이프라인 통합 |
| 한 줄 요약 | "타이핑을 돕는다" | "IDE 안에서 돕는다" | "일을 대신 한다" |
⌨️ 자주 쓰는 슬래시 커맨드 치트시트
| 명령 | 동작 | 언제 |
|---|---|---|
/init | CLAUDE.md 자동 생성 | 프로젝트당 1회 |
/status | 인증·모델·컨텍스트 사용량 | 점검 시 |
/clear | 컨텍스트 초기화 | 작업 전환 시 |
/compact | 오래된 메시지 요약 압축 | 컨텍스트 부족 시 |
/cost | 토큰·비용 확인 | 주기적 |
Shift+Tab | Plan 모드 토글 | 큰 변경 전 |
✍️ 좋은 프롬프트의 4요소 — 대상·목표·제약·검증
에이전트의 정확도는 프롬프트 구조에서 갈립니다. 이 4가지를 명시하세요.
🔐 권한 모드 4단계 — 언제 무엇을
| 모드 | 동작 | 추천 상황 |
|---|---|---|
| allow/deny | 패턴별 허용/차단 사전 정의 | 팀 표준 |
| ask | 민감 작업마다 승인 요청 | 기본·안전 (권장) |
| auto-accept | 승인 없이 자동 실행 | 신뢰된 반복 작업 |
| yolo | 전체 자동 (제한 없음) | ⚠️ 격리 환경만 |
💰 비용, 이렇게 아낀다
- 간단한 작업은
--model haiku— 빠르고 저렴 /cost로 세션 비용 주기적 확인,/compact로 컨텍스트 압축- Headless에서
--allowed-tools "Read,Grep,Glob"로 불필요한 도구 호출 차단 - 반복되는 긴 컨텍스트는 Prompt Caching(Ch6에서 심화)으로 절감
🧯 자주 막히는 지점 & 처방
| 증상 | 원인 · 처방 |
|---|---|
| "Claude Max or Pro is required" | 구독 로그인을 골랐는데 계정이 Free 등급. → Max/Pro 계정으로 로그인하거나 API 키/Bedrock 방식으로 전환 |
| npm 설치 권한 오류 | npm config get prefix가 /usr/local이면 sudo 필요. nvm/fnm/Volta 쓰면 sudo 불필요 |
| 인증/네트워크가 이상함 | claude doctor로 System/Network/Auth/Config 자가 진단 |
| 엉뚱한 파일을 건드림 | CLAUDE.md의 Don't 섹션에 금지 규칙 명시 + 권한 ask 모드 유지 |
🏗️ Architecture 다시 보기 — Agentic Harness 루프
Claude Code를 "AI 채팅"이 아니라 에이전틱 하네스(Agentic Harness)로 보면 동작이 명확해집니다. 매 턴마다 아래 루프를 돕니다.
② 행동(Act) — Edit·Write·Bash로 실제 변경·명령 실행 (권한 승인 개입)
③ 검증(Verify) — 테스트·빌드·재조회로 결과 확인 → 실패 시 ①로 되돌아 반복
이 루프를 Client Layer(SDK) · Tool System · Permission Model 3계층이 떠받칩니다. "왜 도구를 여러 번 호출하지?"의 답이 바로 이 검증-반복 루프입니다.
🔑 인증 6경로 (최신 20260703 에디션)
| 경로 | 설정 | 주 용도 |
|---|---|---|
| ① 구독(OAuth) | 브라우저 로그인 | 개인 Max/Pro |
| ② API Key | ANTHROPIC_API_KEY | 종량제 |
| ③ Bedrock | CLAUDE_CODE_USE_BEDROCK=1 | AWS 조직 |
| ④ Vertex AI | GCP + ADC | GCP 조직 |
| ⑤ LLM Gateway | ANTHROPIC_BASE_URL (프록시) | 사내 게이트웨이 |
| ⑥ Enterprise SSO | IdP 연동(SSO 로그인) | 대규모 조직 |
⑤⑥은 사내 프록시·조직 인증 시나리오로, 대부분 Ch3(Admin)에서 심화됩니다.
🔁 워크플로 실무 패턴 10선
| # | 패턴 | # | 패턴 |
|---|---|---|---|
| ① | 기본 프롬프트 | ⑥ | Headless(-p) |
| ② | TDD | ⑦ | Pipeline / JSON |
| ③ | 코드 리뷰 | ⑧ | CI/CD 통합 |
| ④ | 멀티 에이전트 | ⑨ | 컨텍스트 관리(/clear·/compact) |
| ⑤ | Visual(스크린샷) | ⑩ | 비용 최적화(모델 선택) |
🗂️ 실습을 자산으로 — JOURNEY.md & SUMMARY.md
실습을 그때그때 흘려보내지 말고 누적 기록 문서로 남기면 복습·포트폴리오가 됩니다. Hook(SessionStart/Stop)이나 CLAUDE.md 규칙으로 자동 업데이트되게 설정할 수 있습니다.
- JOURNEY.md — 진행 현황 표 · 버전 · 리소스 아키텍처 · 트러블슈팅 이력(날짜·문제·원인·해결)을 case마다 한 줄씩 누적
- SUMMARY.md — 챕터별 요약 · 아키텍처 · 트러블슈팅 · 현업 운영 고려사항(DevOps)을 정리
→ "무엇을, 왜, 어떻게 고쳤는가"가 남아 다음 챕터·실무에서 그대로 재사용됩니다.
🧪 확장 핸즈온 — 공식 랩 너머 Case 1~6
공식 랩(Task 1~6)은 기본기입니다. 여기에 직접 시나리오를 만들어 Claude Code의 폭을 넓혀 보세요.
| Case | 내용 |
|---|---|
| 1 복구 | 손상된 파일(잘못 섞인 코드 조각) 진단·복구 |
| 2 기능 추가 | soft delete(deletedAt·removeUser) — Plan 모드 |
| 3 결함 수정 | 저장소 분석 → null 예외·테스트 종료코드 결함 수정 |
| 4 데이터 보강 | 누락 데이터 보강 + 회귀 테스트 갱신 |
| 5 코드베이스 학습 | 낯선 프로젝트를 대화로 파악 + 테스트 커버리지 갭 분석 |
| 6 DevOps 자동화 | 스크립트·IaC·파이프라인 작성과 점검 |
❓ FAQ
Q. 구독 없이 써볼 수 있나요?
A. 네. Anthropic Console에서 API 키를 발급해 ANTHROPIC_API_KEY로 종량제 사용하거나, AWS Bedrock/Vertex를 쓸 수 있습니다.
Q. 코드를 마음대로 바꾸면 위험하지 않나요?
A. 기본 ask 모드에서 파일 수정·명령 실행마다 승인을 요청합니다. Git으로 관리하면 되돌리기도 쉽습니다.
Q. VS Code에서도 되나요?
A. 확장으로 연동됩니다. 선택 영역을 컨텍스트로 넘길 수 있습니다.
역할별 전문 에이전트(code-reviewer·test-writer 등)를
.claude/agents/에 정의하고, Task 툴로 자동·병렬 위임하는 법을 다룹니다.
📚 참고 — Claude Code 공식 문서 · claude doctor로 언제든 상태 점검.