Claude Code 101 가이드북 (나만의 학습 노트)

Anthropic이 공개한 무료 강좌 "Claude Code 101" (전체 13개 레슨)을 보고 정리한 개인 학습 노트입니다. Claude Code의 작동 원리를 알아두면 실제로 다룰 때 훨씬 쉬워집니다.

목차

1. Claude Code란 무엇인가?
2. Claude Code 작동 방식 (에이전트 루프)
3. Claude Code 설치
4. 첫 프롬프트 작성하기
5. Explore → Plan → Code → Commit 워크플로
6. 컨텍스트 관리
7. 코드 검토
8. CLAUDE.md 파일
9. 하위 에이전트 (Sub-agents)
10. 기술 (Skills)
11. MCP (Model Context Protocol)
12. 갈고리 (Hooks)
13. 과목 퀴즈
14. [부록] 컨텍스트 관리 방법 한눈에 비교

---

1. Claude Code란 무엇인가?

정의

• 코드베이스를 이해하고, 직접 파일을 수정하며, 터미널 명령어를 실행할 수 있는 에이전트형(Agentic) 코딩 도구
• 지원 환경: 터미널, VS Code, JetBrains IDE 등

일반 Claude.ai와의 차이

• 대화형 AI는 답변만 주지만, Claude Code는 파일 시스템·터미널에 직접 접근해 스스로 수정/실행/확인까지 수행

에이전트로서 할 수 있는 일

• 코드 이해: 전체 코드베이스 읽기, 기능 설명, 버그 추적
• 작업 자동화: 빌드/테스트 실행, 패키지 설치
• 외부 검색: 최신 API 문서가 필요하면 웹 검색까지 스스로 수행

꼭 알아야 할 개념

• 컨텍스트 창(Context Window): Claude의 '작업 기억력'. 전체 코드를 다 외우는 게 아니라 필요한 정보를 전략적으로 찾아 씀
• 사용자 권한(Permission): 명령 실행/코드 수정 전 승인 절차를 거침 → 항상 개발자가 통제권을 가짐
• 완벽하지 않음: 의도와 다르게 수정하거나 버그를 만들 수 있어 항상 검토 필요

💡 한 줄 요약: Claude Code는 코드를 생성만 해주는 게 아니라 내 개발 환경에서 직접 작업을 처리하는 협업 파트너다.

2. Claude Code 작동 방식 (에이전트 루프)

에이전트 루프(Agentic Loop)

1. 컨텍스트 수집 – 프롬프트 이해 + 필요한 코드베이스 정보 모으기
2. 행동 실행 – 파일 수정, 터미널 명령 실행
3. 결과 검증 – 의도와 일치하는지 확인
4. 반복 – 완료될 때까지 자동 반복 (그 사이 언제든 사용자가 개입 가능)

컨텍스트 윈도우 관리

• 대화, 파일, 명령 출력 등을 모두 기억하는 공간
• 한계에 가까워지면 중요도를 판단해 요약/삭제(compact)하며 관리

도구(Tools) 활용

• 시맨틱 검색 등을 통해 상황에 맞는 도구(파일 읽기, 웹 검색 등)를 스스로 선택해 호출

권한 모드(Permission Modes)

• 기본 모드: 파일 수정/명령 실행 전 항상 승인 요청
• Auto Accept: 파일 수정은 자동 승인, 명령 실행은 여전히 확인
• Plan Mode: 읽기 전용 도구만 사용해 먼저 계획을 세움

⚠️ 주의: 권한을 전부 자동으로 넘기면 실수 대응이 어려워질 수 있음

3. Claude Code 설치

터미널 설치

• Mac/Linux/WSL: curl 명령으로 설치 (Homebrew도 가능하지만 자동 업데이트 미지원)
• Windows: PowerShell → Invoke-RestMethod, CMD → curl (Winget 가능하지만 자동 업데이트 미지원)
• 최초 실행: 프로젝트 폴더에서 claude 실행 → 테마 선택 → 계정(Pro/Max/Enterprise) 또는 API 키로 로그인

IDE 통합

• VS Code: 확장 프로그램에서 검색 후 설치, Cmd/Ctrl+Shift+P로 실행 또는 파일 옆 Claude 아이콘 클릭
• JetBrains: 마켓플레이스에서 설치 후 재시작하면 Claude 로고 등장

기타 환경

• Claude Desktop: 로그인 후 상단 'Code' 토글 활성화, 특정 폴더/클라우드 환경 작업 가능
• 웹 (claude.ai/code): GitHub 저장소 연동해 원격 작업 가능

