책에 포함된 노트Claude Code 실전 활용법: 설치부터 자동화·MCP·운영까지

Skills·에이전트·서브에이전트: 지식 모듈화와 병렬 작업

2026-03-22Views 24약 8분

Claude Code를 오래 쓰다 보면, 실력의 차이는 "한 번에 잘 쓰는 프롬프트"가 아니라 "컨텍스트를 관리하는 구조"에서 벌어집니다. 컨텍스트가 커질수록 비용이 늘고, 모델이 실제로 활용할 수 있는 유효 정보 비율은 떨어지며, 결국 잡음이 성능을 갉아먹습니다.¹ 그래서 이 챕터의 결론은 단순합니다.

한 에이전트에 다 넣지 마세요. 역할과 컨텍스트를 분리하면 품질이 오릅니다.

이 원칙을 실무에서 구현하는 도구가 바로 Skills(지식/절차 모듈), 에이전트(역할 프롬프트), 서브에이전트(격리된 실행 컨텍스트)입니다.

컨텍스트가 커지면 왜 품질이 떨어질까

에이전트 코딩은 탐색, 실행, 관찰(로그·파일·검색 결과)을 반복합니다. 문제는 이 관찰이 대부분 장문이고, 회차가 늘수록 쌓여서 컨텍스트가 "기억"이 아니라 "소음"이 된다는 점입니다.¹ 게다가 긴 컨텍스트는 단지 비싸기만 한 게 아니라, 잘못된 정보가 섞여 들어오면 이후 모든 판단을 오염시키기도 합니다(컨텍스트 포이즈닝), 정보가 많아져 중요한 단서가 묻히기도 합니다(컨텍스트 디스트랙션).²

이때 해결책은 두 갈래로 나뉩니다.

첫째는 압축(요약/트리밍/마스킹)입니다. 예를 들어 관찰(툴 결과)만 오래된 것부터 숨기거나, 별도 모델이 과거 대화를 요약하는 식입니다.¹

둘째는 격리(isolate)입니다. 작업을 여러 컨텍스트 창으로 나누는 방식인데, 이것이 바로 서브에이전트의 핵심 가치입니다.²

요약하면, "컨텍스트를 늘려 해결"하는 방향은 금방 한계에 부딪힙니다. 대신 반복되는 지식은 모듈로 빼서 재사용하고(Skills), 일회성 탐색/조사는 서브에이전트로 보내서 컨텍스트를 더럽히지 않게 해야 합니다.

Skills: '컨텍스트를 절약하는' 재사용 가능한 절차

Skills는 "특정 작업을 항상 같은 방식으로 수행하게 만드는, 작고 표준화된 지침 패키지"입니다.³ 매번 긴 설명을 채팅에 붙여 넣는 대신, 프로젝트/개인 환경에 저장해 두고 필요할 때만 로드하는 방식이기 때문에 컨텍스트를 절약합니다.

실무 감각으로 말하면, Skills는 아래 둘을 묶어 둔 것입니다.

판단 기준(체크리스트/정책): 무엇을 위험으로 볼지, 어떤 규칙을 우선할지
절차(워크플로): 어떤 순서로 파일을 읽고, 무엇을 검증하고, 어떤 산출물을 남길지

Skills 폴더 구조와 최소 템플릿

Claude Code는 프로젝트/사용자 레벨의 Skills 경로를 관례적으로 찾습니다.³ 보통은 다음 중 하나를 씁니다.

프로젝트: .claude/skills/<skill-name>/
사용자: ~/.claude/skills/<skill-name>/

Skill은 SKILL.md가 사실상 엔트리 포인트입니다.³ 최소 템플릿은 아래처럼 시작합니다.

---
name: webapp-testing
description: 로컬 웹앱의 핵심 플로우를 Playwright로 검증하고 report.md를 생성한다.
---

# Webapp Testing

## When to Use This Skill
- 릴리스 전 회귀 테스트가 필요할 때
- UI 플로우가 간헐적으로 깨진다고 보고됐을 때
- PR에서 프론트엔드 변경이 컸을 때

## Instructions
1) 테스트 대상 URL/환경을 확인한다.
2) 핵심 사용자 여정(로그인/결제/검색 등)을 시나리오로 정의한다.
3) 자동화 실행 후 실패 케이스는 스크린샷/로그를 첨부한다.
4) report.md에 '재현 단계/기대 동작/실제 동작/원인 후보/다음 액션'을 기록한다.

## Examples
- "Webapp Testing skill로 체크아웃 플로우를 검증하고 report.md를 만들어줘."

핵심은 '사용자에게 설명하는 문서'가 아니라 '모델에게 내리는 작업 지시서'라는 점입니다.³

Skill 설계 규칙: 작게, 단단하게

Skills를 잘못 만들면 오히려 컨텍스트가 늘어납니다. 아래 원칙을 추천합니다.

스킬 하나는 "20~30분 안에 끝나는 반복 작업"을 목표로 합니다.
입력(필수 전제)과 출력(산출물 파일/형식)을 고정합니다.
예외 처리를 써 둡니다. 예를 들어 "테스트 실행이 불가능하면, 실행 커맨드 후보 3개를 제시하고 사용자의 선택을 받는다" 같은 규칙이 스킬의 완성도를 올립니다.

서브에이전트: 병렬화보다 중요한 것은 '격리'

서브에이전트는 메인 세션과 독립된 컨텍스트 창에서 한 가지 하위 작업을 수행하고, 결과만 요약해 돌아오는 형태입니다. 즉, 메인 에이전트가 읽기/검색/로그 같은 "지저분한 작업 흔적"을 직접 떠안지 않아도 됩니다.⁴⁵

많은 사람들이 서브에이전트를 "빨리 끝내는 병렬 처리"로만 이해하지만, 더 큰 효용은 컨텍스트 압축입니다. 하위 작업이 파일 8개를 읽고 툴 호출 15번을 해도, 메인에는 몇백 토큰짜리 결과만 남길 수 있습니다.⁶

Anthropic이 공개한 멀티 에이전트 리서치 시스템도 같은 논리를 씁니다. 서브에이전트가 각자 좁은 주제를 병렬로 탐색한 뒤, 리드 에이전트가 결과를 압축해 합칩니다.⁴

언제 서브에이전트를 쓰고, 언제 쓰지 말까

서브에이전트가 항상 정답은 아닙니다. 비용도 늘고(여러 인스턴스가 토큰을 각각 씁니다), 조율도 필요합니다.⁴⁶

아래처럼 나누면 판단이 쉬워집니다.

서브에이전트를 쓰기 좋은 경우
- 조사/탐색이 길어질 것 같다(로그, 많은 파일, 외부 문서)
- 서로 독립인 하위 작업이 2개 이상이다(도메인 분리 가능)
- 보안/권한을 분리해야 한다(외부 검색 전용 등)
메인에서 직접 처리하기 좋은 경우
- 수정할 파일이 명확하다(한두 파일)
- 순차 의존이 강하다(스키마→API→UI처럼 앞 단계가 다음 입력을 만든다)
- 대화형으로 빠르게 왔다 갔다 해야 한다