Claude Code의 아키텍처 패러다임: Skills, Sub-agents 및 에이전트 오케스트레이션

1. 개요 (Executive Summary)

소프트웨어 엔지니어링의 지평이 수동적인 통합 개발 환경(IDE)에서 능동적인 에이전트 기반 코딩 파트너(Agentic Coding Partner)로 급격히 이동하고 있다. Anthropic의 Claude Code는 이러한 변화의 최전선에 있는 도구로, 단순한 코드 자동 완성을 넘어 터미널 환경에서 파일 시스템을 탐색하고, 명령어를 실행하며, 복잡한 다단계 워크플로우를 자율적으로 수행하는 시스템이다. 본 보고서는 Claude Code의 핵심 구동 원리인 Skills(기술)과 Sub-agents(서브 에이전트), 그리고 이들을 연결하는 에이전트 그래프(Agentic Graph) 아키텍처에 대해 기술적으로 철저히 분석한다.

본 연구는 Skills를 모델의 '절차적 기억(Procedural Memory)'을 확장하는 모듈로, Sub-agents를 독립적인 컨텍스트를 가진 '전문 작업자(Specialized Workers)'로 정의하고, 이 둘의 상호 운용성을 규명한다. 또한, 단순한 명령 실행을 넘어 다수의 에이전트가 협업하는 방향성 비순환 그래프(DAG) 기반의 워크플로우를 설계하는 방법론과, 이를 엔터프라이즈 환경에서 제어하기 위한 설정(Configuration) 및 훅(Hooks) 시스템의 결정론적 자동화 메커니즘을 상세히 다룬다. 이를 통해 개발 팀이 Claude Code를 단순 CLI 도구가 아닌, 자가 수정(Self-correcting)이 가능한 지능형 개발 플랫폼으로 활용할 수 있는 전략을 제시한다.

2. 서론: 에이전트 기반 개발의 부상과 Claude Code

전통적인 코딩 어시스턴트가 개발자의 입력을 기다리는 수동적 도구였다면, Claude Code는 개발자의 의도를 파악하고 파일 시스템과 터미널을 장악하여 능동적으로 작업을 수행하는 '에이전트(Agent)'이다. 이 시스템의 강력함은 단일 거대 언어 모델(LLM)의 지능에 의존하는 것이 아니라, Skills와 Sub-agents라는 두 가지 핵심 추상화 계층을 통해 모델의 능력을 수평적, 수직적으로 확장한다는 점에 있다. 본 보고서는 이 두 가지 핵심 요소의 정의부터 시작하여, 이들이 어떻게 유기적으로 결합되어 복잡한 엔지니어링 문제를 해결하는지 심층적으로 탐구한다.

3. Skills (기술): 컨텍스트 기반의 역량 확장

3.1 Skills의 정의 및 개념적 프레임워크

Claude Code 아키텍처에서 Skills는 모델의 지식을 확장하기 위한 모듈화된 '절차적 지식 패키지' 또는 '조리법(Recipe)'으로 정의된다. 이는 모델의 가중치(Weights)를 직접 수정하지 않고도, 특정 도메인의 지식이나 워크플로우를 에이전트의 작업 기억(Working Memory)에 주입하는 메커니즘이다.

Skills의 핵심 철학은 "기회주의적 로딩(Opportunistic Loading)"에 있다. 모든 지침을 시스템 프롬프트에 담을 경우 컨텍스트 윈도우가 포화되어 모델의 추론 능력이 저하된다. 반면, Skills는 에이전트가 현재 수행 중인 작업과 관련된 경우에만 동적으로 로드된다. 예를 들어, 사용자가 "이 레거시 코드를 설명해줘"라고 요청할 때만 explain-code라는 Skill이 활성화되어, 해당 설명 방식에 대한 구체적인 지침을 모델에 제공한다. 이는 예측 가능성(Predictability)을 일부 희생하는 대신 컨텍스트 효율성(Context Efficiency)을 극대화하는 전략이다.

