<!DOCTYPE html>
<html lang="ko">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Claude Code 완전 가이드 — 초보자를 위한 내부 구조 이해</title>
<style>
:root {
--primary: #d97706;
--primary-light: #fef3c7;
--primary-dark: #92400e;
--accent: #7c3aed;
--accent-light: #ede9fe;
--bg: #fafaf9;
--surface: #ffffff;
--text: #1c1917;
--text-secondary: #57534e;
--border: #e7e5e4;
--code-bg: #292524;
--code-text: #fafaf9;
--success: #16a34a;
--info: #2563eb;
--warning: #ea580c;
--danger: #dc2626;
}
* { margin: 0; padding: 0; box-sizing: border-box; }
body {
font-family: 'Pretendard', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
background: var(--bg);
color: var(--text);
line-height: 1.7;
font-size: 16px;
}
/* ── Hero ── */
.hero {
background: linear-gradient(135deg, #1c1917 0%, #292524 50%, #44403c 100%);
color: #fafaf9;
padding: 80px 24px 60px;
text-align: center;
position: relative;
overflow: hidden;
}
.hero::before {
content: '';
position: absolute;
top: -50%;
left: -50%;
width: 200%;
height: 200%;
background: radial-gradient(circle at 30% 70%, rgba(217,119,6,0.15) 0%, transparent 50%),
radial-gradient(circle at 70% 30%, rgba(124,58,237,0.1) 0%, transparent 50%);
animation: heroShift 20s ease-in-out infinite alternate;
}
@keyframes heroShift { to { transform: translate(5%, -3%); } }
.hero > * { position: relative; z-index: 1; }
.hero h1 { font-size: clamp(2rem, 5vw, 3.2rem); font-weight: 800; letter-spacing: -0.02em; margin-bottom: 12px; }
.hero h1 span { color: var(--primary); }
.hero p { font-size: 1.15rem; color: #a8a29e; max-width: 640px; margin: 0 auto; }
.hero .badge {
display: inline-block;
background: rgba(217,119,6,0.18);
color: var(--primary);
padding: 4px 14px;
border-radius: 999px;
font-size: 0.85rem;
font-weight: 600;
margin-bottom: 18px;
}
/* ── Layout ── */
.container { max-width: 960px; margin: 0 auto; padding: 0 24px; }
.toc-sticky {
position: sticky;
top: 0;
background: var(--surface);
border-bottom: 1px solid var(--border);
z-index: 100;
padding: 10px 0;
box-shadow: 0 1px 3px rgba(0,0,0,0.05);
}
.toc-inner {
max-width: 960px;
margin: 0 auto;
padding: 0 24px;
display: flex;
gap: 6px;
overflow-x: auto;
scrollbar-width: none;
}
.toc-inner::-webkit-scrollbar { display: none; }
.toc-inner a {
flex-shrink: 0;
font-size: 0.82rem;
padding: 5px 12px;
border-radius: 999px;
text-decoration: none;
color: var(--text-secondary);
background: var(--bg);
border: 1px solid var(--border);
transition: all 0.2s;
white-space: nowrap;
}
.toc-inner a:hover {
background: var(--primary-light);
color: var(--primary-dark);
border-color: var(--primary);
}
/* ── Sections ── */
section { padding: 56px 0; }
section + section { border-top: 1px solid var(--border); }
.section-label {
display: inline-block;
font-size: 0.75rem;
font-weight: 700;
text-transform: uppercase;
letter-spacing: 0.1em;
color: var(--primary);
background: var(--primary-light);
padding: 3px 10px;
border-radius: 4px;
margin-bottom: 10px;
}
h2 { font-size: 1.8rem; font-weight: 800; letter-spacing: -0.01em; margin-bottom: 8px; }
h3 { font-size: 1.25rem; font-weight: 700; margin: 32px 0 12px; color: var(--text); }
h4 { font-size: 1.05rem; font-weight: 600; margin: 20px 0 8px; }
p { margin-bottom: 14px; color: var(--text-secondary); }
p.lead { font-size: 1.08rem; color: var(--text); }
/* ── Cards ── */
.card-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(280px, 1fr)); gap: 16px; margin: 20px 0; }
.card {
background: var(--surface);
border: 1px solid var(--border);
border-radius: 12px;
padding: 24px;
transition: box-shadow 0.2s, transform 0.2s;
}
.card:hover { box-shadow: 0 4px 20px rgba(0,0,0,0.06); transform: translateY(-2px); }
.card .icon { font-size: 1.8rem; margin-bottom: 10px; }
.card h4 { margin-top: 0; }
.card p { font-size: 0.92rem; margin-bottom: 0; }
/* ── Numbered Steps ── */
.steps { counter-reset: step; margin: 20px 0; }
.step {
display: flex;
gap: 18px;
margin-bottom: 24px;
position: relative;
}
.step::before {
counter-increment: step;
content: counter(step);
flex-shrink: 0;
width: 36px;
height: 36px;
background: var(--primary);
color: #fff;
font-weight: 800;
font-size: 0.95rem;
display: flex;
align-items: center;
justify-content: center;
border-radius: 50%;
}
.step-content h4 { margin-top: 4px; }
/* ── Code Blocks ── */
pre {
background: var(--code-bg);
color: var(--code-text);
border-radius: 10px;
padding: 20px 24px;
overflow-x: auto;
font-size: 0.88rem;
line-height: 1.6;
margin: 16px 0;
}
code {
font-family: 'JetBrains Mono', 'Fira Code', 'SF Mono', monospace;
font-size: 0.88em;
}
:not(pre) > code {
background: #f5f5f4;
padding: 2px 7px;
border-radius: 4px;
color: var(--primary-dark);
}
/* ── Callout Boxes ── */
.callout {
border-radius: 10px;
padding: 18px 22px;
margin: 20px 0;
display: flex;
gap: 14px;
align-items: flex-start;
}
.callout .callout-icon { font-size: 1.4rem; flex-shrink: 0; margin-top: 2px; }
.callout p { margin: 0; font-size: 0.94rem; }
.callout-tip { background: #f0fdf4; border: 1px solid #bbf7d0; }
.callout-info { background: #eff6ff; border: 1px solid #bfdbfe; }
.callout-warn { background: #fff7ed; border: 1px solid #fed7aa; }
.callout-important { background: #fef2f2; border: 1px solid #fecaca; }
/* ── Tables ── */
table { width: 100%; border-collapse: collapse; margin: 16px 0; font-size: 0.92rem; }
th, td { padding: 10px 14px; text-align: left; border-bottom: 1px solid var(--border); }
th { font-weight: 700; background: #fafaf9; }
/* ── Diagram ── */
.diagram {
background: var(--surface);
border: 1px solid var(--border);
border-radius: 12px;
padding: 32px;
margin: 24px 0;
overflow-x: auto;
}
.diagram svg { display: block; margin: 0 auto; max-width: 100%; height: auto; }
/* ── Tabs ── */
.tabs { display: flex; gap: 0; margin-top: 24px; border-bottom: 2px solid var(--border); }
.tab {
padding: 8px 20px;
font-size: 0.9rem;
font-weight: 600;
cursor: pointer;
border-bottom: 2px solid transparent;
margin-bottom: -2px;
color: var(--text-secondary);
transition: all 0.2s;
background: none;
border-top: none; border-left: none; border-right: none;
}
.tab.active, .tab:hover { color: var(--primary); border-bottom-color: var(--primary); }
.tab-content { display: none; padding-top: 20px; }
.tab-content.active { display: block; }
/* ── Tag badges ── */
.tag {
display: inline-block;
font-size: 0.72rem;
font-weight: 700;
padding: 2px 8px;
border-radius: 4px;
text-transform: uppercase;
letter-spacing: 0.04em;
}
.tag-beginner { background: #dcfce7; color: #166534; }
.tag-intermediate { background: #fef9c3; color: #854d0e; }
.tag-advanced { background: #fee2e2; color: #991b1b; }
/* ── Footer ── */
footer {
background: #1c1917;
color: #a8a29e;
text-align: center;
padding: 40px 24px;
font-size: 0.88rem;
}
footer a { color: var(--primary); }
/* ── Responsive ── */
@media (max-width: 640px) {
.hero { padding: 48px 16px 40px; }
.card-grid { grid-template-columns: 1fr; }
pre { font-size: 0.82rem; padding: 14px 16px; }
}
/* ── Scroll behavior ── */
html { scroll-behavior: smooth; scroll-padding-top: 64px; }
/* Flow chart styling */
.flow-row { display: flex; justify-content: center; gap: 12px; flex-wrap: wrap; margin: 8px 0; }
.flow-box {
background: var(--surface);
border: 2px solid var(--border);
border-radius: 10px;
padding: 12px 20px;
font-size: 0.88rem;
font-weight: 600;
text-align: center;
min-width: 130px;
}
.flow-box.primary { border-color: var(--primary); background: var(--primary-light); color: var(--primary-dark); }
.flow-box.accent { border-color: var(--accent); background: var(--accent-light); color: #5b21b6; }
.flow-box.muted { border-color: #d6d3d1; background: #f5f5f4; color: var(--text-secondary); }
.flow-arrow { display: flex; justify-content: center; font-size: 1.4rem; color: #a8a29e; }
/* Layer diagram */
.layer-stack { display: flex; flex-direction: column; gap: 4px; margin: 20px 0; }
.layer {
border-radius: 8px;
padding: 14px 20px;
font-weight: 600;
font-size: 0.92rem;
display: flex;
justify-content: space-between;
align-items: center;
}
.layer .layer-desc { font-weight: 400; font-size: 0.82rem; opacity: 0.8; }
.layer-1 { background: #fef3c7; color: #92400e; }
.layer-2 { background: #e0e7ff; color: #3730a3; }
.layer-3 { background: #d1fae5; color: #065f46; }
.layer-4 { background: #fce7f3; color: #9d174d; }
.layer-5 { background: #f5f5f4; color: #44403c; }
</style>
</head>
<body>
<!-- ════════════════════════ HERO ════════════════════════ -->
<header class="hero">
<div class="badge">v2026.03 — 소스 코드 기반 분석</div>
<h1><span>Claude Code</span> 완전 가이드</h1>
<p>터미널 AI 코딩 어시스턴트의 내부 구조를 이해하고,<br>더 효과적으로 활용하기 위한 실전 안내서</p>
</header>
<!-- ════════════════════════ TOC ════════════════════════ -->
<nav class="toc-sticky">
<div class="toc-inner">
<a href="#what">이게 뭔가요?</a>
<a href="#mental-model">전체 그림</a>
<a href="#how-it-thinks">생각하는 법</a>
<a href="#tools">도구 활용</a>
<a href="#memory">메모리 시스템</a>
<a href="#commands">슬래시 명령어</a>
<a href="#advanced">심화 기능</a>
<a href="#tips">실전 팁</a>
<a href="#reading-order">코드 읽기 순서</a>
<a href="#glossary">용어 사전</a>
</div>
</nav>
<main class="container">
<!-- ════════════════════════ §1 ════════════════════════ -->
<section id="what">
<span class="section-label">Chapter 1</span>
<h2>Claude Code가 뭔가요?</h2>
<p class="lead">Claude Code는 Anthropic이 만든 <strong>터미널 기반 AI 코딩 어시스턴트</strong>입니다. 터미널에서 대화를 나누면서 파일을 읽고, 코드를 편집하고, 명령을 실행하고, 웹을 검색할 수 있습니다.</p>
<div class="card-grid">
<div class="card">
<div class="icon">💬</div>
<h4>대화형 REPL</h4>
<p>터미널에서 자연어로 요청하면 Claude가 도구를 사용하여 실제로 작업을 수행합니다.</p>
</div>
<div class="card">
<div class="icon">🔧</div>
<h4>40+ 내장 도구</h4>
<p>파일 읽기/쓰기, Bash 실행, 웹 검색, Git 작업 등 다양한 도구를 자동으로 선택합니다.</p>
</div>
<div class="card">
<div class="icon">🧠</div>
<h4>프로젝트 이해</h4>
<p>CLAUDE.md 파일과 메모리 시스템으로 프로젝트 규칙과 사용자 선호도를 기억합니다.</p>
</div>
<div class="card">
<div class="icon">🔌</div>
<h4>MCP로 확장</h4>
<p>Model Context Protocol을 통해 외부 도구와 서비스를 자유롭게 연결할 수 있습니다.</p>
</div>
</div>
<div class="callout callout-tip">
<span class="callout-icon">💡</span>
<div>
<p><strong>왜 내부 구조를 알아야 할까요?</strong><br>
Claude Code의 내부를 이해하면 — 어떤 프롬프트가 Claude에게 전달되는지, 도구가 어떻게 선택되는지, 메모리가 어떻게 작동하는지 — <em>의도를 더 정확하게 전달</em>할 수 있어 작업 효율이 크게 향상됩니다.</p>
</div>
</div>
</section>
<!-- ════════════════════════ §2 ════════════════════════ -->
<section id="mental-model">
<span class="section-label">Chapter 2</span>
<h2>전체 그림: 머릿속에 그려야 할 지도</h2>
<p class="lead">Claude Code는 크게 <strong>5개 층(Layer)</strong>으로 구성됩니다. 위에서 아래로, 사용자와 가까운 층부터 엔진 깊숙한 곳으로 내려갑니다.</p>
<div class="layer-stack">
<div class="layer layer-1">
<span>① 진입점 (Entrypoints)</span>
<span class="layer-desc">main.tsx → CLI 파싱, 인증, 설정 로드</span>
</div>
<div class="layer layer-2">
<span>② UI 계층 (React Ink)</span>
<span class="layer-desc">components/, screens/ → 터미널 화면 렌더링</span>
</div>
<div class="layer layer-3">
<span>③ 대화 엔진 (Core Engine)</span>
<span class="layer-desc">QueryEngine.ts ↔ query.ts → 대화 루프, API 호출</span>
</div>
<div class="layer layer-4">
<span>④ 도구·명령어 (Tools & Commands)</span>
<span class="layer-desc">tools/, commands/ → 40+ 도구, 90+ 슬래시 명령</span>
</div>
<div class="layer layer-5">
<span>⑤ 인프라 (Services & Utils)</span>
<span class="layer-desc">services/, utils/, bridge/ → API, MCP, 분석, 원격 연동</span>
</div>
</div>
<h3>대화 한 턴의 여정</h3>
<p>사용자가 메시지를 입력하면 어떤 일이 벌어질까요?</p>
<div class="diagram">
<div class="flow-row">
<div class="flow-box primary">사용자 입력</div>
</div>
<div class="flow-arrow">↓</div>
<div class="flow-row">
<div class="flow-box">REPL 화면</div>
<div class="flow-box">슬래시 명령 파서</div>
</div>
<div class="flow-arrow">↓</div>
<div class="flow-row">
<div class="flow-box accent">QueryEngine<br><small>시스템 프롬프트 조합</small></div>
</div>
<div class="flow-arrow">↓</div>
<div class="flow-row">
<div class="flow-box">query.ts<br><small>Claude API 호출</small></div>
</div>
<div class="flow-arrow">↓</div>
<div class="flow-row">
<div class="flow-box muted">Claude 응답<br><small>텍스트 + 도구 호출</small></div>
</div>
<div class="flow-arrow">↓</div>
<div class="flow-row">
<div class="flow-box">도구 실행<br><small>Bash, Read, Edit...</small></div>
<div class="flow-box">결과 → 다시 API</div>
</div>
<div class="flow-arrow">↓</div>
<div class="flow-row">
<div class="flow-box primary">최종 응답 표시</div>
</div>
</div>
<div class="callout callout-info">
<span class="callout-icon">🔄</span>
<div>
<p><strong>핵심 포인트:</strong> Claude의 응답에 도구 호출이 포함되어 있으면, 도구를 실행하고 그 결과를 다시 Claude에게 보내는 <em>루프</em>가 반복됩니다. 하나의 사용자 메시지에 대해 여러 번의 API 호출이 일어날 수 있습니다.</p>
</div>
</div>
</section>
<!-- ════════════════════════ §3 ════════════════════════ -->
<section id="how-it-thinks">
<span class="section-label">Chapter 3</span>
<h2>Claude Code는 어떻게 "생각"하나요?</h2>
<p class="lead">Claude Code의 행동은 <strong>시스템 프롬프트</strong>에 의해 결정됩니다. 이 프롬프트는 단일 텍스트가 아니라, 여러 조각이 동적으로 조합된 결과물입니다.</p>
<h3>시스템 프롬프트의 7대 구성 요소</h3>
<table>
<thead>
<tr><th>구성 요소</th><th>무엇을 정의하나요?</th><th>바꿀 수 있나요?</th></tr>
</thead>
<tbody>
<tr><td><strong>역할 소개</strong></td><td>"나는 Claude Code, 소프트웨어 엔지니어링을 돕는 에이전트"</td><td>❌ 고정</td></tr>
<tr><td><strong>보안 지침</strong></td><td>악성 도구 거부, OWASP 취약점 방지</td><td>❌ 고정</td></tr>
<tr><td><strong>작업 철학</strong></td><td>코드 읽고 나서 수정, 과도한 추상화 금지, 최소주의</td><td>❌ 고정</td></tr>
<tr><td><strong>도구 사용법</strong></td><td>Bash 대신 Read/Edit 도구 우선, 병렬 호출 권장</td><td>❌ 고정</td></tr>
<tr><td><strong>환경 정보</strong></td><td>CWD, OS, 셸, Git 상태, 모델명</td><td>🔄 자동 감지</td></tr>
<tr><td><strong>CLAUDE.md</strong></td><td>프로젝트 규칙, 빌드 명령, 코드 스타일</td><td>✅ 사용자 편집</td></tr>
<tr><td><strong>메모리</strong></td><td>사용자 선호도, 피드백, 프로젝트 맥락</td><td>✅ 자동 학습 + 수동</td></tr>
</tbody>
</table>
<div class="callout callout-warn">
<span class="callout-icon">⚡</span>
<div>
<p><strong>사용자가 영향을 줄 수 있는 영역을 아는 것이 핵심입니다!</strong><br>
CLAUDE.md 파일과 메모리 시스템은 사용자가 직접 커스터마이즈할 수 있는 채널입니다. 여기에 프로젝트 규칙을 잘 적어두면 Claude의 행동 품질이 크게 향상됩니다.</p>
</div>
</div>
<h3>Claude가 지키는 핵심 원칙 5가지</h3>
<div class="steps">
<div class="step">
<div class="step-content">
<h4>읽고 나서 수정하라</h4>
<p>파일을 수정하기 전에 반드시 먼저 읽습니다. 보지 않은 코드에 대한 변경 제안은 금지됩니다.</p>
</div>
</div>
<div class="step">
<div class="step-content">
<h4>요청한 것만 하라</h4>
<p>요청 범위를 넘어서는 리팩토링, 기능 추가, 문서화를 하지 않습니다. 최소주의 원칙입니다.</p>
</div>
</div>
<div class="step">
<div class="step-content">
<h4>위험한 작업은 확인하라</h4>
<p><code>git push --force</code>, 파일 삭제, PR 생성 등 비가역적 작업은 반드시 사용자에게 확인을 받습니다.</p>
</div>
</div>
<div class="step">
<div class="step-content">
<h4>전용 도구를 우선하라</h4>
<p>파일을 읽을 때 <code>cat</code> 대신 <code>Read</code> 도구, 검색할 때 <code>grep</code> 대신 <code>Grep</code> 도구를 사용합니다.</p>
</div>
</div>
<div class="step">
<div class="step-content">
<h4>보안을 지켜라</h4>
<p>명령 인젝션, XSS, SQL 인젝션 등 OWASP Top 10 취약점을 만들지 않도록 합니다.</p>
</div>
</div>
</div>
</section>
<!-- ════════════════════════ §4 ════════════════════════ -->
<section id="tools">
<span class="section-label">Chapter 4</span>
<h2>도구(Tool) 시스템 완전 정복</h2>
<p class="lead">도구는 Claude가 "손과 발"처럼 사용하는 기능 단위입니다. 각 도구는 고유한 프롬프트(사용 설명서)를 가지고 있어, Claude가 언제 어떤 도구를 써야 하는지 알 수 있습니다.</p>
<h3>핵심 도구 카테고리</h3>
<div class="card-grid">
<div class="card">
<div class="icon">📄</div>
<h4>파일 작업</h4>
<p><code>Read</code> — 파일 읽기(이미지, PDF 포함)<br>
<code>Write</code> — 파일 생성/덮어쓰기<br>
<code>Edit</code> — diff 기반 부분 수정<br>
<code>Glob</code> — 패턴으로 파일 검색<br>
<code>Grep</code> — ripgrep 기반 텍스트 검색</p>
</div>
<div class="card">
<div class="icon">⚡</div>
<h4>셸 실행</h4>
<p><code>Bash</code> — 셸 명령 실행 (백그라운드 가능)<br>
타임아웃 자동 관리, 도구로 대체 불가한 경우만 사용</p>
</div>
<div class="card">
<div class="icon">🤖</div>
<h4>에이전트 / 팀</h4>
<p><code>Agent</code> — 독립 서브에이전트 생성<br>
<code>SendMessage</code> — 팀원에게 메시지<br>
<code>TodoWrite</code> — 작업 목록 관리</p>
</div>
<div class="card">
<div class="icon">🌐</div>
<h4>웹 / 외부</h4>
<p><code>WebSearch</code> — 웹 검색 (출처 필수)<br>
<code>WebFetch</code> — 웹 페이지 가져오기<br>
<code>MCPTool</code> — 외부 MCP 서버 도구 호출</p>
</div>
</div>
<h3>도구 선택의 우선순위</h3>
<p>Claude는 다음 우선순위로 도구를 선택하도록 프롬프트됩니다:</p>
<pre><code>파일 읽기: Read (cat, head, tail 대신)
파일 수정: Edit (sed, awk 대신)
파일 생성: Write (echo, heredoc 대신)
파일 검색: Glob (find, ls 대신)
내용 검색: Grep (grep, rg 대신)
기타: Bash (위 도구로 불가능한 경우에만)</code></pre>
<div class="callout callout-tip">
<span class="callout-icon">💡</span>
<div>
<p><strong>실전 팁:</strong> "이 파일을 cat으로 읽어줘"라고 하면 Claude는 cat 대신 Read 도구를 사용합니다. 이는 사용자 요청의 <em>의도</em>를 우선하는 것이지, 정확한 커맨드를 따르는 것이 아닙니다.</p>
</div>
</div>
</section>
<!-- ════════════════════════ §5 ════════════════════════ -->
<section id="memory">
<span class="section-label">Chapter 5</span>
<h2>메모리 시스템: Claude가 기억하는 법</h2>
<p class="lead">Claude Code는 두 가지 경로로 프로젝트와 사용자를 "기억"합니다.</p>
<h3>경로 1: CLAUDE.md (프로젝트 규칙)</h3>
<p>프로젝트 루트에 <code>CLAUDE.md</code> 파일을 두면, 모든 세션에서 자동으로 시스템 프롬프트에 포함됩니다.</p>
<table>
<thead>
<tr><th>파일</th><th>범위</th><th>용도</th></tr>
</thead>
<tbody>
<tr><td><code>CLAUDE.md</code></td><td>팀 공유 (소스 관리)</td><td>빌드 명령, 코드 스타일, 프로젝트 구조</td></tr>
<tr><td><code>.claude/CLAUDE.md</code></td><td>팀 공유 (소스 관리)</td><td>CLAUDE.md와 동일, 숨김 디렉토리 선호 시</td></tr>
<tr><td><code>.claude/rules/*.md</code></td><td>팀 공유 (소스 관리)</td><td>주제별 분리된 규칙 파일</td></tr>
<tr><td><code>CLAUDE.local.md</code></td><td>개인 전용 (gitignored)</td><td>개인 선호도, 로컬 환경 설정</td></tr>
<tr><td><code>~/.claude/CLAUDE.md</code></td><td>전역 (모든 프로젝트)</td><td>개인 범용 지침</td></tr>
</tbody>
</table>
<pre><code># 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 형식</code></pre>
<div class="callout callout-important">
<span class="callout-icon">🔑</span>
<div>
<p><strong>CLAUDE.md의 내용은 시스템 프롬프트에서 최고 우선순위를 갖습니다.</strong><br>
프롬프트에 "이 지침은 기본 행동을 OVERRIDE하며, 정확히 따라야 합니다"라고 명시되어 있습니다. 따라서 CLAUDE.md에 적은 규칙은 매우 강력합니다.</p>
</div>
</div>
<h3>경로 2: Auto Memory (AI가 학습하는 기억)</h3>
<p>Claude Code는 대화 중 자동으로 중요한 정보를 메모리 파일로 저장합니다.</p>
<div class="card-grid">
<div class="card">
<h4>🧑 user 메모리</h4>
<p>사용자의 역할, 전문 분야, 선호하는 작업 방식<br><em>예: "시니어 백엔드 개발자, Go 전문"</em></p>
</div>
<div class="card">
<h4>💬 feedback 메모리</h4>
<p>"이렇게 해"/"하지 마" 형태의 행동 가이드<br><em>예: "테스트에서 DB 모킹하지 마"</em></p>
</div>
<div class="card">
<h4>📋 project 메모리</h4>
<p>진행 중인 작업, 마감일, 기술적 결정<br><em>예: "3/15까지 인증 모듈 마이그레이션"</em></p>
</div>
<div class="card">
<h4>📎 reference 메모리</h4>
<p>외부 시스템 위치 참조<br><em>예: "버그 트래킹은 Linear의 INGEST 프로젝트"</em></p>
</div>
</div>
<div class="callout callout-info">
<span class="callout-icon">📁</span>
<div>
<p><strong>메모리 파일 위치:</strong> <code>~/.claude/projects/<프로젝트>/memory/</code><br>
MEMORY.md 인덱스 파일(최대 200줄)이 매 세션에 로드되며, 개별 메모리 파일은 관련성이 높을 때만 Sonnet 모델이 선택하여 로드합니다.</p>
</div>
</div>
</section>
<!-- ════════════════════════ §6 ════════════════════════ -->
<section id="commands">
<span class="section-label">Chapter 6</span>
<h2>슬래시 명령어 가이드</h2>
<p class="lead">채팅 프롬프트에서 <code>/</code>를 입력하면 사용 가능한 명령어 목록이 표시됩니다. 90개 이상의 명령어가 있지만, 핵심만 먼저 익히세요.</p>
<h3>초보자가 먼저 알아야 할 명령어 TOP 10</h3>
<table>
<thead>
<tr><th>명령어</th><th>기능</th><th>난이도</th></tr>
</thead>
<tbody>
<tr><td><code>/help</code></td><td>도움말 표시</td><td><span class="tag tag-beginner">초급</span></td></tr>
<tr><td><code>/clear</code></td><td>대화 초기화 (컨텍스트 리셋)</td><td><span class="tag tag-beginner">초급</span></td></tr>
<tr><td><code>/compact</code></td><td>대화 요약 (토큰 절약)</td><td><span class="tag tag-beginner">초급</span></td></tr>
<tr><td><code>/context</code></td><td>현재 컨텍스트 확인</td><td><span class="tag tag-beginner">초급</span></td></tr>
<tr><td><code>/cost</code></td><td>현재 세션 비용 확인</td><td><span class="tag tag-beginner">초급</span></td></tr>
<tr><td><code>/init</code></td><td>CLAUDE.md 자동 생성</td><td><span class="tag tag-intermediate">중급</span></td></tr>
<tr><td><code>/commit</code></td><td>커밋 메시지 작성 + 커밋</td><td><span class="tag tag-intermediate">중급</span></td></tr>
<tr><td><code>/review</code></td><td>코드 리뷰</td><td><span class="tag tag-intermediate">중급</span></td></tr>
<tr><td><code>/mcp</code></td><td>MCP 서버 관리</td><td><span class="tag tag-advanced">고급</span></td></tr>
<tr><td><code>/memory</code></td><td>메모리 파일 조회/관리</td><td><span class="tag tag-intermediate">중급</span></td></tr>
</tbody>
</table>
<h3>명령어 카테고리 전체 맵</h3>
<div class="card-grid">
<div class="card">
<h4>🔧 설정</h4>
<p><code>/config</code> <code>/theme</code> <code>/model</code> <code>/effort</code> <code>/permissions</code> <code>/vim</code></p>
</div>
<div class="card">
<h4>📂 Git</h4>
<p><code>/commit</code> <code>/diff</code> <code>/branch</code> <code>/review</code> <code>/security-review</code></p>
</div>
<div class="card">
<h4>📊 세션</h4>
<p><code>/session</code> <code>/resume</code> <code>/share</code> <code>/export</code> <code>/stats</code></p>
</div>
<div class="card">
<h4>🔌 확장</h4>
<p><code>/mcp</code> <code>/skills</code> <code>/ide</code> <code>/install</code></p>
</div>
</div>
</section>
<!-- ════════════════════════ §7 ════════════════════════ -->
<section id="advanced">
<span class="section-label">Chapter 7</span>
<h2>심화 기능</h2>
<p class="lead">기본에 익숙해졌다면, Claude Code의 고급 기능을 활용하여 생산성을 극대화하세요.</p>
<h3>🏗️ Compact — 자동 컨텍스트 압축</h3>
<p>대화가 길어지면 Claude Code가 자동으로 대화를 요약합니다. 9개 섹션(요청 의도, 기술 개념, 파일/코드, 에러, 진행 상황 등)으로 구조화하여 핵심 맥락을 보존합니다.</p>
<ul style="color:var(--text-secondary); margin-bottom:14px;">
<li>수동 트리거: <code>/compact</code></li>
<li>자동 트리거: 컨텍스트 윈도우 한계 접근 시</li>
<li>사용자 정의: CLAUDE.md에 "Compact Instructions" 섹션 추가 가능</li>
</ul>
<h3>🧩 MCP (Model Context Protocol)</h3>
<p>외부 도구나 서비스를 Claude Code에 연결하는 표준 프로토콜입니다.</p>
<pre><code># MCP 서버 추가 예시
claude mcp add my-server -- npx -y @my/mcp-server
# 지원 전송 방식
stdio | sse | http | ws | sdk</code></pre>
<h3>👥 코디네이터 모드 (다중 작업자)</h3>
<p>복잡한 작업을 여러 작업자(Worker)에게 분배하여 병렬 처리합니다.</p>
<div class="diagram">
<div class="flow-row">
<div class="flow-box primary">코디네이터 (당신)</div>
</div>
<div class="flow-arrow">↓ 작업 분배</div>
<div class="flow-row">
<div class="flow-box muted">Worker 1<br><small>조사</small></div>
<div class="flow-box muted">Worker 2<br><small>구현</small></div>
<div class="flow-box muted">Worker 3<br><small>검증</small></div>
</div>
<div class="flow-arrow">↑ 결과 보고</div>
<div class="flow-row">
<div class="flow-box accent">코디네이터가 종합 → 사용자에게 보고</div>
</div>
</div>
<h3>🌉 Bridge (원격 세션)</h3>
<p>터미널의 Claude Code 세션을 <code>claude.ai</code> 웹에서 접속할 수 있는 양방향 연결입니다. 모바일에서도 진행 중인 작업을 모니터링하거나 지시를 내릴 수 있습니다.</p>
<h3>📝 Plan 모드</h3>
<p>복잡한 구현 전에 먼저 계획을 세우고 사용자 승인을 받는 모드입니다. Claude가 <code>EnterPlanMode</code>를 호출하면 읽기 전용으로 전환되어 파일 탐색만 가능하고, 계획 완료 후 <code>ExitPlanMode</code>로 승인을 요청합니다.</p>
</section>
<!-- ════════════════════════ §8 ════════════════════════ -->
<section id="tips">
<span class="section-label">Chapter 8</span>
<h2>실전 팁: 더 잘 사용하는 법</h2>
<div class="steps">
<div class="step">
<div class="step-content">
<h4>CLAUDE.md를 반드시 만드세요</h4>
<p><code>/init</code> 명령어로 자동 생성하거나, 수동으로 프로젝트 루트에 만드세요. 빌드/테스트 명령, 코드 스타일 규칙, 중요한 아키텍처 결정을 적어두면 Claude의 정확도가 크게 향상됩니다.</p>
</div>
</div>
<div class="step">
<div class="step-content">
<h4>피드백을 명확하게 주세요</h4>
<p>"아니 그거 말고" 대신 "데이터베이스 모킹하지 말고 실제 DB로 테스트해"처럼 구체적으로 말하면, Claude가 feedback 메모리로 저장하여 다음 세션에서도 기억합니다.</p>
</div>
</div>
<div class="step">
<div class="step-content">
<h4>컨텍스트를 관리하세요</h4>
<p>긴 작업 후 <code>/compact</code>로 요약하고, 완전히 새 주제면 <code>/clear</code>로 리셋하세요. <code>/context</code>로 현재 얼마나 컨텍스트를 사용 중인지 확인할 수 있습니다.</p>
</div>
</div>
<div class="step">
<div class="step-content">
<h4>위험한 작업은 직접 확인하세요</h4>
<p>Claude가 git push, 파일 삭제, PR 생성을 하려고 하면 항상 확인 프롬프트가 뜹니다. 꼼꼼히 읽고 승인/거부하세요.</p>
</div>
</div>
<div class="step">
<div class="step-content">
<h4><code>!</code> 접두사로 직접 명령을 실행하세요</h4>
<p>프롬프트에서 <code>! gcloud auth login</code>처럼 <code>!</code>를 접두사로 치면 해당 명령이 현재 세션에서 실행되어 결과가 대화에 포함됩니다. 인터랙티브 로그인 등에 유용합니다.</p>
</div>
</div>
<div class="step">
<div class="step-content">
<h4>@include로 CLAUDE.md를 깔끔하게 유지하세요</h4>
<p>CLAUDE.md가 너무 길어지면 <code>@docs/api-reference.md</code>처럼 외부 파일을 참조할 수 있습니다. 실마리만 적고 상세 내용은 별도 파일로 분리하세요.</p>
</div>
</div>
</div>
<div class="callout callout-tip">
<span class="callout-icon">🎯</span>
<div>
<p><strong>골든 룰:</strong> Claude Code는 요청한 것만 합니다. "인증 모듈 리팩토링해줘"라고 하면 인증 모듈만 수정합니다. 관련된 다른 코드 정리, 문서 업데이트, 테스트 추가 등은 <em>별도로 요청</em>하세요.</p>
</div>
</div>
</section>
<!-- ════════════════════════ §9 ════════════════════════ -->
<section id="reading-order">
<span class="section-label">Chapter 9</span>
<h2>소스 코드 읽기 가이드</h2>
<p class="lead">Claude Code 소스를 직접 분석하고 싶다면, 다음 순서를 추천합니다.</p>
<h3>레벨 1: 큰 그림 이해 <span class="tag tag-beginner">초급</span></h3>
<div class="steps">
<div class="step">
<div class="step-content">
<h4>main.tsx — 앱 시작점</h4>
<p>Commander.js CLI 파싱, 인증 확인, 설정 로드, REPL 실행 흐름을 훑어보세요. 전체 부트스트랩 과정이 한 눈에 보입니다.</p>
</div>
</div>
<div class="step">
<div class="step-content">
<h4>Tool.ts — 도구 타입 정의</h4>
<p><code>Tool</code>, <code>ToolUseContext</code>, <code>ToolPermissionContext</code> 타입이 앱 전체에서 사용됩니다. 이 인터페이스를 이해하면 도구가 어떻게 정의되고 실행되는지 알 수 있습니다.</p>
</div>
</div>
<div class="step">
<div class="step-content">
<h4>tools.ts — 도구 레지스트리</h4>
<p>어떤 도구가 등록되어 있는지, feature flag로 어떻게 게이트되는지 확인하세요.</p>
</div>
</div>
</div>
<h3>레벨 2: 핵심 엔진 <span class="tag tag-intermediate">중급</span></h3>
<div class="steps">
<div class="step">
<div class="step-content">
<h4>QueryEngine.ts — 대화 루프</h4>
<p>사용자 입력 → 시스템 프롬프트 조합 → API 호출 → 도구 실행 → 반복의 핵심 루프입니다. 가장 중요한 파일 중 하나입니다.</p>
</div>
</div>
<div class="step">
<div class="step-content">
<h4>constants/prompts.ts — 시스템 프롬프트</h4>
<p><code>getSystemPrompt()</code> 함수에서 최종 시스템 프롬프트가 어떻게 조합되는지 확인하세요. Claude의 "성격"이 정의되는 곳입니다.</p>
</div>
</div>
<div class="step">
<div class="step-content">
<h4>query.ts — API 호출</h4>
<p>메시지 정규화, 스트리밍 처리, 에러 핸들링, 자동 compact 등 실제 API 통신 로직입니다.</p>
</div>
</div>
</div>
<h3>레벨 3: 확장 이해 <span class="tag tag-advanced">고급</span></h3>
<div class="steps">
<div class="step">
<div class="step-content">
<h4>services/mcp/ — MCP 클라이언트</h4>
<p>외부 도구 서버와의 연결, 도구/리소스 동기화, OAuth 인증 흐름을 이해합니다.</p>
</div>
</div>
<div class="step">
<div class="step-content">
<h4>coordinator/coordinatorMode.ts — 다중 에이전트</h4>
<p>코디네이터 모드의 전체 시스템 프롬프트가 정의되어 있습니다. 작업자에게 프롬프트를 전달하는 5대 원칙을 읽어보세요.</p>
</div>
</div>
<div class="step">
<div class="step-content">
<h4>bridge/ — 원격 세션</h4>
<p>claude.ai와의 양방향 연결, JWT 인증, 폴링/재연결, 세션 관리 등 분산 시스템 아키텍처입니다.</p>
</div>
</div>
</div>
<div class="callout callout-info">
<span class="callout-icon">📚</span>
<div>
<p><strong>함께 읽으면 좋은 문서:</strong><br>
• <a href="analyze.md" style="color:var(--info)">analyze.md</a> — 전체 소스 코드 구조 분석 (19개 카테고리)<br>
• <a href="prompts.md" style="color:var(--info)">prompts.md</a> — 프롬프트 시스템 심층 분석 (12개 챕터)</p>
</div>
</div>
</section>
<!-- ════════════════════════ §10 ════════════════════════ -->
<section id="glossary">
<span class="section-label">Reference</span>
<h2>용어 사전</h2>
<p class="lead">Claude Code에서 자주 등장하는 핵심 용어를 정리했습니다.</p>
<table>
<thead>
<tr><th>용어</th><th>설명</th></tr>
</thead>
<tbody>
<tr><td><strong>REPL</strong></td><td>Read-Eval-Print Loop. 대화형 입력-실행-출력 반복 환경</td></tr>
<tr><td><strong>Tool</strong></td><td>Claude가 호출할 수 있는 기능 단위 (Read, Bash, Agent 등)</td></tr>
<tr><td><strong>Command</strong></td><td><code>/</code> 접두사 슬래시 명령어 (/commit, /help 등)</td></tr>
<tr><td><strong>MCP</strong></td><td>Model Context Protocol. 외부 도구/서비스 연결 표준</td></tr>
<tr><td><strong>Compact</strong></td><td>대화 요약. 긴 대화를 압축하여 컨텍스트 공간 확보</td></tr>
<tr><td><strong>CLAUDE.md</strong></td><td>프로젝트별 지시사항 파일. 시스템 프롬프트에 포함됨</td></tr>
<tr><td><strong>Agent</strong></td><td>독립 컨텍스트에서 작업하는 서브에이전트</td></tr>
<tr><td><strong>Worktree</strong></td><td>Git worktree. 격리된 브랜치 환경에서 작업</td></tr>
<tr><td><strong>Bridge</strong></td><td>터미널 Claude Code ↔ claude.ai 웹 양방향 연결</td></tr>
<tr><td><strong>Ink</strong></td><td>React 기반 터미널 UI 렌더링 라이브러리 (커스텀 포크)</td></tr>
<tr><td><strong>Swarm</strong></td><td>다중 에이전트(팀원) 아키텍처</td></tr>
<tr><td><strong>Feature Flag</strong></td><td><code>bun:bundle</code> 기반 빌드타임 기능 토글 (Dead Code Elimination)</td></tr>
<tr><td><strong>System Prompt</strong></td><td>Claude에게 전달되는 행동 지침 전체 (Static + Dynamic)</td></tr>
<tr><td><strong>Prompt Cache</strong></td><td>정적 시스템 프롬프트를 API 서버에 캐시하여 비용/지연 절감</td></tr>
<tr><td><strong>Plan Mode</strong></td><td>구현 전 계획을 세우고 승인받는 모드</td></tr>
<tr><td><strong>Coordinator</strong></td><td>다중 Worker를 오케스트레이션하는 모드</td></tr>
<tr><td><strong>Dream</strong></td><td>백그라운드 자율 작업 태스크</td></tr>
</tbody>
</table>
</section>
</main>
<!-- ════════════════════════ FOOTER ════════════════════════ -->
<footer>
<p>이 문서는 Claude Code <code>src/</code> 소스 코드를 직접 분석하여 작성되었습니다.</p>
<p style="margin-top:8px;">
<a href="analyze.md">소스 코드 분석</a> · <a href="prompts.md">프롬프트 분석</a>
</p>
<p style="margin-top:12px; font-size:0.8rem;">2026-03-31 · 분석 기준 버전</p>
</footer>
<!-- ────── Minimal Tab Script ────── -->
<script>
document.querySelectorAll('.tabs').forEach(tabBar => {
const contents = tabBar.parentElement.querySelectorAll('.tab-content');
tabBar.querySelectorAll('.tab').forEach((tab, i) => {
tab.addEventListener('click', () => {
tabBar.querySelectorAll('.tab').forEach(t => t.classList.remove('active'));
contents.forEach(c => c.classList.remove('active'));
tab.classList.add('active');
contents[i].classList.add('active');
});
});
});
</script>
</body>
</html>
|