Claude Code 구조와 동작 한눈에 보기
Claude Code를 단순히 “코딩을 도와주는 AI 챗봇”으로 이해하면 핵심을 놓치기 쉽습니다. Claude Code의 본질은 LLM 모델을 실제 개발 환경에서 일할 수 있는 Agent로 바꿔주는 실행 Harness에 가깝습니다.
Claude Code를 단순히 “코딩을 도와주는 AI 챗봇”으로 이해하면 핵심을 놓치기 쉽습니다. Claude Code의 본질은 LLM 모델을 실제 개발 환경에서 일할 수 있는 Agent로 바꿔주는 실행 Harness에 가깝습니다.
이 그림은 Claude Code를 구성하는 핵심 요소인 LLM Model, Agent, Memory, MCP, Agent Skills, Harness를 하나의 구조로 정리한 인포그래픽입니다.
1. Claude Code는 LLM 하나가 아니다
Claude Code의 중심에는 Claude 모델이 있습니다. 하지만 모델만으로는 파일을 읽고, 코드를 수정하고, 테스트를 실행하고, Git 작업을 수행할 수 없습니다.
모델은 추론합니다. Claude Code는 그 추론을 실제 행동으로 연결합니다.
즉, Claude Code는 다음과 같은 구조로 볼 수 있습니다.
LLM Model + Agent Loop + Tool Execution + Context Management + Safety Layer
이 조합이 있어야 비로소 “코딩 에이전트”가 됩니다.
2. Agent의 핵심은 반복 루프다
그림 중앙의 Agent는 세 단계의 루프로 표현되어 있습니다.
Context 수집 코드베이스, 파일, 테스트 결과, 문서, 사용자 요청을 읽고 상황을 파악합니다.
Action 실행 파일을 수정하거나, 명령어를 실행하거나, 검색하고, 필요한 도구를 호출합니다.
Verify 검증 테스트 결과, 로그, 변경사항을 확인하고 다시 다음 행동을 결정합니다.
이 루프는 한 번만 돌고 끝나는 것이 아닙니다. 필요하다면 Claude Code는 계속 탐색하고, 수정하고, 실행하고, 검증합니다.
중요한 점은 사용자가 이 루프의 밖에 있는 관찰자가 아니라는 것입니다. 사용자는 중간에 개입하고, 방향을 바꾸고, 승인을 하며, Agent의 작업 흐름을 함께 조정할 수 있습니다.
3. 기본 Harness: Claude Code가 기본으로 제공하는 실행 환경
그림의 왼쪽 녹색 영역은 기본 Harness입니다.
여기에는 Claude Code가 기본적으로 제공하는 기능들이 포함됩니다.
- 파일 읽기, 편집, 생성, 이동
- 코드 검색과 패턴 탐색
- Bash 실행, 테스트, 빌드, Git 작업
- 웹 검색과 문서 조회
- 세션 관리, 컨텍스트 관리, 컴팩션
- 권한 모드와 안전장치
- 기본 명령어와 번들 Skills
이 영역이 있기 때문에 Claude는 단순히 답변만 하는 모델이 아니라, 실제 개발 환경에서 행동할 수 있는 에이전트가 됩니다.
개인적으로는 이 부분을 **“Claude Code 순정 Harness”**라고 이해하면 좋다고 봅니다. Claude Code를 처음 배울 때는 이 기본 Harness를 먼저 잘 다루는 것이 중요합니다.
4. 사용자 설정 Harness: 내 환경에 맞게 Claude Code를 바꾸는 부분
그림의 오른쪽 보라색 영역은 사용자 설정 Harness입니다.
Claude Code의 진짜 생산성은 여기서부터 크게 달라집니다. 기본 기능 위에 개인, 프로젝트, 조직의 지식과 규칙을 얹을 수 있기 때문입니다.
대표적인 구성 요소는 다음과 같습니다.
Memory
CLAUDE.md, CLAUDE.local.md, rules/*.md, Auto Memory 등을 통해 Claude가 프로젝트의 맥락, 코딩 규칙, 반복되는 실수, 빌드 방법 등을 기억하게 만들 수 있습니다.
Agent Skills
SKILL.md를 통해 반복되는 절차, 체크리스트, 워크플로우를 캡슐화할 수 있습니다.
예를 들어 코드 리뷰, 디버깅, 배포 점검, 문서 생성 같은 작업을 Skill로 만들 수 있습니다.
MCP
MCP는 Claude Code를 외부 도구나 서비스와 연결하는 확장 통로입니다. 이슈 트래커, 데이터베이스, 사내 API, 문서 시스템 등과 연결하면 Claude가 더 많은 실제 맥락을 기반으로 작업할 수 있습니다.
Hooks / Automation
Hooks는 Claude가 도구를 실행하기 전후에 자동으로 동작하는 규칙입니다. 포맷팅, 검증, 알림, 정책 강제 같은 작업을 자동화할 수 있습니다.
Settings / Policy
settings.json, settings.local.json, managed-settings.json 등을 통해 권한, 환경 변수, 정책, 기본 동작을 설정할 수 있습니다.
5. 기본 Harness와 사용자 Harness를 구분해야 하는 이유
Claude Code를 잘 쓰기 위해서는 “도구를 많이 붙이는 것”보다 먼저 구조를 이해해야 합니다.
기본 Harness는 Claude Code가 이미 제공하는 실행 능력입니다. 사용자 설정 Harness는 그 위에 내가 추가하는 지식, 규칙, 도구, 정책입니다.
이 둘을 구분하면 다음 질문에 답하기 쉬워집니다.
이 문제는 Claude Code 기본 기능을 잘 쓰면 해결되는가? 아니면 우리 프로젝트에 맞는 Memory, Skill, MCP, Hook이 필요한가?
많은 경우 처음부터 복잡한 설정을 추가하기보다, 기본 Harness를 충분히 익힌 뒤 반복되는 패턴을 사용자 Harness로 승격시키는 것이 좋습니다.
6. Claude Code를 “환경”으로 이해하기
Claude Code는 단순한 CLI 도구라기보다, AI가 일하는 환경입니다.
모델은 추론하고, Agent는 루프를 돌고, Harness는 실행 능력을 주고, 사용자 설정 Harness는 Claude Code를 내 업무 환경에 맞게 바꿉니다.
그래서 Claude Code 사용 능력은 단순히 프롬프트를 잘 쓰는 능력만이 아닙니다.
오히려 더 중요한 것은 다음에 가깝습니다.
AI가 반복적으로 잘 일할 수 있도록 지식, 도구, 규칙, 실행 환경을 설계하는 능력
이것이 Claude Code 시대의 실질적인 생산성 차이를 만든다고 생각합니다.
마무리
이 그림은 Claude Code를 하나의 구조로 이해하기 위한 지도입니다.
처음에는 중앙의 Agent loop만 이해해도 충분합니다. 그다음 기본 Harness를 익히고, 반복되는 업무가 보이면 Memory, Skills, MCP, Hooks를 하나씩 추가해 나가면 됩니다.
Claude Code를 잘 쓴다는 것은 단순히 “AI에게 일을 시키는 것”이 아니라, AI가 더 잘 일할 수 있는 환경을 함께 만들어가는 과정입니다.
이 글은 위키독스 블로그에 처음 실었습니다.
댓글 0
첫 댓글을 남겨 주세요.
Google로 로그인하고 댓글 남기기