3.2 Skills의 상세 구조 및 구성 요소

기술적으로 Skill은 단순한 텍스트 파일이 아니라, Agent Skills 개방형 표준을 따르는 디렉토리 구조로 구현된다. 이는 다양한 AI 도구 간의 상호 운용성을 보장한다.

3.2.1 파일 시스템 구조

강력한 기능을 가진 Skill은 다음과 같은 파일들로 구성된 디렉토리 형태를 띤다:

• SKILL.md: Skill의 진입점(Entrypoint)이 되는 핵심 파일로, YAML 프론트매터(Frontmatter)와 마크다운 지침을 포함한다.
• template.md: 에이전트가 문서를 작성할 때 사용할 템플릿 파일이다.
• examples/: 에이전트에게 기대하는 출력 형식을 보여주는 퓨샷(Few-shot) 예제 파일들이 위치한다.
• scripts/: Skill 실행 중 에이전트가 호출할 수 있는 파이썬(Python)이나 쉘(Shell) 스크립트를 포함한다. 예를 들어, 데이터 검증을 수행하는 validate.py 등이 포함될 수 있다.

3.2.2 YAML 프론트매터 설정 (Syntax)

SKILL.md 파일의 상단에는 Skill의 동작을 제어하는 YAML 블록이 반드시 포함되어야 한다. 이 메타데이터는 오케스트레이션 레이어가 Skill을 언제 로드할지 결정하는 데 사용된다.

• name: Skill의 고유 식별자이다 (예: generate-diagram). 공백 없이 소문자와 하이픈을 사용한다.
• description: 가장 중요한 필드로, 에이전트가 이 Skill의 용도를 이해하는 의미론적 벡터(Semantic Vector) 역할을 한다. 사용자의 자연어 요청(Intent)과 이 설명이 일치할 때 Skill이 자동으로 활성화된다.
• argument-hint: 사용자가 수동으로 Skill을 호출할 때 표시될 인자 힌트이다 (예: [source-file]).
• allowed-tools: 보안 및 안전성을 위해 해당 Skill이 활성화된 동안 사용할 수 있는 도구를 제한한다. 예를 들어, 문서를 읽기만 해야 하는 Skill에는 Write 도구를 차단하고 Read, Glob만 허용할 수 있다.
• disable-model-invocation: 이 값을 true로 설정하면, 모델이 스스로 판단하여 Skill을 호출하는 것을 막고 오직 사용자의 명시적인 명령어(/skill-name)에 의해서만 실행되도록 강제한다.

3.3 사용 패턴: 자동 감지 vs 수동 호출

Skills의 활용 방식은 크게 두 가지로 나뉜다.

자동 감지 (Automatic Discovery):

사용자가 "이 데이터베이스 스키마를 분석해줘"라고 입력하면, Claude Code는 사용 가능한 모든 Skill의 description을 스캔한다. 만약 db-analyzer라는 Skill의 설명이 이 요청과 의미적으로 유사하다면, 시스템은 해당 Skill의 내용을 현재 대화의 컨텍스트에 조용히 주입한다. 이 과정은 사용자에게 투명하게 이루어지며, 에이전트가 마치 처음부터 해당 지식을 알고 있었던 것처럼 행동하게 한다.

수동 호출 (Manual Invocation):

슬래시 커맨드(/)를 사용하여 특정 Skill을 강제로 실행하는 방식이다 (예: /review-docs src/README.md). 이는 반복적이고 정형화된 작업, 혹은 모델의 판단에 맡기기에는 중요한 보안 절차 등을 수행할 때 선호된다.

3.4 Skills의 구체적 예제 및 구현

예제 A: 문서 검토자 (Documentation Reviewer)

기술 문서 작성 시, 회사 고유의 스타일 가이드를 준수하도록 강제하는 Skill이다.

파일 위치: .claude/skills/docs-reviewer/SKILL.md