선택 가이드

• 최신 기능이 가장 빠른 곳 → 터미널
• 코딩 환경과 밀착 → VS Code / JetBrains 플러그인
• 멀티태스킹 → Desktop 앱
• 여러 세션 동시 관리, 원격 GitHub 작업 → 웹

4. 첫 번째 프롬프트

모드 전환: Shift + Tab으로 전환

• Auto-accept 모드: 파일 변경은 자동 승인, 명령 실행은 승인 필요
• Approval 모드: 모든 변경마다 승인 필요

Plan Mode

• 프롬프트 분석 → 읽기 전용 도구로 코드베이스 파악 → 질문 → 상세 계획 제시
• 다단계 기능 추가, 안전한 코드 리뷰에 특히 유용

실전 예시 (다크모드 구현)

1. Shift+Tab으로 Plan 모드 진입
2. 구체적 요청 입력 (다크모드 전체 적용, 헤더 토글 스위치, 라이트 테마와 대비되는 색상 제안 등)
3. Claude가 제시한 계획 검토
4. 실행 승인

💡 팁: 프롬프트는 최대한 구체적으로. 통제권을 유지하려면 Plan Mode를 적극 활용하자.

5. Explore → Plan → Code → Commit 워크플로

① Explore & Plan

• Shift+Tab으로 Plan Mode 진입 → Claude가 파일 수정 없이 코드 읽기/웹 검색으로 구현 방법 연구 후 실행 계획 제시
• 계획 단계에서 수정 요청하는 것이 코드 작성 후 고치는 것보다 훨씬 효율적

② Code

• 계획 단계에서 '성공 기준'을 명확히 정의
• 보조 도구 적극 활용 (예: 웹 UI 작업 시 Claude Chrome Extension으로 테스트)
• 프로젝트에 테스트 스위트 포함 → Claude가 지속적으로 검증하게 함
• 반복되는 문제 해결책은 CLAUDE.md에 저장해 컨텍스트 유지

③ Commit

• 커밋 전 서브 에이전트 코드 리뷰어 실행
• 커밋 메시지는 Claude에게 스타일대로 작성 요청

💡 핵심: 코딩 전에 Plan Mode로 충분히 연구/계획하는 것만으로 효율이 극대화된다. 이후 테스트 + 서브 에이전트 리뷰로 품질 보장.

6. 컨텍스트 관리 (Context Window)

컨텍스트 윈도우란

• Claude의 작업 메모리. 파일 읽기, 명령 실행, 메시지 등 모든 상호작용이 이 공간을 차지 → 유한하므로 관리 필수

명령어

• /compact: 대화 내용을 요약하고 불필요한 도구 호출 결과 제거. 컨텍스트가 찼지만 이전 내용을 계속 기억해야 할 때 유용
• /clear: 대화 기록 완전 삭제 후 새로 시작. 새 기능/프로젝트 시작 시 이전 대화의 편향을 막기 위해 사용
• /context: 현재 컨텍스트 사용 현황을 카테고리별 그래프로 확인

효율적 관리 팁

• CLAUDE.md 활용: 세션이 끝나도 기억해야 할 중요 정보는 파일에 기록
• 프롬프트는 구체적으로: 너무 짧으면 Claude가 더 많이 탐색해야 해서 오히려 컨텍스트를 더 소모
• 관련 없는 MCP 서버는 비활성화, 컨텍스트를 통째로 점유하지 않는 Skills 기능 활용
• Sub-agents 활용: 독립된 컨텍스트에서 특정 작업을 위임하고 결과만 요약 받기

📌 요약: 기억 유지 필요 → /compact · 새 시작 필요 → /clear · 상태 확인 → /context

---

7. 코드 검토 (Code Review)

기본 원칙

• 변경사항 점검: 작업 후 Diff 분석을 요청해 의도치 않은 수정/버그를 방지
• 자동화 검증: 수정 후 테스트 스위트(npm test, pytest 등)를 실행해 통과 여부를 Claude가 직접 검증하도록 유도

Anthropic의 Code Review 기능 (2026년 3월 발표, Team/Enterprise 리서치 프리뷰)

• PR이 열리면 여러 에이전트를 동시에 투입해 버그를 찾고, 오탐을 걸러낸 뒤 심각도 순으로 정리해 PR에 종합 코멘트 + 라인별 코멘트로 남겨줌
• 변경 규모에 따라 투입되는 에이전트 수와 검토 깊이가 달라지며, 평균 검토 시간은 약 20분
• Anthropic 내부 적용 결과, 의미 있는 리뷰 코멘트가 달리는 PR 비율이 16%에서 54%로 증가
• 승인 여부는 여전히 사람이 결정하며, 비용은 PR 크기에 따라 건당 대략 15~25달러 수준
• 조직 단위 월 비용 한도, 저장소별 활성화 여부, 검토 현황 대시보드 등으로 관리 가능

