Claude Code가 뭔가요?
Claude Code는 Anthropic이 만든 터미널 기반 AI 코딩 어시스턴트입니다. 터미널에서 대화를 나누면서 파일을 읽고, 코드를 편집하고, 명령을 실행하고, 웹을 검색할 수 있습니다.
대화형 REPL
터미널에서 자연어로 요청하면 Claude가 도구를 사용하여 실제로 작업을 수행합니다.
40+ 내장 도구
파일 읽기/쓰기, Bash 실행, 웹 검색, Git 작업 등 다양한 도구를 자동으로 선택합니다.
프로젝트 이해
CLAUDE.md 파일과 메모리 시스템으로 프로젝트 규칙과 사용자 선호도를 기억합니다.
MCP로 확장
Model Context Protocol을 통해 외부 도구와 서비스를 자유롭게 연결할 수 있습니다.
왜 내부 구조를 알아야 할까요?
Claude Code의 내부를 이해하면 — 어떤 프롬프트가 Claude에게 전달되는지, 도구가 어떻게 선택되는지, 메모리가 어떻게 작동하는지 — 의도를 더 정확하게 전달할 수 있어 작업 효율이 크게 향상됩니다.
전체 그림: 머릿속에 그려야 할 지도
Claude Code는 크게 5개 층(Layer)으로 구성됩니다. 위에서 아래로, 사용자와 가까운 층부터 엔진 깊숙한 곳으로 내려갑니다.
대화 한 턴의 여정
사용자가 메시지를 입력하면 어떤 일이 벌어질까요?
시스템 프롬프트 조합
Claude API 호출
텍스트 + 도구 호출
Bash, Read, Edit...
핵심 포인트: Claude의 응답에 도구 호출이 포함되어 있으면, 도구를 실행하고 그 결과를 다시 Claude에게 보내는 루프가 반복됩니다. 하나의 사용자 메시지에 대해 여러 번의 API 호출이 일어날 수 있습니다.
Claude Code는 어떻게 "생각"하나요?
Claude Code의 행동은 시스템 프롬프트에 의해 결정됩니다. 이 프롬프트는 단일 텍스트가 아니라, 여러 조각이 동적으로 조합된 결과물입니다.
시스템 프롬프트의 7대 구성 요소
| 구성 요소 | 무엇을 정의하나요? | 바꿀 수 있나요? |
|---|---|---|
| 역할 소개 | "나는 Claude Code, 소프트웨어 엔지니어링을 돕는 에이전트" | ❌ 고정 |
| 보안 지침 | 악성 도구 거부, OWASP 취약점 방지 | ❌ 고정 |
| 작업 철학 | 코드 읽고 나서 수정, 과도한 추상화 금지, 최소주의 | ❌ 고정 |
| 도구 사용법 | Bash 대신 Read/Edit 도구 우선, 병렬 호출 권장 | ❌ 고정 |
| 환경 정보 | CWD, OS, 셸, Git 상태, 모델명 | 🔄 자동 감지 |
| CLAUDE.md | 프로젝트 규칙, 빌드 명령, 코드 스타일 | ✅ 사용자 편집 |
| 메모리 | 사용자 선호도, 피드백, 프로젝트 맥락 | ✅ 자동 학습 + 수동 |
사용자가 영향을 줄 수 있는 영역을 아는 것이 핵심입니다!
CLAUDE.md 파일과 메모리 시스템은 사용자가 직접 커스터마이즈할 수 있는 채널입니다. 여기에 프로젝트 규칙을 잘 적어두면 Claude의 행동 품질이 크게 향상됩니다.
Claude가 지키는 핵심 원칙 5가지
읽고 나서 수정하라
파일을 수정하기 전에 반드시 먼저 읽습니다. 보지 않은 코드에 대한 변경 제안은 금지됩니다.
요청한 것만 하라
요청 범위를 넘어서는 리팩토링, 기능 추가, 문서화를 하지 않습니다. 최소주의 원칙입니다.
위험한 작업은 확인하라
git push --force, 파일 삭제, PR 생성 등 비가역적 작업은 반드시 사용자에게 확인을 받습니다.
전용 도구를 우선하라
파일을 읽을 때 cat 대신 Read 도구, 검색할 때 grep 대신 Grep 도구를 사용합니다.
보안을 지켜라
명령 인젝션, XSS, SQL 인젝션 등 OWASP Top 10 취약점을 만들지 않도록 합니다.
도구(Tool) 시스템 완전 정복
도구는 Claude가 "손과 발"처럼 사용하는 기능 단위입니다. 각 도구는 고유한 프롬프트(사용 설명서)를 가지고 있어, Claude가 언제 어떤 도구를 써야 하는지 알 수 있습니다.
핵심 도구 카테고리
파일 작업
Read — 파일 읽기(이미지, PDF 포함)
Write — 파일 생성/덮어쓰기
Edit — diff 기반 부분 수정
Glob — 패턴으로 파일 검색
Grep — ripgrep 기반 텍스트 검색
셸 실행
Bash — 셸 명령 실행 (백그라운드 가능)
타임아웃 자동 관리, 도구로 대체 불가한 경우만 사용
에이전트 / 팀
Agent — 독립 서브에이전트 생성
SendMessage — 팀원에게 메시지
TodoWrite — 작업 목록 관리
웹 / 외부
WebSearch — 웹 검색 (출처 필수)
WebFetch — 웹 페이지 가져오기
MCPTool — 외부 MCP 서버 도구 호출
도구 선택의 우선순위
Claude는 다음 우선순위로 도구를 선택하도록 프롬프트됩니다:
파일 읽기: Read (cat, head, tail 대신)
파일 수정: Edit (sed, awk 대신)
파일 생성: Write (echo, heredoc 대신)
파일 검색: Glob (find, ls 대신)
내용 검색: Grep (grep, rg 대신)
기타: Bash (위 도구로 불가능한 경우에만)실전 팁: "이 파일을 cat으로 읽어줘"라고 하면 Claude는 cat 대신 Read 도구를 사용합니다. 이는 사용자 요청의 의도를 우선하는 것이지, 정확한 커맨드를 따르는 것이 아닙니다.
메모리 시스템: Claude가 기억하는 법
Claude Code는 두 가지 경로로 프로젝트와 사용자를 "기억"합니다.
경로 1: CLAUDE.md (프로젝트 규칙)
프로젝트 루트에 CLAUDE.md 파일을 두면, 모든 세션에서 자동으로 시스템 프롬프트에 포함됩니다.
| 파일 | 범위 | 용도 |
|---|---|---|
CLAUDE.md | 팀 공유 (소스 관리) | 빌드 명령, 코드 스타일, 프로젝트 구조 |
.claude/CLAUDE.md | 팀 공유 (소스 관리) | CLAUDE.md와 동일, 숨김 디렉토리 선호 시 |
.claude/rules/*.md | 팀 공유 (소스 관리) | 주제별 분리된 규칙 파일 |
CLAUDE.local.md | 개인 전용 (gitignored) | 개인 선호도, 로컬 환경 설정 |
~/.claude/CLAUDE.md | 전역 (모든 프로젝트) | 개인 범용 지침 |
# CLAUDE.md 예시
# CLAUDE.md
This file provides guidance to Claude Code when working in this repository.
## Build & Test
- `npm run build` — TypeScript 컴파일
- `npm test -- --run` — Vitest 테스트 (watch 모드 아님)
- `npm run lint` — ESLint 실행
## Code Style
- TypeScript strict 모드 사용
- `type` 선호 (`interface` 대신)
- 들여쓰기: 2칸 스페이스
## 중요 규칙
- PR 생성 전 반드시 lint + test 통과 확인
- 커밋 메시지는 Conventional Commits 형식CLAUDE.md의 내용은 시스템 프롬프트에서 최고 우선순위를 갖습니다.
프롬프트에 "이 지침은 기본 행동을 OVERRIDE하며, 정확히 따라야 합니다"라고 명시되어 있습니다. 따라서 CLAUDE.md에 적은 규칙은 매우 강력합니다.
경로 2: Auto Memory (AI가 학습하는 기억)
Claude Code는 대화 중 자동으로 중요한 정보를 메모리 파일로 저장합니다.
🧑 user 메모리
사용자의 역할, 전문 분야, 선호하는 작업 방식
예: "시니어 백엔드 개발자, Go 전문"
💬 feedback 메모리
"이렇게 해"/"하지 마" 형태의 행동 가이드
예: "테스트에서 DB 모킹하지 마"
📋 project 메모리
진행 중인 작업, 마감일, 기술적 결정
예: "3/15까지 인증 모듈 마이그레이션"
📎 reference 메모리
외부 시스템 위치 참조
예: "버그 트래킹은 Linear의 INGEST 프로젝트"
메모리 파일 위치: ~/.claude/projects/<프로젝트>/memory/
MEMORY.md 인덱스 파일(최대 200줄)이 매 세션에 로드되며, 개별 메모리 파일은 관련성이 높을 때만 Sonnet 모델이 선택하여 로드합니다.
슬래시 명령어 가이드
채팅 프롬프트에서 /를 입력하면 사용 가능한 명령어 목록이 표시됩니다. 90개 이상의 명령어가 있지만, 핵심만 먼저 익히세요.
초보자가 먼저 알아야 할 명령어 TOP 10
| 명령어 | 기능 | 난이도 |
|---|---|---|
/help | 도움말 표시 | 초급 |
/clear | 대화 초기화 (컨텍스트 리셋) | 초급 |
/compact | 대화 요약 (토큰 절약) | 초급 |
/context | 현재 컨텍스트 확인 | 초급 |
/cost | 현재 세션 비용 확인 | 초급 |
/init | CLAUDE.md 자동 생성 | 중급 |
/commit | 커밋 메시지 작성 + 커밋 | 중급 |
/review | 코드 리뷰 | 중급 |
/mcp | MCP 서버 관리 | 고급 |
/memory | 메모리 파일 조회/관리 | 중급 |
명령어 카테고리 전체 맵
🔧 설정
/config /theme /model /effort /permissions /vim
📂 Git
/commit /diff /branch /review /security-review
📊 세션
/session /resume /share /export /stats
🔌 확장
/mcp /skills /ide /install
심화 기능
기본에 익숙해졌다면, Claude Code의 고급 기능을 활용하여 생산성을 극대화하세요.
🏗️ Compact — 자동 컨텍스트 압축
대화가 길어지면 Claude Code가 자동으로 대화를 요약합니다. 9개 섹션(요청 의도, 기술 개념, 파일/코드, 에러, 진행 상황 등)으로 구조화하여 핵심 맥락을 보존합니다.
- 수동 트리거:
/compact - 자동 트리거: 컨텍스트 윈도우 한계 접근 시
- 사용자 정의: CLAUDE.md에 "Compact Instructions" 섹션 추가 가능
🧩 MCP (Model Context Protocol)
외부 도구나 서비스를 Claude Code에 연결하는 표준 프로토콜입니다.
# MCP 서버 추가 예시
claude mcp add my-server -- npx -y @my/mcp-server
# 지원 전송 방식
stdio | sse | http | ws | sdk👥 코디네이터 모드 (다중 작업자)
복잡한 작업을 여러 작업자(Worker)에게 분배하여 병렬 처리합니다.
조사
구현
검증
🌉 Bridge (원격 세션)
터미널의 Claude Code 세션을 claude.ai 웹에서 접속할 수 있는 양방향 연결입니다. 모바일에서도 진행 중인 작업을 모니터링하거나 지시를 내릴 수 있습니다.
📝 Plan 모드
복잡한 구현 전에 먼저 계획을 세우고 사용자 승인을 받는 모드입니다. Claude가 EnterPlanMode를 호출하면 읽기 전용으로 전환되어 파일 탐색만 가능하고, 계획 완료 후 ExitPlanMode로 승인을 요청합니다.
실전 팁: 더 잘 사용하는 법
CLAUDE.md를 반드시 만드세요
/init 명령어로 자동 생성하거나, 수동으로 프로젝트 루트에 만드세요. 빌드/테스트 명령, 코드 스타일 규칙, 중요한 아키텍처 결정을 적어두면 Claude의 정확도가 크게 향상됩니다.
피드백을 명확하게 주세요
"아니 그거 말고" 대신 "데이터베이스 모킹하지 말고 실제 DB로 테스트해"처럼 구체적으로 말하면, Claude가 feedback 메모리로 저장하여 다음 세션에서도 기억합니다.
컨텍스트를 관리하세요
긴 작업 후 /compact로 요약하고, 완전히 새 주제면 /clear로 리셋하세요. /context로 현재 얼마나 컨텍스트를 사용 중인지 확인할 수 있습니다.
위험한 작업은 직접 확인하세요
Claude가 git push, 파일 삭제, PR 생성을 하려고 하면 항상 확인 프롬프트가 뜹니다. 꼼꼼히 읽고 승인/거부하세요.
! 접두사로 직접 명령을 실행하세요
프롬프트에서 ! gcloud auth login처럼 !를 접두사로 치면 해당 명령이 현재 세션에서 실행되어 결과가 대화에 포함됩니다. 인터랙티브 로그인 등에 유용합니다.
@include로 CLAUDE.md를 깔끔하게 유지하세요
CLAUDE.md가 너무 길어지면 @docs/api-reference.md처럼 외부 파일을 참조할 수 있습니다. 실마리만 적고 상세 내용은 별도 파일로 분리하세요.
골든 룰: Claude Code는 요청한 것만 합니다. "인증 모듈 리팩토링해줘"라고 하면 인증 모듈만 수정합니다. 관련된 다른 코드 정리, 문서 업데이트, 테스트 추가 등은 별도로 요청하세요.
소스 코드 읽기 가이드
Claude Code 소스를 직접 분석하고 싶다면, 다음 순서를 추천합니다.
레벨 1: 큰 그림 이해 초급
main.tsx — 앱 시작점
Commander.js CLI 파싱, 인증 확인, 설정 로드, REPL 실행 흐름을 훑어보세요. 전체 부트스트랩 과정이 한 눈에 보입니다.
Tool.ts — 도구 타입 정의
Tool, ToolUseContext, ToolPermissionContext 타입이 앱 전체에서 사용됩니다. 이 인터페이스를 이해하면 도구가 어떻게 정의되고 실행되는지 알 수 있습니다.
tools.ts — 도구 레지스트리
어떤 도구가 등록되어 있는지, feature flag로 어떻게 게이트되는지 확인하세요.
레벨 2: 핵심 엔진 중급
QueryEngine.ts — 대화 루프
사용자 입력 → 시스템 프롬프트 조합 → API 호출 → 도구 실행 → 반복의 핵심 루프입니다. 가장 중요한 파일 중 하나입니다.
constants/prompts.ts — 시스템 프롬프트
getSystemPrompt() 함수에서 최종 시스템 프롬프트가 어떻게 조합되는지 확인하세요. Claude의 "성격"이 정의되는 곳입니다.
query.ts — API 호출
메시지 정규화, 스트리밍 처리, 에러 핸들링, 자동 compact 등 실제 API 통신 로직입니다.
레벨 3: 확장 이해 고급
services/mcp/ — MCP 클라이언트
외부 도구 서버와의 연결, 도구/리소스 동기화, OAuth 인증 흐름을 이해합니다.
coordinator/coordinatorMode.ts — 다중 에이전트
코디네이터 모드의 전체 시스템 프롬프트가 정의되어 있습니다. 작업자에게 프롬프트를 전달하는 5대 원칙을 읽어보세요.
bridge/ — 원격 세션
claude.ai와의 양방향 연결, JWT 인증, 폴링/재연결, 세션 관리 등 분산 시스템 아키텍처입니다.
함께 읽으면 좋은 문서:
• analyze.md — 전체 소스 코드 구조 분석 (19개 카테고리)
• prompts.md — 프롬프트 시스템 심층 분석 (12개 챕터)
용어 사전
Claude Code에서 자주 등장하는 핵심 용어를 정리했습니다.
| 용어 | 설명 |
|---|---|
| REPL | Read-Eval-Print Loop. 대화형 입력-실행-출력 반복 환경 |
| Tool | Claude가 호출할 수 있는 기능 단위 (Read, Bash, Agent 등) |
| Command | / 접두사 슬래시 명령어 (/commit, /help 등) |
| MCP | Model Context Protocol. 외부 도구/서비스 연결 표준 |
| Compact | 대화 요약. 긴 대화를 압축하여 컨텍스트 공간 확보 |
| CLAUDE.md | 프로젝트별 지시사항 파일. 시스템 프롬프트에 포함됨 |
| Agent | 독립 컨텍스트에서 작업하는 서브에이전트 |
| Worktree | Git worktree. 격리된 브랜치 환경에서 작업 |
| Bridge | 터미널 Claude Code ↔ claude.ai 웹 양방향 연결 |
| Ink | React 기반 터미널 UI 렌더링 라이브러리 (커스텀 포크) |
| Swarm | 다중 에이전트(팀원) 아키텍처 |
| Feature Flag | bun:bundle 기반 빌드타임 기능 토글 (Dead Code Elimination) |
| System Prompt | Claude에게 전달되는 행동 지침 전체 (Static + Dynamic) |
| Prompt Cache | 정적 시스템 프롬프트를 API 서버에 캐시하여 비용/지연 절감 |
| Plan Mode | 구현 전 계획을 세우고 승인받는 모드 |
| Coordinator | 다중 Worker를 오케스트레이션하는 모드 |
| Dream | 백그라운드 자율 작업 태스크 |