구성:

---
name: docs-reviewer
description: 기술 문서를 회사의 스타일 가이드(능동태 사용, 명확한 제목 계층 등)에 맞춰 검토하고 수정 제안을 함.
allowed-tools: Read, Edit
---

당신은 전문 테크니컬 에디터입니다. 다음 규칙에 따라 문서를 검토하십시오:

1. 수동태 대신 능동태를 사용하십시오.
2. 모든 절차는 번호가 매겨진 목록으로 작성하십시오.
3. 약어는 최초 등장 시 전체 이름을 명시하십시오.

참고 파일: @style-guide.md

효과: 사용자가 문서를 제출하면, 에이전트는 일반적인 언어 모델이 아닌 '회사의 편집자' 페르소나를 가지고 문서를 교정한다.

예제 B: 코드 설명 표준화 (Code Explainer)

신규 입사자가 코드를 이해할 때 일관된 형식으로 설명을 제공하기 위한 Skill이다.

구성:

---
name: explain-code
description: 복잡한 코드를 비유와 시각적 다이어그램을 사용하여 초보자에게 설명함.
---

코드를 설명할 때는 반드시 다음 3단계를 따르십시오:

1. **현실 세계의 비유**: 이 코드가 하는 일을 일상생활의 개념에 비유하십시오.
2. **ASCII 다이어그램**: 데이터의 흐름을 텍스트 다이어그램으로 그리십시오.
3. **라인별 분석**: 핵심 로직을 한 줄씩 분석하십시오.

예제 C: 리버스 엔지니어링 (Reverse Engineering)

Claude가 생성한 문서(Excel, PDF 등)의 구조를 역추적하여 이를 프로그래밍 방식으로 재생성하는 코드를 추출하는 고급 Skill이다. 이는 Skills가 단순한 텍스트 지침을 넘어, 복잡한 인지 작업을 수행하는 '매크로(Macro)' 역할을 할 수 있음을 보여준다.

4. Sub-agents (서브 에이전트): 격리된 전문 작업자

4.1 정의 및 아키텍처적 역할

Skills가 '조리법'이라면, Sub-agents는 그 조리법을 보고 요리를 수행하는 '전문 셰프(Sous Chef)' 또는 '동료(Coworker)'에 해당한다. Sub-agent의 가장 결정적인 아키텍처적 특징은 독립된 컨텍스트 윈도우(Isolated Context Window)를 가진다는 점이다.

메인 Claude Code 인스턴스가 작업을 Sub-agent에게 위임하면, 시스템은 완전히 분리된 새로운 세션을 생성한다. 이 격리(Isolation)는 다음과 같은 중요한 이점을 제공한다:

• 컨텍스트 오염 방지 (Hygiene): 복잡한 디버깅 작업은 수십 개의 파일을 읽고, 수많은 오류 로그를 생성한다. 이를 메인 세션에서 수행하면 컨텍스트 윈도우가 불필요한 정보로 가득 차게 된다. Sub-agent는 이러한 '지저분한' 작업을 별도 공간에서 수행하고, 최종 결과(요약)만을 메인 에이전트에게 보고한다.
• 역할의 전문화 (Specialization): Sub-agent는 메인 에이전트와 전혀 다른 시스템 프롬프트를 가질 수 있다. 예를 들어, 메인 에이전트는 "친절한 도우미"이지만, Sub-agent는 "공격적인 보안 감사관(Red Teamer)"으로 설정하여 코드의 취약점을 집요하게 공격하게 할 수 있다.
• 토큰 경제성 (Token Economy): 탐색 및 추론 루프를 격리함으로써 메인 대화의 토큰 소비를 줄이고, 초기 지침이 잊혀지는 현상을 방지한다.

4.2 설정 및 수명 주기

Sub-agent는 프로젝트의 .claude/agents/ 디렉토리 또는 글로벌 설정인 ~/.claude/agents/ 디렉토리에 마크다운 파일로 정의된다.

