에이전트를 직접 만들고 싶다면 — Claude Code 개발팀이 알려주는 에이전트 설계의 핵심

개요

AI 에이전트는 단순한 챗봇을 넘어 스스로 판단하고, 도구를 사용하며, 복잡한 작업을 자율적으로 수행하는 시스템이다. Anthropic의 Claude Code 개발팀은 이런 에이전트를 효과적으로 설계하기 위한 실전 가이드라인을 공개했다. 이 글에서는 Claude Code 팀이 실제 개발 경험에서 얻은 에이전트 설계의 핵심 원칙부터 구현 패턴, 커스텀 에이전트 만들기까지 깊이 있게 다룬다.

에이전트의 본질: 컴퓨터를 사용하는 AI

Claude Agent SDK의 핵심 철학은 놀라울 정도로 단순하다. 에이전트에게 컴퓨터를 제공하라. Claude Code 팀은 AI의 지능이 부족한 것이 아니라 맥락(Context)이 부족한 것이 문제라고 본다. 에이전트가 파일을 찾고, 읽고, 수정하고, 실행하고, 디버깅하는 과정을 반복할 수 있게 하면 인간 개발자처럼 문제를 풀어나갈 수 있다.

이 철학에서 에이전트의 동작은 네 단계 피드백 루프로 요약된다.

• 컨텍스트 수집: 파일 시스템 탐색, 검색, bash 스크립트로 필요한 정보 확보
• 행동 실행: 도구 호출, 코드 생성, 외부 서비스 연동으로 실제 작업 수행
• 작업 검증: 린팅, 테스트 실행, 시각적 확인 등으로 결과 품질 확인
• 반복: 검증 결과를 바탕으로 자체 수정 후 다시 루프 진입

이 루프의 핵심은 에이전트가 스스로 언제 멈출지를 결정한다는 점이다. 정해진 횟수만큼 반복하는 것이 아니라, 결과가 충분히 확실해질 때까지 계속 작업한다.

---

3가지 핵심 설계 원칙

Anthropic이 강조하는 에이전트 설계의 3대 원칙은 다음과 같다.

1. 단순성을 유지하라

가장 간단한 방법부터 시작해서 필요할 때만 복잡성을 추가해야 한다. 프레임워크를 쓰기 전에 LLM API를 직접 호출하는 것부터 시도하라. 복잡한 프레임워크 뒤에 숨은 추상화 계층은 프롬프트와 응답의 흐름을 가리고 디버깅을 어렵게 만든다.

성공적인 에이전트 구현은 대부분 단순하고 조합 가능한 패턴을 사용한다. 거대한 프레임워크보다 작은 빌딩 블록의 조합이 더 강력하다.

2. 투명성을 확보하라

에이전트의 계획 수립 과정을 명시적으로 보여줘야 한다. 에이전트가 무엇을 하고 있는지, 왜 그런 결정을 내렸는지를 추적할 수 있어야 문제가 생겼을 때 빠르게 대응할 수 있다.

3. 도구 인터페이스를 정교하게 설계하라

에이전트-컴퓨터 인터페이스(ACI)를 철저하게 설계해야 한다. 도구 설명을 명확하고 상세하게 작성하고, 모델이 자연스럽게 이해할 수 있는 입출력 형식을 선택하라. 도구 설계가 에이전트 성능에 미치는 영향은 프롬프트 엔지니어링만큼 크다.

워크플로우 vs 에이전트: 언제 무엇을 쓸까

Anthropic은 에이전트 시스템을 두 가지로 구분한다.

워크플로우(Workflow)는 LLM과 도구가 미리 정의된 코드 경로를 따라 동작하는 시스템이다. 순서가 정해져 있고, 예측 가능한 결과를 낸다. 잘 정의된 반복 작업에 적합하다.

에이전트(Agent)는 LLM이 자신의 프로세스와 도구 사용을 동적으로 결정하는 시스템이다. 유연하게 상황에 대응하고, 모델 스스로 판단하여 다음 단계를 선택한다. 개방형 문제나 복잡한 의사결정이 필요한 상황에 적합하다.

실무적 판단 기준은 이렇다.

• 정해진 단계로 처리 가능 → 워크플로우 선택
• 상황에 따라 다른 판단 필요 → 에이전트 선택
• 비용과 지연 시간이 중요 → 워크플로우 우선 고려
• 작업 품질이 최우선 → 에이전트로 유연성 확보

---

5가지 아키텍처 패턴

Anthropic이 제시하는 에이전트 시스템의 주요 아키텍처 패턴이다.

프롬프트 체이닝 (Prompt Chaining)

하나의 LLM 호출 결과를 다음 호출의 입력으로 전달하는 순차 구조다. 마케팅 카피 작성 후 번역하는 것처럼 단계별로 나눠 처리할 수 있는 작업에 적합하다.

라우팅 (Routing)

입력을 분류한 뒤 각 카테고리에 맞는 전문화된 처리 경로로 보내는 구조다. 고객 문의를 기술 지원, 환불, 일반 상담으로 분류하여 각각 다른 에이전트가 처리하는 방식이다.

