Claude 시스템 아키텍처 완전 해부

서론

2025년 9월, Anthropic은 $183B 기업가치로 $13B 자금을 조달하며 세계 4위 비상장 기업이 되었습니다. 핵심 제품인 Claude Code는 2월 출시 이후 11.5만 명의 활성 개발자를 유치했으며, 매주 1.95억 줄의 코드를 처리하고, 사용자 성장률은 **300%**에 달합니다.

더 흥미로운 것은 Anthropic CEO Dario Amodei가 밝힌 사실입니다: Claude Code 코드의 90%가 자기 자신이 작성했습니다.

어떻게 가능할까요?

하나의 AI 프로그래밍 어시스턴트가 어떻게 "스스로를 작성"할 수 있을까요? 어떤 아키텍처 설계가 이처럼 효율적으로 인간 개발자를 보조하고, 심지어 대체할 수 있게 만드는 것일까요?

정답은 Claude의 모듈식 아키텍처에 있습니다: MCP는 도구를 제공하고, Skills는 사용법을 가르치며, Subagents는 병렬로 실행하고, Hooks는 제어 가능성을 보장합니다. 이러한 구성 요소들이 협력하여 Claude에게 "프로그래머처럼 일하는" 능력을 부여합니다.

이 문서에서는 이 아키텍처의 전체 그림을 조감하겠습니다. 각 구성 요소의 역할, 구성 요소 간의 협업 관계, 그리고 빠르게 시작할 수 있는 설정 예시를 다룹니다. 후속 글에서는 각 구성 요소의 세부 사항을 깊이 분석할 예정입니다.

전체 아키텍처 개요

Claude 시스템은 모듈식 아키텍처 설계를 채택하고 있으며, 각 구성 요소는 기능별로 분류되어 상호 보완적으로 협력하며 계층적 의존이 아닙니다:

핵심 이해: 이러한 구성 요소들은 동급 보완적 확장 기능이며 계층적 의존이 아닙니다. 필요에 따라 자유롭게 조합할 수 있습니다:

핵심 런타임

Agent SDK — 런타임 엔진

Agent SDK는 전체 Claude Agent 시스템의 런타임 핵심 엔진으로, 다음을 제공합니다:

• 메인 루프 (Main Loop): Agent의 핵심 작업 루프
• 컨텍스트 관리: Token 예산, 자동 압축 (92% 사용률에서 트리거)
• 도구 디스패치: 어떤 도구를 사용할지, 어떻게 실행할지 결정
• 권한 시스템: 도구 접근 권한 제어

Agent의 핵심 작업 모드는 간단한 피드백 루프입니다:

컨텍스트 수집 → 작업 실행 → 작업 검증 → 반복

Built-in Tools — 핵심 도구

Claude Agent에는 20개 이상의 핵심 도구가 내장되어 있으며, 세 가지 범주로 나뉩니다:

이러한 도구는 기본적으로 사용 가능하며 추가 설정이 필요 없습니다. Claude는 이러한 도구를 통해 컴퓨터와 상호작용하며, 프로그래머가 IDE를 사용하는 것과 같습니다.

설정 및 컨텍스트

CLAUDE.md — 영구 컨텍스트

새로운 대화를 시작할 때마다 프로젝트 배경, 코딩 규칙, 아키텍처 약속을 반복해서 설명해야 합니다... CLAUDE.md를 사용하면 이러한 정보를 한 번 설정하고 자동으로 로드할 수 있습니다.

CLAUDE.md는 프로젝트의 README for AI와 같습니다. Claude에게 이 프로젝트의 배경 지식, 작업 방식, 약속을 알려줍니다.

계층적 오버라이드

Claude는 다음 순서로 CLAUDE.md를 로드하며, 더 구체적인 것이 더 높은 우선순위를 가집니다:

Enterprise (최저)
    ↓
User (~/.claude/CLAUDE.md)
    ↓
Project (./CLAUDE.md)
    ↓
Module (./src/module/CLAUDE.md) (최고)

내용 제안

CLAUDE.md에는 다음과 같은 핵심 정보를 포함해야 합니다:

핵심 원칙: 간결하게 유지하세요. CLAUDE.md는 매 대화마다 로드되므로, 너무 길면 소중한 Token을 낭비하게 됩니다.