4.2.1 에이전트 정의 파일

security-auditor.md와 같은 파일은 다음과 같은 구성을 가진다:

• name: 위임 시 호출할 이름 (예: security-auditor).
• description: 메인 에이전트가 어떤 상황에서 작업을 이 Sub-agent에게 넘겨야 할지 판단하는 근거가 된다 (예: "코드의 보안 취약점을 점검하거나 OWASP 가이드라인 준수 여부를 확인할 때 사용").
• tools: 해당 Sub-agent가 사용할 수 있는 도구의 집합이다. 예를 들어 Researcher 에이전트에게는 WebSearch와 Read 권한만 부여하고, Write 권한을 박탈하여 실수로 코드를 수정하는 것을 원천 차단할 수 있다.
• skills: 해당 Sub-agent가 초기화될 때 자동으로 로드할 Skills의 목록이다. 이는 Sub-agent가 특정 도메인 지식을 가지고 태어나도록 설정하는 강력한 기능이다.

4.3 Sub-agent의 수명 주기 (Lifecycle): Fork-Join 패턴

Sub-agent의 실행 흐름은 병렬 컴퓨팅의 Fork-Join 모델과 유사하다:

1. 위임 (Delegation): 사용자 또는 메인 에이전트가 하위 작업(예: "이 PR의 보안 문제 점검")을 식별한다.
2. 분기 (Fork): 시스템은 security-auditor Sub-agent를 인스턴스화한다. 이때 새로운 컨텍스트 윈도우가 열린다.
3. 실행 (Execution): Sub-agent는 자신의 루프(생각-행동-관찰)를 돌며 작업을 수행한다. 파일을 읽고, 정적 분석 도구를 실행하고, 웹을 검색한다. 이 과정에서 발생하는 수많은 중간 단계의 생각(Chain of Thought)과 도구 출력은 메인 세션에 기록되지 않는다.
4. 합성 (Synthesis): 작업이 완료되면 Sub-agent는 결과를 요약하여 보고서를 작성한다.
5. 결합 (Join): 작성된 보고서만이 메인 에이전트의 컨텍스트로 반환되며, Sub-agent의 인스턴스는 종료된다.

4.4 Sub-agent의 구체적 예제

예제 A: 코드 리뷰어 (Code Reviewer)

코드 품질을 담당하는 까다로운 리뷰어 에이전트이다.

• 설정: Read, Glob, Grep 도구만 허용. 시스템 프롬프트에 "DRY 원칙, 에러 핸들링, 타입 안정성을 최우선으로 검토하라"는 지침 포함.
• 워크플로우: 개발자가 "내 변경 사항 리뷰해줘"라고 요청하면, 메인 에이전트는 code-reviewer를 호출한다. 이 에이전트는 git diff를 읽고 비판적인 리뷰를 수행한 뒤, 수정해야 할 사항의 목록만을 메인 에이전트에게 전달한다.

예제 B: 심층 연구원 (Deep Researcher)

특정 라이브러리의 사용법이나 에러 해결법을 찾기 위해 웹을 광범위하게 탐색하는 에이전트이다.

• 워크플로우: "이 에러가 왜 발생하는지 찾아줘"라는 요청에 대해, researcher 에이전트는 구글 검색을 수행하고, 10개 이상의 StackOverflow 페이지와 공식 문서를 읽는다. 이 과정에서 발생하는 방대한 텍스트는 메인 컨텍스트를 오염시키지 않으며, 최종적으로 "이 문제는 라이브러리 버전 호환성 때문이며, 해결책은 X입니다"라는 정제된 결론만 반환된다.

예제 C: QA 엔지니어 (QA Engineer)

테스트를 통과할 때까지 코드를 수정하는 자율적인 에이전트이다.