병렬화 (Parallelization)

여러 LLM 호출을 동시에 실행하여 속도와 정확도를 모두 높이는 구조다. 코드 리뷰 시 보안, 성능, 가독성을 동시에 검토하는 방식이 대표적이다.

오케스트레이터-워커 (Orchestrator-Worker)

중앙 오케스트레이터가 작업을 동적으로 분할하여 여러 워커에게 배분하는 구조다. 여러 파일에 걸친 대규모 코딩 작업에 효과적이다.

평가자-최적화자 (Evaluator-Optimizer)

하나의 모델이 결과를 생성하고, 다른 모델이 평가하여 피드백을 제공하는 반복 구조다. 번역이나 글쓰기처럼 품질을 점진적으로 높여야 하는 작업에 적합하다.

Claude Code 서브에이전트: 실전 구현 가이드

Claude Code에서 커스텀 에이전트를 만드는 가장 직접적인 방법은 서브에이전트를 정의하는 것이다. 서브에이전트는 독립된 컨텍스트 윈도우에서 동작하는 전문화된 AI 어시스턴트다.

서브에이전트가 필요한 이유

• 컨텍스트 보존: 탐색이나 분석 결과가 메인 대화의 맥락을 오염시키지 않는다
• 도구 제한: 리뷰어에게는 읽기 전용 도구만 부여하는 식으로 권한을 분리할 수 있다
• 재사용: 한 번 만든 에이전트를 여러 프로젝트에서 활용할 수 있다
• 비용 제어: 단순 작업은 Haiku 같은 빠르고 저렴한 모델로 라우팅할 수 있다

에이전트 파일 구조

서브에이전트는 YAML 프론트매터가 포함된 마크다운 파일로 정의한다. .claude/agents/ 디렉토리에 저장하면 프로젝트 전체에서 사용할 수 있고, ~/.claude/agents/에 저장하면 모든 프로젝트에서 사용할 수 있다.

---
name: code-reviewer
description: 코드 품질과 보안을 검토하는 전문 리뷰어
tools: Read, Glob, Grep
model: sonnet
---

코드를 분석하여 품질, 보안, 유지보수성에 대한
구체적이고 실행 가능한 피드백을 제공하세요.

주요 설정 필드

• name: 소문자와 하이픈으로 구성된 고유 식별자
• description: 에이전트가 언제 위임받을지 결정하는 설명문
• tools: 사용할 수 있는 도구 목록 (생략하면 모든 도구 상속)
• model: 사용할 모델 (sonnet, opus, haiku, inherit)
• memory: 세션 간 영구 메모리 범위 (user, project, local)
• permissionMode: 권한 모드 (default, acceptEdits, dontAsk 등)
• maxTurns: 최대 에이전트 턴 수
• skills: 시작 시 주입할 스킬 목록
• hooks: 에이전트 전용 라이프사이클 훅

---

도구 스코핑: 역할에 맞는 권한 부여

서브에이전트의 강점은 역할에 따라 도구 접근을 세밀하게 제어할 수 있다는 점이다.

읽기 전용 에이전트 (리뷰어, 감사자)에게는 Read, Grep, Glob만 부여한다.

tools: Read, Grep, Glob

리서치 에이전트에게는 웹 검색 기능을 추가한다.

tools: Read, Grep, Glob, WebFetch, WebSearch

코드 작성 에이전트에게는 편집 도구를 포함한다.

tools: Read, Write, Edit, Bash, Glob, Grep

특정 도구를 차단하려면 disallowedTools를 사용한다.

disallowedTools: Write, Edit

---

실전 에이전트 예시

코드 리뷰어

읽기 전용으로 동작하면서 최근 변경사항을 분석하고 우선순위별 피드백을 제공하는 에이전트다.

---
name: code-reviewer
description: 코드 변경사항의 품질과 보안을 검토합니다
tools: Read, Grep, Glob, Bash
model: inherit
---

시니어 코드 리뷰어로서 코드 품질과 보안 표준을 검토합니다.

호출 시:
1. git diff로 최근 변경사항 확인
2. 수정된 파일에 집중
3. 즉시 리뷰 시작

피드백은 우선순위별로 정리:
- 치명적 이슈 (반드시 수정)
- 경고 (수정 권장)
- 제안 (개선 고려)

디버거

오류 분석부터 수정, 검증까지 전 과정을 자율적으로 수행하는 에이전트다.

---
name: debugger
description: 오류, 테스트 실패, 비정상 동작을 진단하고 수정합니다
tools: Read, Edit, Bash, Grep, Glob
---

근본 원인 분석에 전문화된 디버거입니다.

호출 시:
1. 에러 메시지와 스택 트레이스 수집
2. 재현 단계 식별
3. 실패 지점 격리
4. 최소한의 수정 적용
5. 해결 검증

---

영구 메모리: 에이전트의 학습 능력

memory 필드를 설정하면 에이전트가 세션 간에 학습 내용을 축적할 수 있다. 코드베이스 패턴, 디버깅 인사이트, 아키텍처 결정 사항 등을 기억하고 점점 더 효과적으로 동작한다.