💡 팁: 가벼운 자동 리뷰(GitHub Action)와 깊은 멀티 에이전트 리뷰는 목적이 다르다. 중요 PR일수록 깊은 리뷰가, 사소한 PR엔 가벼운 리뷰가 어울린다.

8. CLAUDE.md 파일

정의와 역할

• 프로젝트 루트에 두는 마크다운 파일로, Claude Code가 세션을 시작할 때마다 자동으로 읽어 들이는 '온보딩 문서'
• 프로젝트의 기술 스택, 구현된 기능, 코딩 스타일을 미리 알려줘 매번 반복되는 시행착오를 줄여줌
• /init 명령어를 입력하면 코드베이스를 분석해 초기 파일을 자동 생성

작성 가이드

• 포함할 내용: 기술 스택(예: Next.js, Tailwind, ORM 등), 코드 스타일(인덴트·명명 규칙), 프로젝트 관례(API 경로, 우선 패턴 등)
• 성장형 작성: 처음부터 다 적기보다 Claude가 실수를 반복하거나 수정이 필요할 때마다 "메모리에 저장해줘"라고 요청해 점진적으로 보완
• @파일경로로 다른 문서를 참조시킬 수 있음

계층 구조

• 프로젝트 레벨: 루트 디렉토리, 팀 전체가 공유하는 규칙
• 사용자 레벨: 개인 설정 폴더, 모든 프로젝트에 적용되는 개인 습관·선호

⚠️ 주의: 파일이 너무 길어지면(권장 200줄 이하) 반복 절차는 Skills로, 특정 경로에만 적용되는 규칙은 rules로 분리하는 게 좋음

9. 하위 에이전트 (Sub-agents)

개념

• 특정 작업을 위임받아 각자 독립된 컨텍스트 윈도우와 커스텀 시스템 프롬프트로 동작하는 전문 보조 에이전트
• 작업이 끝나면 요약만 메인 대화로 반환하고, 중간 과정(파일 탐색, 검색 등)은 모두 격리되어 폐기됨

왜 유용한가

• 예: "결제 시스템에서 환불을 처리하는 서비스가 어디인지 찾아줘" 같은 조사성 작업은 파일 15개를 읽고 여러 번 검색해야 할 수도 있음
• 서브 에이전트 없이 진행하면 그 탐색 과정 전체가 메인 컨텍스트를 채우지만, 서브 에이전트를 쓰면 결과만 받고 메인 창은 깨끗하게 유지됨

기본 제공 서브 에이전트

• general-purpose: 탐색과 실행이 모두 필요한 다단계 작업용
• explore: 코드베이스를 빠르게 검색하는 용도
• plan: Plan Mode에서 계획을 제시하기 전 코드베이스를 조사·분석하는 용도
• 커스텀 시스템 프롬프트와 툴 권한을 지정해 나만의 서브 에이전트도 만들 수 있음

⚠️ 한계: 메인 창은 서브 에이전트가 어떤 과정을 거쳐 결론에 도달했는지 볼 수 없음. 과정을 직접 확인하고 싶다면 Skills가 더 적합.

10. 기술 (Skills)

개념

• 특정 작업을 한 번 가르쳐두면 필요할 때마다 Claude가 자동으로 꺼내 쓰는 지침 모음(마크다운 SKILL.md 파일 기반)
• 코딩 표준, PR 리뷰 형식, 커밋 메시지 규칙처럼 매번 반복 설명해야 했던 내용을 대신함

저장 위치

• 개인 스킬: ~/.claude/skills — 모든 프로젝트에 적용되는 개인 선호(커밋 스타일, 문서 형식 등)
• 프로젝트 스킬: .claude/skills (리포지토리 루트) — 팀 공통 표준(브랜드 가이드, 디자인 시스템 등)을 공유, 클론한 모든 사람에게 자동 적용

CLAUDE.md와의 차이

• CLAUDE.md: 모든 대화에 항상 로드 → 항상 지켜야 할 기본 설정에 적합
• Skills: 세션 시작 시엔 이름·설명만 대기 상태로 로드되고, 관련 작업이 감지될 때만 본문이 로드 → 컨텍스트를 불필요하게 차지하지 않음

