Claude Code 기본 구조 이해하기(Agent, Skill, Context)

안녕하세요 Diana 입니다.

오늘은 Claude Code를 사용하기에 앞서 Claude Code의 기본 구조인 Agent, Skill, Context 에 대해 알아보려고 합니다.

 

Claude Code 는 터미널에서 실행되는 Agent 어시스턴트 입니다.

코딩에 탁월하며 문서 작성, 빌드 실행, 파일 검색 등 명령줄에서 할 수 있는 모든 작업을 도와줍니다.

 

Claude Code는 Claude 주변의 에이전트 하네스 역할을 합니다. 언어 모델을 능력 있는 코딩 에이전트로 변환하는 도구이며 텍스트 관리와 실행 환경을 제공합니다.

 

여기서 Agent, 즉 Claude Code은 AI를 요청을 단순히 처리하는 수동적인 존재가 아닌 일을 수행하는 하나의 실행 주체로 전제합니다.

 

그럼 이 Agent가 대체 무엇일까요?

 

✅ Agent 란?

Agent는 특정 역할과 책임을 가진 실행 주체입니다.

Agent는 단순 프롬프트 또는 대화 세션이 아닌 어떤 역할을 수행하는지, 어떤 작업(Task)를 담당하는지 그리고 어떤 입력과 출력을 가지느냐에 따라 역할 단위가 나눠집니다.

예를 들면 PR 리뷰 Agent, 문서 생성 Agent 등으로 나뉘는 방식이죠.

 

✅ Skill 이란?

Skill은 재사용이 가능한 작업 단위로 Agent가 누구인가 를 나타낸다면 Skill은 무엇을 할 수 있는가 를 나타냅니다.

여기서 중요한 점은 Skill이 단순히 잘 작성된 프롬프트와 다르다는 것입니다.

 

프롬프트의 경우 개인에게 종속되어 버전관리가 어렵고 테스트가 불가능하며 재사용에 불안정한 반면, Skill은 코드처럼 관리되며 설치가 가능하고 버전 관리가 가능하며 여러 Agent에서 재사용이 가능합니다.

 

실제 생김새는 아래와 같습니다.

.claude/skills/pr-review/
├── SKILL.md          ← 본체 (마크다운)
├── scripts/check.sh  ← 선택: 실행 스크립트
└── reference/rules.md ← 선택: 참고 문서

 

Sill은 AI 활용의 최소 실행 단위이자 조직 차원에서 공유 자산을 의미합니다.

예시는 아래와 같습니다.

---
name: pr-review
description: PR 리뷰가 필요할 때 사용. 변경사항 검토 후 코멘트 작성.
---

## 절차
1. `git diff main...HEAD`로 변경사항 확인
2. 아래 체크리스트 기준으로 검토
3. 파일별 코멘트 작성

✅ Context 란?

Context는 Agent가 작업을 수행하기 위해 의도적으로 제공되는 제한된 정보 공간을 의미합니다.

 

Context의 핵심은 제한이며 모든 정보를 주는 것이 아닌 필요한 정보만을 제공하며 역할에 맞는 범위만을 허용합니다.

이는 결과의 예측 가능성을 높히고 일관된 실행을 보장해주며 불필요한 토큰 낭비를 방지해줍니다.

 

Prompt가 AI와의 즉흥적인 대화라면 Context는 설계된 실행 환경입니다.

 

그럼 이렇게 Agent, Skill, Context는 어떻게 연결될까요?

이 셋은 독립된 개념이 아닌 항상 함께 동작합니다.

구조적으로 표현하면 Agent가 Skill을 사용하고 Agent가 Context의 제한 내에서 동작하는 것이죠.

 

즉, Agent는 역할과 책임을 가지고 Skill은 Agent 가 수행할 수 있는 기능이며 Context는 그 기능이 실행되는 정보 경계인 것입니다.

 

Claude Code가 지향하는 것은 프롬프트를 더 잘쓰는 방법이 아닙니다.

프롬프트에 의존하지 않더라도 AI를 안정적으로 활용할 수 잇는 구조를 생성하는 것이죠.

 

✅ Claude Code의 작동 방식

Claude에게 작업을 주면 아래의 그림과 같이 컨텍스트 수집, 작업 수행, 결과 검증의 단계를 거치게 됩니다.

 

 