패키징 및 배포

Plugins — 설치 가능한 단위

팀 설정이 분산되어 있고, 공유 및 표준화가 어렵습니다. 각자 자신만의 Skills, Commands, Hooks 세트를 가지고 있는데... 어떻게 통합 관리할 수 있을까요?

Plugins는 Skills + Commands + Subagents + Hooks + MCP를 설치 가능한 단위로 패키징하여, 원클릭 배포와 팀 표준화를 실현합니다.

디렉토리 구조

my-plugin/
├── .claude-plugin/
│   └── plugin.json     # 플러그인 매니페스트 (필수)
├── commands/           # Slash Commands
├── agents/             # Subagents
├── skills/             # Skills
├── hooks/              # Hooks 설정
├── .mcp.json           # MCP Server 설정
└── README.md           # 설명 문서

설정 예시

// plugin.json
{
  "name": "frontend-toolkit",
  "version": "1.0.0",
  "description": "프론트엔드 개발 툴킷",
  "author": "Your Team"
}

# 설치 방법
claude plugin install github:your-org/your-plugin  # GitHub에서
claude plugin install /path/to/plugin              # 로컬에서

관련 리소스

확장 기능 (상호 보완 모듈)

Claude 시스템의 확장 기능은 여러 상호 보완 모듈로 구성되어 있으며, 각자의 역할을 수행하면서 협력합니다:

MCP — 외부 연결

설계 철학

기존 방식에서는 각 외부 데이터 소스마다 커스텀 통합이 필요했으며, 이로 인해 N×M의 통합 지옥이 발생했습니다. MCP는 표준화된 프로토콜을 제공하여 한 번 연결하면 어디서나 사용 가능하게 합니다.

MCP (Model Context Protocol)는 AI 애플리케이션의 USB-C 인터페이스로 설계되었습니다:

아키텍처 패턴

┌─────────────────┐
│   MCP Host      │  (Claude Desktop, IDE, AI 도구)
│   (Main Agent)  │
└────────┬────────┘
         │ 1:N
    ┌────┴────┬────────┬────────┐
    │ Client  │ Client │ Client │  (프로토콜 클라이언트)
    └────┬────┴────┬───┴────┬───┘
         │         │        │
    ┌────┴────┐ ┌──┴───┐ ┌─┴────┐
    │ Server  │ │Server│ │Server│  (특정 기능 노출)
    │ GitHub  │ │  DB  │ │ Slack│
    └─────────┘ └──────┘ └──────┘

사용 시나리오: 데이터베이스 연결, 서드파티 서비스 통합 (GitHub, Slack, Notion), 프라이빗 API 접근, 실시간 데이터 스트림 처리.

설정 예시

프로젝트 루트 디렉토리에 .mcp.json을 생성합니다:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

Commands — 수동 워크플로

Slash Commands는 수동으로 트리거하는 반복적인 워크플로를 제공합니다.

예시: .claude/commands/review.md 생성

현재 변경 사항에 대해 코드 리뷰를 수행하세요. 다음에 중점을 두세요:
1. 코드 스타일과 일관성
2. 잠재적인 성능 문제
3. 보안 취약점
4. 테스트 커버리지

그런 다음 /review를 입력하면 트리거됩니다.

Hooks — 결정론적 제어

Hooks는 결정론적 제어의 핵심입니다. 특정 작업은 반드시 실행되어야 하며 LLM의 판단에 의존할 수 없습니다.

설정 예시

TypeScript 파일 자동 포맷팅:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | { read f; [[ $f == *.ts ]] && npx prettier --write \"$f\"; }"
          }
        ]
      }
    ]
  }
}

실전: 자율 루프

Ralph Wiggum은 Anthropic 공식 플러그인으로, Stop hook을 활용하여 자율 반복 루프를 구현합니다:

/ralph-loop "TODO API 구현, CRUD 및 테스트 포함" --max-iterations 20

작동 원리: Stop hook이 Claude의 종료를 가로채서 원래 prompt를 다시 주입하고, 작업이 완료되거나 최대 반복 횟수에 도달할 때까지 계속 반복합니다.

적용 시나리오: 여러 차례 반복이 필요한 작업 (테스트 통과, 코드 리팩토링), 자동 검증 수단이 있는 작업.