• 자율성: npm test를 실행하고, 실패 로그를 분석한 뒤, 소스 코드를 수정하고 다시 테스트를 실행하는 과정을 반복한다. 이러한 '반복적 수정 루프'는 Sub-agent 아키텍처의 꽃이라 할 수 있으며, 사용자의 개입 없이 문제를 해결한다.

5. 비교 분석: Skills와 Sub-agents의 차이 및 공존

이 두 개념을 명확히 구분하는 것은 효율적인 시스템 설계의 핵심이다. 이들은 상호 배타적이지 않으며, 오히려 상호 보완적인 관계이다.

5.1 주요 차이점 비교표

아래 표는 Skills와 Sub-agents의 기술적, 기능적 차이를 요약한 것이다.

특징	Skills (기술)	Sub-agents (서브 에이전트)
비유	요리책 / 레시피 (Recipe)	보조 셰프 / 동료 (Coworker)
컨텍스트	메인 세션과 공유됨	격리된 독립 세션 (Isolated)
주 목적	지식 및 절차의 확장	작업 위임 및 컨텍스트 격리
호출 방식	상황에 따른 자동 로드 (Opportunistic)	메인 에이전트에 의한 명시적 위임
도구 접근	메인 에이전트의 도구 상속 또는 제한	설정 파일에 명시된 도구만 사용
기억 (Memory)	일회성 (해당 턴에만 로드됨)	세션 기반 (작업 완료 시까지 유지)
비용 (Cost)	낮음 (텍스트 주입 비용)	높음 (별도 에이전트 루프 실행)
적합한 작업	포맷팅, 스타일 준수, 단순 절차 설명	심층 연구, 반복적 디버깅, 대규모 분석

5.2 상호 운용성: 같이 사용 가능 여부

가능하며, 적극적으로 권장된다.

두 컴포넌트의 관계는 계층적이다. Sub-agent는 '실행의 주체'이고, Skills는 '실행을 위한 자원'이다.

• 사전 로딩 (Preloading): Sub-agent 정의 파일의 skills 필드를 통해 특정 Skill을 미리 장착시킬 수 있다. 예를 들어, python-dev라는 Sub-agent를 만들면서 python-style-guide와 error-handling-patterns라는 Skill을 기본적으로 탑재시킬 수 있다.
• 컨텍스트 주입: 초기에는 Sub-agent가 Skills를 사용하지 못한다는 제약이 있었으나, 최신 문서에 따르면 skills 필드를 통해 Sub-agent의 컨텍스트에 도메인 지식을 주입하여 탐색 없이 바로 전문 지식을 활용하게 할 수 있음이 확인되었다.

시나리오: security-auditor Sub-agent(주체)가 초기화될 때 owasp-top-10 Skill(지식)을 로드한다. 이 에이전트는 코드를 분석할 때 Skill에 정의된 체크리스트를 기준으로 취약점을 탐색한다.

6. 에이전트 그래프(Agentic Graph): 그래프 기반 오케스트레이션

사용자의 질문 중 "그래프와 같이 agentic하게 사용하는 방법"은 단순한 요청-응답 모델을 넘어, 에이전트 간의 상호작용을 방향성 비순환 그래프(DAG) 형태로 설계하는 것을 의미한다. 이는 복잡한 문제를 해결하기 위해 에이전트들이 협업하는 구조를 만드는 것이다.

6.1 에이전트 그래프의 개념

그래프 워크플로우에서 각 노드(Node)는 특정 작업을 수행하는 에이전트(또는 Sub-agent)이며, 엣지(Edge)는 데이터의 흐름과 의존성이다. 에이전트 A의 출력이 에이전트 B의 입력이 되는 구조이다. Claude Code는 CLI 기반의 암시적 그래프와 SDK 기반의 명시적 그래프 두 가지 방식을 지원한다.

6.2 CLI 기반의 암시적 그래프 (Natural Language Graph)

Claude Code CLI 환경에서는 사용자가 자연어 명령을 통해 Sub-agent들의 연쇄 작용을 유도할 수 있다.

