이 글은 claude code를 몇번 번 사용해 본 유저를 대상으로 작성되었습니다. claude code를 처음 사용하는 사람에게 벅찬 내용일 수 있습니다. 놀랍게도 이 글의 60%이상이 claude code가 작성했습니다.
들어가기 전에
claude code의 내용은 계속 업데이트되니 공식문서를 참조하는게 가장 좋습니다. 이 글은 2026년 2월 기준으로 제 경험을 기준으로 claude code 사용방법이 정리되었습니다.
- 공식문서: https://code.claude.com/docs/en/settings
목차
요약
- 제 생각엔 Claude Code는 AI 모델을 감싸서 실제로 일할 수 있게 만드는 Agentic Harness입니다
- 세션마다 고유한 Context를 가지고 있고, Context는 AI 모델에게 보내는 맥락 전체입니다
- Context에는 Memory(CLAUDE.md, Auto memory)가 포함되어 있고, Memory는 세션이 바뀌어도 유지됩니다
- 아쉽게도 이 글에서는 도구(Tools), 샌드박스(Sandbox), 권한(Permission), 확장(MCP, Skills, Hooks)은 다루지 못했습니다. 시간이 된다면 이후에 정리할 예정입니다.
Claude Code는 무엇인가?
본격적으로 Claude Code가 무엇인지 알아봅시다. Claude Code를 이해하려면 세 가지 개념을 알아야 합니다. AI 모델, Harness, AI Agent입니다.
AI 모델: 추론
Claude AI 모델은 LLM(Large Language Model)입니다. LLM은 다음에 올 토큰을 확률적으로 예측해서 가장 높은 확률의 토큰을 선택합니다. 이를 추론이라합니다.
claude code에서는 2026년 2월 기준으로 claude AI모델만 사용할 수 있고, /model 명령어로 AI 모델을 변경할 수 있습니다.
# AI 모델 선택
/model
추론과정에서 토큰(Token)이란 토큰이란 용어가 나옵니다. 토큰은 AI 모델이 텍스트를 처리하는 최소 단위입니다. 헷갈리면 안 되는 점은, 토큰 ≠ 단어입니다. 영어는 대략 1단어 ≈ 1토큰이지만, 한글은 1글자가 여러 토큰으로 쪼개질 수 있습니다.
토큰은 두 종류로 나뉩니다.
| Input token | 모델이 읽는 모든 것. 사용자 질문, 시스템 프롬프트, 이전 대화 맥락 등 |
| Output token | 모델이 생성하는 답변 |
토큰은 AI 모델의 처리 단위이기 때문에 AI모델 사용량을 측정할 때 사용됩니다. claude code는 /stats 명령어로 사용한 토큰을 확인할 수 있습니다.
# 토큰 사용량 확인
/stats
Harness: AI 모델을 감싸서 일할 수 있게 만드는 시스템
AI 모델은 스스로 파일을 읽거나, 코드를 수정하거나, 명령어를 실행할 수 없습니다. 토큰을 예측해서 텍스트를 생성할 뿐입니다. 따라서, AI 모델을 감싸서 실제로 일할 수 있게 만드는 시스템이 필요합니다. 이 시스템을 Harness라고 부릅니다.
Harness는 원래 “마구”라는 뜻입니다. 말(horse)에 채워서 제어하는 도구입니다. AI에서도 비슷합니다. Harness는 AI 모델(LLM)을 감싸서 도구를 사용하고, 권한을 관리하고, 상태를 유지하는 시스템 전체를 의미합니다. 마치 OS가 시스템을 관리하는 것처럼 Harness는 AI 시스템을 관리합니다.
CLAUDE.md, skills 등이 Harness에 해당합니다.
AI Agent: AI 모델 + Harness
AI Agent는 AI모델을 활용하는 소프트웨어입니다. AI Agent는 AI모델을 사용하여 스스로 판단하고 행동(Act)합니다. 이 때 AI Agent는 AI 시스템을 관리하는 Harness도 활용합니다.
| AI 모델 | 텍스트를 생성. 스스로 행동하지 못함 |
| Harness | 도구 실행, 권한 관리, 상태 유지, 컨텍스트 관리 |
| AI Agent | 스스로 판단하고 행동함 |
Claude Code는 Agentic Harness다
그렇다면 Claude Code는 AI 모델, Harness, AI Agent 이 3개 중 어디에 해당할까요? 공식문서를 참조하면, 제 생각엔 Claude Code는 Agentic Harness입니다. Claude AI 모델을 감싸서, 도구 실행/컨텍스트 관리/실행 환경을 제공하는 시스템입니다.
Claude Code serves as the agentic harness around Claude: it provides the tools, context management, and execution environment that turn a language model into a capable coding agent.
출처: https://code.claude.com/docs/en/how-claude-code-works
사용자가 “이 버그를 고쳐줘”라고 하면, Claude AI 모델이 “파일을 읽어야겠다”고 판단하고, Claude Code(Harness)가 실제로 파일을 읽어서 결과를 모델에게 돌려줍니다. 모델이 다시 “이 부분을 수정해야겠다”고 판단하면, Claude Code가 코드를 수정합니다. 이 과정이 반복되면서 버그가 고쳐집니다.
Claude Code는 어떻게 동작하는가? (Agentic Loop)
Claude Code(Harness)는 Agentic Loop라는 반복 작업으로 동작합니다. 세 가지 단계를 반복합니다.
Agentic Loop 설명문서: https://code.claude.com/docs/en/how-claude-code-works
- 맥락 수집 (Gather Context): 파일을 읽고, 코드를 검색하고, 프로젝트 구조를 파악합니다
- 행동 (Take Action): 코드를 수정하고, 명령어를 실행합니다
- 검증 (Verify Results): 테스트를 실행하고, 결과를 확인합니다
claude code 동작원리는 Agentic Loop가 핵심입니다. AI 모델이 “다음에 뭘 해야 할지” 판단하면, Claude Code(Harness)가 실제로 도구를 실행하고 결과를 AI 모델에게 전달합니다. 모델은 그 결과를 보고 다음 행동을 결정합니다. 작업이 완료될 때까지 이 과정이 반복됩니다.
사용자인 저희도 이 loop의 일부입니다. 언제든 중간에 개입해서 방향을 바꾸거나, 추가 정보를 제공하거나, 다른 접근 방식을 시도하라고 할 수 있습니다.
Claude Code(Harness)의 구성 요소
Claude Code가 Harness로서 제공하는 기능은 크게 여섯 가지입니다. 이 글에서는 세션과 Context(Memory 포함)만 다룹니다. 나머지는 시간이 된다면 이후에 에서 정리할 예정입니다.
| 도구 (Tools) | Bash, 파일 읽기/수정, 웹 검색, MCP 서버 등 실제 행동을 실행 |
| 권한/안전 (Permission) | 도구별 권한 설정, 사용자 승인 게이트 |
| 샌드박스 (Sandbox) | 도구 실행을 격리된 환경에서 안전하게 수행 |
| 세션 (Session) | 사용자와의 연결 단위. 세션 저장, 이전 세션 불러오기 |
| Context (Memory 포함) | 대화 맥락 유지, CLAUDE.md, Context Window 관리 |
| 확장 (Extensibility) | MCP, Skills, Hooks로 기능 확장 |
세션(Session)
세션이란?
세션(Session)은 Claude Code를 실행한 시점부터 종료할 때까지 유지되는 연결입니다. 사용자는 세션을 통해 claude code에 작업을 요청을 합니다. 터미널에서 claude를 실행하면 새 세션이 시작되고, /exit이나 Ctrl+C로 종료하면 세션이 끝납니다.
웹 브라우저 또는 데스크탑 앱에서는 사용자가 작업을 요청할 때 세션을 생성합니다.
세션이 시작되면,
세션이 생성되면 claude code는 작업을 할 수 있도록 일종의 초기화 작업을 합니다. MCP 불러오기, Skills 불러오기, context 불러오기 등을 수행합니다.
세션은 세션마다 데이터를 가지고 있는 데 이를 context라고 합니다. context는 세션 내에서 메모리에 유지되고, 로컬 파일(JSONL)에 백업됩니다. context에 대한 자세한 내용은 Context 챕터에서 다룹니다.
세션 ID 조회
세션은 세션마다 고유한 ID를 가집니다. /status에서 session ID가 세션ID입니다.
/status
세션의 context는 어디에 저장될까?
세션의 context는 메모리에 유지되고, 로컬 파일(JSONL)에 백업됩니다. 파일은 백업 용도이기 때문에 세션 중에는 사용하지 않습니다. 백업의 의미는 종료된 세션을 다시 불러오기 위한 목적입니다.
파일 저장 경로는 ~/.claude/projects/ 입니다.
~/.claude/projects/{프로젝트경로}/{세션UUID}.jsonl
예를 들어 my-project 디렉토리에서 Claude Code를 실행하면, 세션 파일은 아래 경로에 생성됩니다.
~/.claude/projects/my-project/f41ff972-7bab-4719-8a7a-e564732bdaf0.jsonl
JSONL(JSON Lines)파일은 claude code 세션의 context가 한 줄씩 기록됩니다. 같은 디렉토리에서 claude를 여러 번 실행하면, 그만큼 JSONL 파일이 생깁니다. 예를 들어 제가 claude code에서 세션에 대한 질문을 아래처럼 물어봤습니다.
제가 물어본 내용은 먼저 context에 저장되고, 이후 jsonl파일에 백업됩니다. 참고로 jsonl는 jq명령어로 필터링이 가능합니다.
cat f41ff972-7bab-4719-8a7a-e564732bdaf0.jsonl | jq -r 'select(.type == "user") | .message.content'
이전 세션 불러오기
세션의 context가 파일에 백업되기 때문에, 세션을 실수로 종료하더라도 다시 이전 세션을 불러올 수 있습니다. 이전 세션을 이어서 하고 싶다면 두 가지 옵션이 있습니다.
–continue: 가장 최근 세션 이어가기
claude –continue는 현재 디렉토리에서 가장 최근에 사용한 세션의 JSONL 파일을 찾아서 대화 맥락을 다시 로드합니다.
claude --continue
가장 최근 세션”은 어떻게 판단할까요? git HEAD 같은 포인터가 있는 것은 아닙니다. JSONL 파일의 수정 시간(mtime)을 기준으로 가장 최근 파일을 선택합니다.
주의할 점이 있습니다. –continue는 현재 디렉토리 기준으로 세션 파일을 찾습니다. 이전에 세션을 실행했던 디렉토리와 다른 디렉토리에서 실행하면 아래와 같은 에러가 발생합니다.
$ claude --continue
No conversation found to continue
–resume: 특정 세션 선택하기
claude –resume은 목록에서 원하는 세션을 선택할 수 있습니다. 세션 ID를 따로 외울 필요 없이, 이 목록에서 골라서 세션을 이어가면 됩니다.
claude --resume
Context
Context란?
AI 모델은 이전 대화를 기억하지 못합니다. 매번 새로운 요청으로 처리합니다. 그래서 Claude Code(Harness)가 매 요청마다 필요한 맥락을 구성해서 AI 모델에게 보냅니다.
Context는 Claude Code(Harness)가 AI 모델에게 요청할 때 함께 보내는 맥락 전체입니다. Harness 챕터에서 설명한 것처럼, context 관리는 Claude code의 핵심 역할입니다.
Context 종류
대표적인 context의 종류는 아래와 같습니다.
| System prompt | Claude Code의 기본 시스템 명령어 |
| System tools | 도구 정의 (Read, Edit, Bash 등) |
| Skills | 스킬 메타데이터 |
| Messages | 지금까지의 대화 내용 (질문 + 응답 + 도구 결과) |
| Autocompact buffer | 압축한 context |
Context Window (크기)
Context Window는 context를 담을 수 있는 최대 크기입니다. Claude 모델의 context window는 200k 토큰입니다.
대화가 쌓이면 context가 커지고, 200k 토큰 한계에 도달하면 관리가 필요합니다. 이 관리 방법은 뒤에서 설명하는 Context 초기화와 Context 압축입니다.
Memory
Context에 로드되는 요소 중에 특별한 것이 있습니다. Memory는 세션이 바뀌어도 유지되는 지시/정보입니다. Context의 다른 내용(대화, 도구 결과)은 세션이 끝나면 사라지지만, Memory는 파일로 영구 저장되어 다음 세션에서도 다시 context에 로드됩니다.
Claude Code의 Memory는 크게 두 종류입니다.
1. CLAUDE.md 파일: 사용자가 직접 작성하는 지시/규칙
2. Auto memory: Claude가 작업하면서 자동으로 기록하는 학습 내용
CLAUDE.md
CLAUDE.md는 Claude Code에게 주는 지시서입니다. 세션이 시작될 때 자동으로 읽어서 context에 로드합니다. /memory 명령어로 편집할 수 있습니다.
| User memory | ~/.claude/CLAUDE.md | 개인 설정 (모든 프로젝트 공통) | 나만 사용 |
| Project memory | ./CLAUDE.md | 팀 공유 프로젝트 규칙 | 팀 전체 (git) |
| Project memory (local) | ./CLAUDE.local.md | 개인 프로젝트 설정 | 나만 사용 (자동 gitignore) |
| Project rules | .claude/rules/*.md | 모듈화된 프로젝트 규칙 | 팀 전체 (git) |
Auto Memory
Auto memory는 Claude가 작업하면서 자동으로 기록하는 학습 내용입니다. 프로젝트 패턴, 디버깅 인사이트, 사용자 선호도 등을 자동으로 저장합니다.
Auto Memory는 2026년 2월 기준으로 점진적으로 배포되고 있어서 기본으로 활성화 된 사용자가 있거나 비활성화된 사용자가 있습니다. Auto Memory 활성화 여부는 /memory 명령어로 확인할 수 있습니다.
/memory
Auto Memory를 활성화하려면 환경변수 CLAUDE_CODE_DISABLE_AUTO_MEMORY를 설정하면 됩니다.
CLAUDE_CODE_DISABLE_AUTO_MEMORY=0
저장 위치는 ~/.claude/projects/<project>/memory/ 입니다. MEMORY.md 파일이 인덱스 역할을 하고, 세부 내용은 별도 파일로 관리됩니다.
~/.claude/projects/<project>/memory/
├── MEMORY.md # 인덱스 (세션 시작 시 처음 200줄 로드)
├── debugging.md # 디버깅 패턴 메모
├── api-conventions.md # API 설계 결정
└── ...
Context 초기화 (/clear)
/clear는 현재 세션의 context를 초기화하는 명령어입니다. 대화 내용, 읽은 파일 내용 등이 모두 사라지고 세션 시작 상태로 돌아갑니다. Memory(CLAUDE.md, Auto memory)는 파일로 저장되어 있기 때문에 다시 로드됩니다.
/clear
헷갈리면 안 되는 점이 있습니다. /clear는 JSONL 세션 파일을 삭제하지 않습니다. context만 초기화할 뿐, 세션 파일은 그대로 남아 있습니다.
Context 압축 (Compaction)
대화가 길어지면 context가 계속 커집니다. 200k 토큰 한계에 가까워지면 어떻게 될까요? Auto compact 설정이 활성화 되어 있으면 자동 압축을 하고, 비활성화 되어 있으면 Context를 압축하라고 claude code가 사용자에게 알려줍니다.
사용자는 /compact 명령어로 수동으로 context를 압축할 수 있습니다.
/compact
context 압축 이후에는 이전 대화의 세부 내용을 잃어버릴 수 있습니다. 요약은 핵심만 남기기 때문에, “아까 세 번째 파일에서 수정한 부분 다시 보여줘” 같은 세부적인 질문에 답하지 못할 수 있습니다.
참고자료
- claude code 작동 방식: https://code.claude.com/docs/en/how-claude-code-works
- claude code 설정: https://code.claude.com/docs/en/settings
- claude code cli 문서: https://code.claude.com/docs/en/cli-reference
- claude code sandbox 릴리즈: https://www.anthropic.com/engineering/claude-code-sandboxing
- claude code compaction: https://platform.claude.com/docs/en/build-with-claude/compaction#how-compaction-works
- claude code context window: https://platform.claude.com/docs/en/build-with-claude/context-windows
'전공영역 공부 기록' 카테고리의 다른 글
| 리눅스에서 tmp 디렉터리가 메모리 사용률을 올리는 이유 (0) | 2026.03.01 |
|---|---|
| Claude Code 첫 프로젝트 후기 - SLO 계산기와 배포방법 고민 (0) | 2026.02.22 |
| 단순한 온프레미스 리다이렉트 서버를, AWS로 옮기는 방법들은 뭐가 있을까?(ALB vs CloudFront) (0) | 2026.02.17 |
| 내가 사용하는 Ghostty 설정 - 테마, 단축키, 분할화면 (macOS) (0) | 2026.02.16 |
| git worktree개념과 사용방법 (0) | 2026.02.15 |