Subagents — 작업 위임 및 병렬 실행

설계 철학

단일 Agent가 직면하는 과제: 제한된 컨텍스트 윈도우, 병렬 처리 불가, 불명확한 책임 분담. Subagents는 Orchestrator-Worker 아키텍처 패턴을 채택하여 이러한 문제를 해결합니다:

Main Agent (Orchestrator)
    ├── 사용자 요청 분석
    ├── 계획 수립
    ├── 작업 분해
    └── 전문화된 서브 에이전트 생성
         ↓
    ┌────────┬────────┬────────┐
    │ Sub 1  │ Sub 2  │ Sub 3  │  (Workers - 병렬 실행)
    │ 코드   │ 테스트  │ 문서   │
    └────────┴────────┴────────┘
         ↓
    결과 통합 → 메인 에이전트 종합 출력

핵심 특성

성능 데이터: 다중 에이전트 시스템은 단일 에이전트보다 90.2% 높은 성능을 보이며, 병렬화는 연구 시간을 90% 단축할 수 있습니다 (Token 소비는 약 15배이지만, 복잡한 작업에는 가치가 있습니다).

설정 예시

.claude/agents/에 Markdown 파일을 생성합니다:

---
name: Code Reviewer
description: 코드 리뷰 전문 서브 에이전트
tools:
  - Read
  - Grep
  - Glob
---

당신은 숙련된 코드 리뷰 전문가입니다. 다음에 중점을 두세요:
1. 코드 품질과 유지보수성
2. 잠재적인 버그와 경계 조건
3. 성능 최적화 기회
4. 보안 취약점

Skills — 절차적 지식

설계 철학

Skills는 AI를 위한 재사용 가능한 작업 매뉴얼입니다. 모듈화된 지식 패키지로, Claude가 필요에 따라 동적으로 로드할 수 있습니다. 핵심 설계 원칙은 **점진적 공개 (Progressive Disclosure)**입니다:

📚 Skills 작업 매뉴얼
│
├─ 📋 목차 ────────────── 【메타데이터 레이어】시작 시 사전 로드 (~30-50 tokens)
│   name: "weekly-report"
│   description: "표준화된 주간 보고서 생성"
│
├─ 📖 본문 섹션 ─────────── 【핵심 문서 레이어】관련 시 로드 (~수백-수천 tokens)
│   # Weekly Report Generator
│   ## Instructions
│   다음 구조에 따라 주간 보고서 생성...
│
└─ 📎 부록 ────────────── 【참조 리소스 레이어】필요 시 로드
    references/
    ├── template.xlsx
    └── examples/

MCP vs Skills: MCP는 Claude에게 도구에 접근하는 능력을 제공하고 (WHAT), Skills는 Claude에게 이러한 도구를 효과적으로 사용하는 방법을 가르칩니다 (HOW).

핵심 장점

설정 예시

.claude/skills/에 디렉토리를 생성합니다:

my-skill/
├── SKILL.md          # 핵심 지시 사항 (필수)
├── scripts/          # 실행 가능한 스크립트 (선택)
└── references/       # 참고 자료 (선택)

SKILL.md 핵심 구조:

---
name: code-review                        # Skill 이름
description: 코드 리뷰, 품질 및 보안 검사    # 간단한 설명 (자동 매칭에 사용)
---

# Code Review Skill

## Instructions
[구체적인 단계 설명...]

## Output Format
[출력 형식 요구 사항...]

핵심 사항: frontmatter의 description은 자동 매칭에 사용되므로, 간결하고 정확하게 유지하세요.

공식 참조 링크

설계 철학

공식 문서

심층 분석

더 읽을거리

Skills의 개념과 실습을 더 깊이 알고 싶다면 다음을 참고하세요:

• Claude Skills란 무엇인가 — Skills 핵심 원리 상세 해설
• Claude Skills 실전 가이드 — 첫 번째 Skill 직접 만들기
• Claude Subagent 완벽 가이드 — 서브 에이전트 사용 및 커스터마이징
• GSD 심층 해부 — 컨텍스트 엔지니어링 기반 AI 프로그래밍 시스템
• 나의 Claude Code 모범 사례 — Claude Code 일상 사용 팁