Claude Code 가이드
질문 검색만 쓰는 것을 넘어서
ARCHITECTURE OVERVIEW
Claude Code는 단순 챗봇이 아니라, 도구를 직접 사용하는 에이전트다
Claude Code System
Input
Core
External
기본 도구 (Built-in Tools)
Claude가 직접 사용하는 도구들
코드, 이미지, PDF, 노트북 모두 읽을 수 있다. 파일 경로만 주면 된다.
“auth.py 파일 읽어봐”
기존 파일의 특정 부분만 정확히 교체한다. 전체를 다시 쓰지 않고 diff만 적용.
“login 함수에서 null 체크 추가해줘”
새 파일을 만들거나 기존 파일을 완전히 덮어쓴다.
“utils/format.ts 파일 만들어줘”
npm, git, curl 등 모든 쉘 명령을 실행할 수 있다.
“테스트 돌려봐 / 빌드해봐”
파일명 패턴으로 프로젝트 내 파일을 찾는다. find 대신 사용.
“**/*.tsx 파일 찾아봐”
파일 내용에서 정규식 패턴을 검색한다. grep/rg 대신 사용.
“useAuth 쓰는 곳 전부 찾아봐”
실시간 웹 검색으로 최신 정보를 가져온다.
“React 19 새 기능 검색해봐”
특정 URL의 내용을 가져와서 분석한다.
“이 문서 페이지 내용 요약해줘”
서브에이전트 (Sub-agents)
복잡한 작업을 분리된 컨텍스트에서 병렬 처리
서브에이전트는 독립된 AI 인스턴스다. 메인 대화의 컨텍스트를 오염시키지 않고 복잡한 작업을 위임할 수 있다. 결과만 메인으로 돌아온다.
도구: Read-only
코드베이스 탐색, 파일 검색, 구조 파악
“이 프로젝트 구조 파악해봐” / “auth 관련 파일 찾아봐”
도구: Read-only
구현 전략 설계, 아키텍처 분석
“리팩토링 계획 세워봐” / “이 기능 어떻게 구현할지 계획해”
도구: 모든 도구
멀티스텝 작업, 코드 수정 + 테스트
“이 버그 찾아서 고쳐봐” / “테스트 돌리고 결과 알려줘”
도구: 설정 가능
팀 맞춤 워크플로우
.claude/agents/ 폴더에 SKILL.md로 정의
커스텀 에이전트 만들기
파일 위치
.claude/agents/code-reviewer.md # 프로젝트용 (팀 공유) ~/.claude/agents/my-agent.md # 개인용 (모든 프로젝트)
예시: 코드 리뷰 에이전트
--- name: code-reviewer description: 코드 품질, 보안, 성능을 리뷰한다. 코드 변경 후 자동 실행. tools: Read, Glob, Grep model: sonnet maxTurns: 10 --- 당신은 시니어 코드 리뷰어입니다. 변경된 코드를 분석하고, 구체적인 개선점을 제시하세요. 보안 취약점, 성능 이슈, 코드 스타일을 중점적으로 봅니다.
MCP (Model Context Protocol)
외부 도구와 API를 Claude에 연결하는 표준
MCP는 Claude가 외부 시스템과 소통하는 플러그인 시스템이다. GitHub, Sentry, DB, 브라우저 등을 Claude의 도구로 추가할 수 있다.
🐙
GitHub
PR 생성, 이슈 관리, 코드 검색
claude mcp add --transport http github https://api.githubcopilot.com/mcp/
🐛
Sentry
에러 모니터링, 이슈 추적
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
🌐
Playwright
브라우저 자동화, E2E 테스트
claude mcp add --transport stdio playwright -- npx @playwright/mcp@latest
MCP 설정 방법
# 1. 리모트 서버 추가 (HTTP)
claude mcp add --transport http 이름 URL
# 2. 로컬 서버 추가 (stdio)
claude mcp add --transport stdio 이름 -- 명령어
# 3. 프로젝트 공유용 (.mcp.json)
{
"mcpServers": {
"github": {
"type": "http",
"url": "https://api.githubcopilot.com/mcp/"
}
}
}MCP 관리 명령어
claude mcp list # 서버 목록 claude mcp get 이름 # 서버 상세 claude mcp remove 이름 # 서버 제거 # Claude Code 안에서 /mcp # 대화형 MCP 관리 @server:resource # 리소스 참조
설정 범위: Local (이 프로젝트) > Project (.mcp.json, 팀 공유) > User (~/.claude.json)
스킬 (Skills / Slash Commands)
재사용 가능한 커스텀 명령어
스킬은 마크다운 파일 하나로 만드는 커스텀 명령어다./스킬이름으로 실행하거나, Claude가 자동으로 판단해서 실행한다.
변경된 코드의 품질, 재사용성 리뷰
대규모 변경을 병렬로 처리
변경사항 커밋
커스텀 스킬 만들기
# 파일 위치 .claude/skills/deploy/SKILL.md # 프로젝트용 ~/.claude/skills/my-cmd/SKILL.md # 개인용 # SKILL.md 예시 --- name: deploy description: 프로덕션 배포 context: fork allowed-tools: Bash --- 1. 테스트 스위트 실행 2. 빌드 3. 배포 스크립트 실행 4. 배포 확인
스킬 설정 옵션
인자 사용: $ARGUMENTS, $0, $1 로 접근 가능
훅 (Hooks)
특정 시점에 자동으로 실행되는 자동화
훅은 Claude가 특정 행동을 할 때 자동으로 트리거되는 스크립트다. 코드 포맷팅, 파일 보호, 알림, 로깅 등을 자동화할 수 있다.
| 이벤트 | 언제 | 활용 |
|---|---|---|
| PreToolUse | 도구 실행 전 | 파일 보호, 명령 검증 |
| PostToolUse | 도구 실행 후 | 자동 포맷팅, 로깅 |
| UserPromptSubmit | 프롬프트 전송 시 | 컨텍스트 주입 |
| Stop | 응답 완료 시 | 결과 검증 |
| SessionStart | 세션 시작 | 환경 셋업 |
| Notification | 알림 필요 시 | 데스크톱 알림 |
예시: 자동 코드 포맷팅
// .claude/settings.json
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "npx prettier --write $(jq -r '.tool_input.file_path')"
}
]
}
]
}
}예시: 데스크톱 알림
// .claude/settings.json
{
"hooks": {
"Notification": [
{
"hooks": [
{
"type": "command",
"command": "osascript -e 'display notification \"Claude Code 확인 필요\"'"
}
]
}
]
}
}훅 타입: command (쉘), http (웹훅), prompt (경량 LLM), agent (도구 사용 LLM)
CLAUDE.md
프로젝트 규칙과 컨텍스트를 Claude에게 전달
CLAUDE.md는 매 세션 시작 시 자동으로 로드되는 지시 파일이다. 코딩 컨벤션, 프로젝트 구조, 빌드 명령 등을 적어두면 Claude가 매번 알아서 따른다.
| 파일 | 위치 | 범위 | 공유 |
|---|---|---|---|
| CLAUDE.md | 프로젝트 루트 | 팀 전체 | Git으로 공유 |
| CLAUDE.local.md | 프로젝트 루트 | 나만 | .gitignore |
| ~/.claude/CLAUDE.md | 홈 디렉토리 | 내 모든 프로젝트 | 개인 |
| .claude/rules/*.md | 프로젝트 내 | 경로별 규칙 | Git으로 공유 |
CLAUDE.md 템플릿
# 프로젝트 개요 Next.js 14 기반 포트폴리오 사이트 ## 코딩 컨벤션 - TypeScript strict mode - 2스페이스 인덴트 - 컴포넌트는 화살표 함수 ## 빌드 & 테스트 - npm run dev # 개발 서버 - npm run build # 프로덕션 빌드 - npm run lint # 린트 ## 프로젝트 구조 - app/ # Next.js App Router 페이지 - components/ # 공용 컴포넌트 - lib/ # 유틸리티, API 클라이언트 ## 중요 규칙 - 커밋 전 반드시 빌드 확인 - 환경변수는 .env.local에만
메모리 (Auto Memory)
세션을 넘어서 기억하는 시스템
CLAUDE.md vs Memory
CLAUDE.md = 내가 쓰는 규칙
“이 프로젝트는 이렇게 해”라고 직접 작성
Memory = Claude가 쓰는 메모
작업하면서 배운 패턴, 디버깅 인사이트를 자동 저장
메모리 사용법
“이거 기억해” — Claude가 메모리에 저장
“항상 bun 써” — 다음 세션부터 적용
“잊어” — 해당 메모리 삭제
위치: ~/.claude/projects/<id>/memory/MEMORY.md
매 세션 시작 시 첫 200줄 자동 로드
컨텍스트 윈도우 (Context Window)
Claude가 한번에 볼 수 있는 범위
컨텍스트 윈도우는 Claude가 한 대화에서 동시에 기억할 수 있는 총량이다. 사람의 단기 기억과 비슷하다. 대화가 길어지면 이전 내용을 잊기 시작한다.
CONTEXT WINDOW STRUCTURE
Context Window · 200k tokens
context
├─ System prompt ··· 1.8%
├─ System tools ··· 8.1%
├─ MCP tools ····· 0.1%
├─ Memory files ··· 0.5%
├─ Skills ········· 0.3%
├─ Messages ······ 0.3%
├─ Free space ···· 72.4%
└─ Autocompact buffer · 16.5%
System prompt
System tools
MCP tools
Memory files
Skills
Messages
Free space
Autocompact
System prompt
· Claude의 기본 성격, 톤, 안전 규칙
· 도구 사용 우선순위와 작업 지침
· 변경 불가 — Anthropic이 관리
System tools
· Read, Edit, Write, Bash, Glob, Grep 등
· 각 도구의 JSON 스키마와 사용 설명
· 가장 큰 고정 영역 중 하나
MCP tools
· MCP 서버가 등록한 외부 도구 정의
· 서버가 많을수록 이 영역이 커짐
· 필요 없는 MCP는 제거하면 절약
Memory files
· CLAUDE.md (프로젝트 규칙) 자동 로드
· MEMORY.md (자동 메모리) 첫 200줄
· 세션 시작 시 한번 주입
Skills
· 등록된 스킬의 이름, 설명, 트리거 조건
· Claude가 자동으로 스킬을 선택하는 데 사용
· 스킬이 많으면 이 영역도 커짐
Messages
· 대화가 진행될수록 계속 커지는 영역
· 유저 프롬프트 + Claude 응답 + 도구 결과
· 컨텍스트 소비의 주범 — /compact로 관리
Free space
· 아직 사용되지 않은 빈 공간
· Claude의 응답 생성에 필요
· 이 공간이 줄면 자동 압축 발동
Autocompact buffer
· 자동 압축을 위해 예약된 버퍼
· Free space가 바닥나면 이 영역 사용
· 오래된 대화를 요약해서 압축
컨텍스트가 꽉 차면?
1. Autocompact buffer가 오래된 대화를 자동 요약·압축한다
2. 압축 후에도 최근 대화와 중요 정보는 유지된다
3. 수동으로 /compact를 실행하면 즉시 압축할 수 있다
4. /context로 현재 사용량을 시각적으로 확인 가능
컨텍스트를 아끼는 방법
/compact — 대화를 요약해서 공간 확보
/context — 현재 컨텍스트 사용량 확인
서브에이전트 활용 — 장황한 작업은 위임해서 메인 컨텍스트 보호
새 세션 — 주제가 바뀌면 새 대화 시작
컨텍스트 vs 메모리
컨텍스트 = 단기 기억
현재 대화에서만 유효. 세션 끝나면 사라짐. 용량 제한 있음.
메모리 = 장기 기억
세션 간 유지. MEMORY.md에 저장. 다음 세션에도 로드됨.
CLAUDE.md = 교범
매번 로드되는 고정 규칙. 프로젝트 컨벤션, 빌드 명령 등.
설정 & 권한 (Settings)
Claude의 행동 범위를 제어
권한 모드
권한 규칙 설정
// .claude/settings.json
{
"permissions": {
"allow": [
"Bash(npm run *)",
"Bash(git *)",
"Read"
],
"deny": [
"Read(.env)",
"Bash(rm *)",
"Bash(sudo *)"
]
}
}Cursor / VS Code 통합
에디터에서 바로 사용하는 방법
키보드 단축키
유용한 기능
@ 파일 참조 — 프롬프트에 @입력 후 파일명 검색
라인 범위 — @file.ts#5-10 으로 특정 줄 참조
세션 이어하기 — 상단 드롭다운에서 이전 세션 선택
/mcp — MCP 서버 관리
/compact — 컨텍스트 정리
/memory — 메모리 관리
Agent SDK
Claude Code를 프로그래밍 API로 사용
Claude Code의 모든 기능을 코드에서 호출할 수 있다
TypeScript
import { query } from
"@anthropic-ai/claude-agent-sdk";
for await (const msg of query({
prompt: "auth.py 버그 찾아서 고쳐",
options: {
allowedTools: ["Read", "Edit", "Bash"]
}
})) {
if ("result" in msg)
console.log(msg.result);
}Python
from claude_agent_sdk import query
async for message in query(
prompt="auth.py 버그 찾아서 고쳐",
options=ClaudeAgentOptions(
allowed_tools=[
"Read", "Edit", "Bash"
]
)
):
if hasattr(message, "result"):
print(message.result)파일 구조 총정리
어디에 뭘 두면 되는지
프로젝트/
├── CLAUDE.md # 팀 규칙 (Git 공유)
├── CLAUDE.local.md # 내 규칙 (.gitignore)
├── .mcp.json # MCP 서버 (팀 공유)
├── .claude/
│ ├── settings.json # 프로젝트 설정 (팀)
│ ├── settings.local.json # 내 설정 (.gitignore)
│ ├── agents/ # 커스텀 에이전트
│ │ └── code-reviewer.md
│ ├── skills/ # 커스텀 스킬
│ │ └── deploy/SKILL.md
│ ├── rules/ # 경로별 규칙
│ │ ├── frontend.md
│ │ └── api.md
│ └── hooks/ # 훅 스크립트
│ └── protect-files.sh
홈/
└── ~/.claude/
├── settings.json # 전역 설정
├── CLAUDE.md # 전역 규칙
├── agents/ # 전역 에이전트
├── skills/ # 전역 스킬
└── projects/<id>/memory/ # 자동 메모리
└── MEMORY.md파워 유저 팁
복잡한 작업은 plan 모드로 시작. Claude가 코드를 읽고 계획을 세운 뒤 승인하면 실행한다.
테스트 실행, 문서 분석 등 장황한 작업은 서브에이전트에 위임. 메인 컨텍스트가 깨끗하게 유지된다.
프로젝트 규칙을 한번 적어두면 매 세션마다 Claude가 자동으로 따른다. 반복 설명이 사라진다.
대화가 길어지면 컨텍스트 윈도우가 찬다. /compact로 정리하면 중요한 것만 남기고 계속 작업 가능.
GitHub, DB, 모니터링 등을 MCP로 연결하면 Claude가 직접 데이터를 조회하고 작업한다.
/rename으로 세션에 이름을 붙이면 나중에 claude --resume 이름 으로 이어서 작업할 수 있다.
Claude Code