💡 핵심: 슬래시 명령어를 직접 칠 필요 없이 Claude가 상황을 인식해 자동 적용한다. 똑같은 설명을 반복하고 있다면 그건 Skill로 만들 신호다.

11. MCP (Model Context Protocol) 🔜 (상세 내용 추가 예정)

• 개념: 외부 도구(Linear, GitHub, Figma, DB 등) 및 데이터 소스에 연결하는 개방형 표준 프로토콜
• 서버 유형: HTTP 서버(원격 서비스), Stdio 서버(로컬 프로세스)
• 스코핑: 로컬(본인/현재 프로젝트), 사용자(모든 프로젝트), 프로젝트(.mcp.json으로 팀 공유)
• 컨텍스트 관리: /mcp로 연결 상태 확인, 미사용 서버는 비활성화 권장

12. 갈고리 (Hooks)

핵심 개념

• 특정 라이프사이클 이벤트마다 명령어를 자동으로, 예외 없이 실행하는 결정론적(Deterministic) 자동화 도구
• 프롬프트로 부탁하는 것과 달리 조건이 맞으면 반드시 발동함

주요 이벤트 (settings.json에 등록)

• UserPromptSubmit: 프롬프트가 처리되기 직전
• PreToolUse: 툴 호출 직전
• PostToolUse: 툴 호출 완료 직후
• Notification / Stop: 알림 발송 시 / 응답 완료 시

활용 사례

• 자동 포맷팅(PostToolUse): 파일 수정 시마다 Prettier, gofmt, Ruff 등을 자동 실행
• 위험 작업 차단(PreToolUse): 입력을 검사해 종료 코드 0이면 통과, 2면 차단하고 표준 에러 메시지로 Claude에게 이유를 전달 (예: 프로덕션 설정 수정 금지, rm -rf 차단)

팀 협업

• settings.json의 Hooks 설정을 레포지토리에 체크인하면 팀 전체가 같은 규칙을 공유
• ${CLAUDE_PROJECT_DIR} 같은 환경 변수를 쓰면 실행 위치와 무관하게 항상 같은 스크립트를 참조

📌 핵심 요약: 반복 작업이나 실수가 허용되지 않는 보안 규칙은 프롬프트에 의존하지 말고 Hooks에 맡기자. 가장 확실한 자동화 방식이다.

13. 과목 퀴즈 (Course Quiz) 🔜 (상세 내용 추가 예정)

• 핵심 체크포인트: CLI 기본 사용법·에이전트 루프 이해, Skills vs MCP 차이 및 컨텍스트 비용, .mcp.json·CLAUDE.md를 통한 팀 공유, /compact 등 토큰 관리 최적화 전략

---

14. [부록] 컨텍스트 관리 방법 한눈에 비교

Claude Code에서 지시를 넣는 방법은 여러 가지이고, 방법마다 컨텍스트 비용(토큰 소모)과 권한(강제력)이 다르다. 이 두 축으로 CLAUDE.md·Skills·Sub-agents·Hooks를 구분해서 쓰면 된다.

방법	언제 로드되나	압축(compact) 후 유지	컨텍스트 비용	대표 용도
CLAUDE.md	세션 시작, 세션 내내 유지	다시 읽어 유지	높음	빌드 명령·폴더 구조·코딩 규칙·팀 관례
Skills	이름·설명만 시작 시, 본문은 호출 시	호출된 스킬만 재주입	낮음	배포·리뷰 등 반복 절차
Sub-agents	이름·설명·툴 목록만 시작 시	최종 요약만 메인에 반환	낮음(호출 전 0)	격리된 곁가지 작업(검색·로그·감사)
Hooks	라이프사이클 이벤트 발동 시	압축 영향 없음	낮음	확정적 자동화·차단

상황별 선택 기준

• "매번 X 하면 항상 Y 하라"는 CLAUDE.md에 적지 말고 Hooks로 옮기자. 반드시 실행돼야 하는 동작은 판단이 아니라 자동 실행이어야 한다.
• "절대 이건 하지 마라"는 프롬프트 지시만으로는 완전히 강제되지 않는다. 진짜 가드레일이 필요하면 Hooks·permissions 같은 결정론적 방법을 쓰자.
• 30줄 넘는 절차를 CLAUDE.md에 넣고 있다면 Skills로 옮기자. CLAUDE.md는 '항상 알아야 할 사실'용이다.
• 개인 취향은 팀 공용 CLAUDE.md가 아니라 개인 레벨 파일에 적자.

✍️ 이 문서는 계속 업데이트됩니다. 11장(MCP), 13장(퀴즈)의 상세 내용을 받으면 채워나갈 예정입니다.