---
name: code-reviewer
description: 코드 품질과 보안을 검토합니다
memory: user
---

메모리 범위는 세 가지다.

• user: 모든 프로젝트에서 공유되는 학습 내용 (~/.claude/agent-memory/)
• project: 특정 프로젝트에 한정된 지식, 버전 관리 가능 (.claude/agent-memory/)
• local: 프로젝트 한정이지만 버전 관리에 포함하지 않는 지식 (.claude/agent-memory-local/)

메모리를 활용하는 팁은 다음과 같다.

• 작업 시작 전에 메모리를 참조하도록 요청한다
• 작업 완료 후에 배운 내용을 메모리에 저장하도록 요청한다
• 에이전트 프롬프트에 메모리 관리 지침을 직접 포함한다

---

Agent Skills: 점진적 정보 공개

Claude Code의 Skills 시스템은 에이전트에게 도메인 지식을 주입하는 메커니즘이다. 핵심 원칙은 점진적 정보 공개(Progressive Disclosure)로, 잘 정리된 설명서의 목차처럼 필요할 때만 정보를 로드한다.

스킬은 3계층 구조로 설계된다.

• 메타데이터 계층: YAML 프론트매터의 name과 description으로 사용 시점 판단
• 핵심 설명 계층: SKILL.md 본문에 담긴 주요 지침
• 상세 참조 계층: 특정 상황에서만 필요한 추가 파일들

서브에이전트에 스킬을 미리 로드하려면 skills 필드를 사용한다.

---
name: api-developer
description: API 엔드포인트를 팀 컨벤션에 맞게 구현합니다
skills:
  - api-conventions
  - error-handling-patterns
---

---

서브에이전트 실행 패턴

순차 체이닝

하나의 서브에이전트 결과를 다음 서브에이전트에 전달하는 파이프라인 구조다.

코드 리뷰어 → 성능 최적화 에이전트 → 테스트 에이전트

병렬 리서치

독립적인 조사를 여러 서브에이전트에 동시에 맡기는 구조다. 인증 모듈, 데이터베이스 모듈, API 모듈을 각각 별도 에이전트가 탐색한 뒤 메인 에이전트가 결과를 종합한다.

포그라운드 vs 백그라운드

• 포그라운드: 서브에이전트 완료까지 메인 대화가 대기. 사용자 승인이 필요한 작업에 적합
• 백그라운드: 메인 대화를 계속하면서 서브에이전트가 병렬로 작업. 독립적인 작업에 적합

---

Hooks: 에이전트의 안전장치

Hooks는 서브에이전트의 도구 실행 전후에 검증 로직을 삽입하는 메커니즘이다. 단순한 도구 제한을 넘어 조건부 규칙을 적용할 수 있다.

예를 들어, 데이터베이스 에이전트에게 Bash 접근을 허용하되 SELECT 쿼리만 실행하도록 제한할 수 있다.

---
name: db-reader
description: 읽기 전용 데이터베이스 쿼리 실행
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

검증 스크립트는 JSON으로 전달된 명령을 분석하여 INSERT, UPDATE, DELETE 같은 쓰기 작업을 차단하고 SELECT만 허용한다. 이렇게 하면 에이전트에게 유연한 도구 접근을 허용하면서도 안전 범위를 벗어나지 않도록 보장할 수 있다.

---

에이전트 개선을 위한 디버깅 체크리스트

에이전트가 기대대로 동작하지 않을 때 확인해야 할 사항이다.

• 작업을 잘못 이해할 때: 검색 API나 도구 설명을 개선하여 필요한 정보에 더 쉽게 접근하게 한다
• 같은 실수를 반복할 때: 도구 호출에 형식적 규칙이나 검증을 추가한다
• 자체 수정이 안 될 때: 더 다양한 도구를 제공하여 대안을 시도할 수 있게 한다
• 성능이 불안정할 때: 실제 사용 패턴을 기반으로 테스트 세트를 구축한다

에이전트 개발은 반복적인 과정이다. 처음부터 완벽한 에이전트를 만드는 것이 아니라, 실패에서 배우며 점진적으로 개선하는 것이 핵심이다.

---

마무리

Claude Code 개발팀이 강조하는 에이전트 설계의 핵심은 결국 단순함에서 시작하여 필요에 따라 확장하라는 것이다. 화려한 프레임워크나 복잡한 아키텍처보다 명확한 도구 설계, 적절한 권한 분리, 그리고 피드백 루프가 더 중요하다. 서브에이전트와 스킬 시스템을 활용하면 각 역할에 특화된 에이전트를 만들고, 이들을 조합하여 복잡한 워크플로우를 자동화할 수 있다. 직접 에이전트를 만들어 보면서 자신의 프로젝트에 맞는 설계 패턴을 찾아보자.

---

참고 자료

• Building agents with the Claude Agent SDK
• Building Effective AI Agents - Anthropic
• Create custom subagents - Claude Code Docs
• Equipping agents for the real world with Agent Skills
• Agent SDK overview - Claude API Docs
• How Claude Code works - Claude Code Docs

이 글은 Claude Code를 활용하여 작성되었습니다.