패턴: 폭포수 검증 그래프 (Waterfall Validation Graph)

1. 노드 1 (계획): 메인 에이전트가 architect Sub-agent를 호출하여 솔루션 계획을 수립한다.
2. 노드 2 (구현): 수립된 계획을 developer Sub-agent에게 전달하여 코드를 작성하게 한다.
3. 노드 3 (검토): 작성된 코드를 reviewer Sub-agent에게 전달한다.
4. 루프 (Loop): 만약 reviewer가 코드를 거부하면, 피드백과 함께 다시 developer 노드로 제어권이 넘어간다.

이 방식에서는 메인 에이전트(와 사용자)가 라우터(Router) 역할을 수행하며, 대화의 흐름 자체가 그래프를 형성한다.

6.3 SDK 기반의 명시적 오케스트레이션 (Programmatic Orchestration)

보다 정교하고 자율적인 그래프를 구축하기 위해서는 Claude Agent SDK (구 Claude Code SDK)를 사용해야 한다. 이를 통해 파이썬 코드로 에이전트 간의 로직(루프, 조건문, 병렬 실행)을 명시적으로 제어할 수 있다.

6.3.1 그래프 설계 예시

SDK를 사용하면 다음과 같은 로직을 구현할 수 있다. 여기서 각 노드는 특정 시스템 프롬프트를 가진 Claude 인스턴스이다.

# Claude Agent SDK를 사용한 에이전트 그래프 의사 코드 (Pseudo-code)

async def release_pipeline_graph(feature_request):
    # 노드 1: 기획자 (Think)
    plan = await planner_agent.think(feature_request)

    # 노드 2: 병렬 실행 (Fan-out) - 프론트엔드와 백엔드 작업을 동시에 수행
    frontend_task = asyncio.create_task(frontend_agent.execute(plan.ui))
    backend_task = asyncio.create_task(backend_agent.execute(plan.api))

    fe_result, be_result = await asyncio.gather(frontend_task, backend_task)

    # 노드 3: 통합 (Fan-in)
    merged_code = await integrator_agent.merge(fe_result, be_result)

    # 노드 4: 검증 및 조건부 분기 (Conditional Edge)
    tests_passed = await qa_agent.verify(merged_code)

    if not tests_passed:
        # 피드백 루프 (Loop back edge)
        return await debugger_agent.fix(merged_code, qa_agent.logs)
    else:
        return merged_code

이러한 프로그래매틱 오케스트레이션(Programmatic Orchestration)은 자연어 프롬프트에 의존하는 것보다 훨씬 더 신뢰성 있고 결정론적인 제어 흐름을 제공한다.

6.4 주요 에이전트 패턴 (Agentic Patterns)

연구 결과, Claude Code를 활용한 몇 가지 효과적인 에이전트 패턴이 식별되었다:

• 마스터-클론 아키텍처 (Master-Clone Architecture): 메인 에이전트가 자신의 복제본(Clone)을 여러 개 생성하여 각기 다른 해결책을 탐색하게 한 뒤, 가장 우수한 결과를 선택하는 방식이다.
• 하이브 마인드 / 스웜 (Hive Mind / Swarm): 전문화된 에이전트들(DB 관리자, UI 디자이너, 로직 핸들러)이 '여왕(Queen)' 또는 '오케스트레이터' 에이전트의 조율 하에 협업하며 합의 알고리즘을 통해 의사결정을 내리는 구조이다.
• 위자드 워크플로우 (Wizard Workflows): 단계별 선형 그래프로, 각 단계(노드)가 끝날 때마다 사용자의 확인을 받고 다음 단계로 넘어가는 방식이다 (계획 -> 승인 -> 코딩 -> 승인 -> 배포).

7. 설정 (Configuration) 및 생태계 구성

Claude Code를 단순한 도구가 아닌 팀의 일원으로 만들기 위해서는 정교한 설정 관리가 필수적이다. 설정은 개인의 선호도와 팀의 규칙을 조화시키는 계층적 구조를 따른다.