Claude는 이 단계들을 거칠 때 이전 단계에서 배운 내용을 바탕으로 각 단계에서 필요한 것을 결정하고 수십 개의 작업을 연결하며 그 과정의 방향을 수정합니다.

 

이 반복되는 과정을 우리는 Agent Loop 라고 부르며 추론하는 모델과 작용하는 도구 라는 두 가지의 구성요소로 구동됩니다.

Claude Code는 Claude 주변의 에이전트 하네스 역할을 하며 언어 모델을 능력있는 코딩 에이전트로 변환하는 도구, 컨텍스트 관리, 실행환경을 제공합니다.

 

Claude Code 는 Claude 모델을 사용하여 코드를 이해하고 작업에 대해 추론합니다. 모델에는 Sonnet, Opus 등이 존재하며 각각 다른 특징을 가지고 있습니다.

 

도구의 경우 Claude Code를 에이전트로 만들어 줍니다. 도구가 없으면 Claude는 텍스트로만 응답할 수 있고 도구가 있어야 코드를 읽고 파일을 편집하고 명령을 실행하는 등의 상호작용이 가능해집니다.

 

내장 도구는 다섯 가지의 범주로 나눠지며 각각 다른 종류의 에이전시를 나타냅니다.

범주	하는 일
파일 작업	파일 읽기, 코드 편집, 새 파일 생성, 이름 변경 및 재구성
검색	패턴으로 파일 찾기, 정규식으로 콘텐츠 검색, 코드 베이스 탐색
실행	셀 명령 실행, 서버 시작, 테스트 실행, Git 사용
웹	웹 검색, 문서 가져오기, 오류 메세지 조회
코드 인텔리전스	편집 후 타입 오류 및 경고 확인, 정의로 이동, 참조 찾기 등

 

Claude는 프롬프트와 그 과정에서 학습한 내용을 바탕으로 사용할 도구를 선택합니다.

각 도구는 Claude에게 다음 단계를 알리는 새로운 정보를 제공하며 이것이 바로 위에서 알아본 Agent Loop의 작동입니다.

 

도구의 동작을 아는 것은 기초로 Claude Code는 더 나아가 Skill로 Claude가 알 수 있는 것을 확장하고 MCP로 외부 서비스에 연결하고, Hooks로 워크 플로우를 자동화하고 Subagents로 작업을 위임할 수 있습니다. 이러한 확장은 핵심 에이전트 루프 위에 계층을 형성합니다.

 

세션

Claude Code는 작업한 대화 내용을 로컬에 저장합니다. 각 메시지, 도구 사용, 결과가 ~/.claude/projects/ 아래의 파일에 기록되며 되돌리기, 재개 및 포크 세션을 활성화합니다. 

 

세션은 독립적이며 각 새 세션은 대화 기록 없이 새로운 컨텍스트 윈도우로 시작합니다. Claude는 자동 메모리를 사용하여 세션간의 학습을 유지하고 CLAUDE.md에 자신의 지속적인 지침을 추가할 수 있습니다.

 

이렇게 세션 ID를 사용한 세션을 통해 우리는 작업 시점과 상태를 제어하고 통제합니다.

 

컨텍스트

Claude의 컨텍스트 윈도우는 작업이 시작되면 대화 기록, 파일 콘텐츠, 명령 출력, CLAUDE.md, 자동 메모리, 로드된 Skills, 시스템 지침 등으로 채워집니다.

Context가 가득 차는 경우 Claude는 자동으로 Context를 압축하며 이로 인해 작업 초반의 지침이 손실될 수 있습니다. 따라서 지속적으로 CLAUDE.md를 업데이트 하고 /context 명령어를 통해 공간을 관리하는 작업이 필요합니다.

 

Claude Code는 자동으로 Context를 관리하며 이전 도구 출력을 지우고 대화를 요약합니다.

요청과 주요 코드 스니펫은 유지되지만 압축으로 인해 자세한 지침은 손실될 가능성이 존재합니다.

 

우리가 Claude Code를 사용하며 초반에 설정한 내용들이 초기화되고 망각되는 현상은 바로 이런 이유로 발생합니다.

 

이렇게 오늘은 Claude Code의 핵심 개념들과 동작 원리에 대해 알아보았습니다.

 

감사합니다.

 

출처

Claude Code Docs - Claude Code 작동 방식

KT - [AI 활용] Claude Code 기본 구조 이해하기