7.1 설정의 계층 구조 (Hierarchy)

Claude Code는 설정을 다음 순서로 확인하며, 상위 설정이 하위 설정을 덮어쓴다 (우선순위 높음 -> 낮음):

1. 관리자 설정 (Managed Settings) (managed-settings.json): 엔터프라이즈 수준에서 보안 정책(예: 공용 클라우드 업로드 차단)을 강제할 때 사용한다.
2. 로컬 프로젝트 재정의 (.claude/settings.local.json): 특정 머신이나 개발자 개인을 위한 설정으로, Git에 커밋되지 않는다.
3. 프로젝트 설정 (.claude/settings.json): Git에 커밋되어 팀 전체가 공유하는 설정이다. 권한 관리나 훅 설정이 여기에 포함된다.
4. 사용자 글로벌 설정 (~/.claude/settings.json): 모든 프로젝트에 적용되는 사용자의 개인적인 선호도(테마, 기본 에디터 등)이다.

7.2 CLAUDE.md: 프로젝트의 시스템 프롬프트

CLAUDE.md 파일은 Claude Code 설정의 핵심이다. 이는 JSON 형태의 설정 파일이 아니라, 에이전트가 대화를 시작할 때마다 읽어들이는 지속적 컨텍스트(Persistent Context) 파일이다.

포함해야 할 내용:

• 프로젝트의 고수준 아키텍처
• 자주 사용하는 빌드/테스트 명령어(예: npm test 대신 make test를 써야 함)
• 코딩 스타일 가이드 요약
• "하지 말아야 할 것(Gotchas)"

제외해야 할 내용:

• 에이전트가 파일 시스템을 읽어서 스스로 파악할 수 있는 정보
• 너무 방대한 API 문서. CLAUDE.md가 너무 길면 에이전트가 핵심 지침을 무시할 수 있다.

7.3 MCP (Model Context Protocol) 통합: 외부 세계와의 연결

사용자 질문의 "기타 기능"에 해당하는 중요한 요소가 바로 MCP이다. MCP는 Claude Code를 GitHub, Google Drive, Slack, 데이터베이스 등 외부 시스템과 연결하는 표준 프로토콜이다.

• 설정 방법: .mcp.json 파일이나 글로벌 설정에 MCP 서버를 정의한다.
• 활용: 설정이 완료되면, 에이전트는 query_database나 fetch_github_issue와 같은 도구를 사용할 수 있게 된다.
• 예제: claude mcp add --transport stdio --env API_KEY=xyz airtable... 명령어를 통해 Airtable을 데이터베이스처럼 조회하고 수정할 수 있는 능력을 에이전트에게 부여할 수 있다.

8. Hook (훅): 결정론적 자동화 및 라이프사이클 제어

8.1 정의 및 목적

Hook(훅)은 LLM의 확률적인 본성을 보완하는 결정론적 제어 계층(Deterministic Layer)이다. 이는 Claude Code의 수명 주기(Lifecycle) 중 특정 시점에 자동으로 실행되는 쉘 명령어 또는 스크립트이다.

Skills와 Sub-agents가 '지능'을 담당한다면, Hooks는 '거버넌스(Governance)'와 '안전장치'를 담당한다. 에이전트가 "기억"하는지에 의존하지 않고, 린트(Lint) 검사나 보안 확인과 같은 필수 작업을 강제할 수 있다.

8.2 Hook 이벤트 종류 및 라이프사이클

Claude Code는 다양한 시점에 훅을 트리거할 수 있는 이벤트를 제공한다:

이벤트 (Event)	설명	주요 용도	차단 가능 여부
UserPromptSubmit	사용자가 엔터를 치는 순간 발생	프롬프트 수정, 의도 로깅	가능 (프롬프트 차단)
PreToolUse	에이전트가 도구를 실행하기 직전	보안 정책 시행, 위험 명령어 차단	가능 (실행 차단)
PostToolUse	도구 실행이 완료된 직후	자동 포맷팅, 결과 로깅, 알림	불가능
Stop	에이전트가 응답을 마치려 할 때	작업 완료 조건 검증 (테스트 실행)	가능 (종료 차단)
Notification	시스템이 사용자 입력을 기다릴 때	사운드 재생, 데스크탑 알림	불가능

8.3 Hook 설정 및 사용법

Hook은 settings.json 파일의 "hooks" 키 아래에 정의된다.

8.3.1 기본 구조

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "command": "prettier --write $FILE_PATH"
      }
    ]
  }
}

8.4 고급 Hook 활용 시나리오

시나리오 A: 보안 차단 (The Security Blockade)

에이전트가 .env 파일을 수정하거나 데이터베이스 삭제 명령을 내리는 것을 원천 봉쇄한다.

• 이벤트: PreToolUse
• Matcher: Bash
• 로직: 스크립트가 실행될 명령어를 분석하여 rm -rf나 .env 편집이 포함되어 있으면 종료 코드 1을 반환하고 에러 메시지를 출력한다.
• 결과: Claude는 "Action Blocked by Security Hook"이라는 오류를 받고, 다른 방법을 찾아야 한다.

시나리오 B: "완료 정의" 강제 (The Definition of Done Enforcer)

테스트를 통과하지 않으면 에이전트가 작업을 마칠 수 없게 한다.

• 이벤트: Stop
• 명령어: 프로젝트의 전체 테스트 스위트 실행 (npm test).
• 로직: 테스트가 실패하면 Hook은 "Block" 결정과 함께 실패 로그를 반환한다.
• 결과: Claude는 작업을 종료하려다 실패 메시지를 보고, 스스로 코드를 수정하는 루프로 다시 진입한다. 이는 프롬프트가 아닌 코드로 강제된 자가 수정 루프(Self-Correcting Loop)를 형성한다.

8.5 CI/CD 통합 및 기타 기능

훅과 더불어 Claude Code는 GitHub Actions나 GitLab CI/CD 파이프라인에 통합될 수 있다.

• GitHub Actions: PR에 @claude를 태그하면, Claude가 자동으로 코드를 리뷰하거나 버그를 수정하여 커밋을 푸시하도록 설정할 수 있다. 이를 위해서는 ANTHROPIC_API_KEY와 적절한 권한 설정이 필요하다.
• 비용 관리: 무한 루프에 빠져 API 비용이 과다 청구되는 것을 막기 위해 max_turns 설정이나 예산 알림 기능을 활용해야 한다.

9. 결론 (Conclusion)

Claude Code의 생태계는 단순한 코딩 도구를 넘어, Skills, Sub-agents, Agentic Graphs, Hooks가 유기적으로 결합된 복합 지능 시스템이다.

• Skills는 에이전트에게 '무엇을 어떻게(How-to)' 할지 알려주는 지식의 원천이다.
• Sub-agents는 작업을 병렬로 처리하고 컨텍스트를 격리하여 '확장성(Scale)'을 제공한다.
• Agentic Graphs는 이러한 단위들을 묶어 복잡한 문제를 해결하는 '구조(Structure)'를 만든다.
• Hooks는 에이전트의 행동을 결정론적으로 제어하는 '안전장치(Guardrails)' 역할을 한다.
• MCP는 외부 세계와 소통하는 '감각 기관'이다.

현대의 소프트웨어 아키텍트와 엔지니어링 리더에게 있어, 이 네 가지 요소(Skills, Agents, Graphs, Hooks)를 마스터하는 것은 선택이 아닌 필수이다. 정교하게 작성된 CLAUDE.md, 전문화된 Sub-agents, 그리고 강력한 보안 Hook 정책을 통해, 팀은 Claude Code를 단순한 조수가 아닌 신뢰할 수 있는 자율적인 동료로 격상시킬 수 있을 것이다.