/agents 명령어로 에이전트 생성하기

VS Code에서 클로드 코드를 열고 /agents를 입력합니다. 그런데 화면에 안내 메시지가 뜹니다. "터미널에서 계속 진행하세요." IDE 확장 프로그램의 한계 때문에, 일부 슬래시 명령은 터미널에서만 실행됩니다. 큰 문제는 아닙니다. 터미널을 열면 명령이 바로 실행되고, 보조 에이전트 관리 화면이 나타납니다.

이 화면에서 할 수 있는 일은 명확합니다.

현재 프로젝트에 등록된 모든 에이전트를 조회할 수 있습니다. 프로젝트 에이전트와 빌트인 에이전트가 구분되어 표시됩니다. 기존 에이전트를 선택해서 편집하거나 삭제할 수 있습니다. 그리고 새 에이전트를 생성할 수 있습니다.

"Create new agent"를 선택하면, 클로드 코드가 대화형으로 에이전트 구성을 안내합니다. 여기서 두 가지 선택지가 주어집니다. 수동으로 직접 구성하는 방법과, 클로드에게 생성을 맡기는 방법입니다.

클로드에게 맡기는 방법을 선택하면, 우리가 해야 할 일은 이 에이전트가 무엇을 해야 하고, 언제 호출되어야 하는지를 자연어로 설명하는 것뿐입니다. 설명이 구체적이고 포괄적일수록 결과가 좋습니다.

프로젝트 에이전트로 만들지, 개인(글로벌) 에이전트로 만들지도 이 단계에서 결정합니다. 프로젝트 에이전트는 해당 프로젝트의 .claude/agents/ 폴더에 저장되어, 그 프로젝트에서만 사용 가능합니다. 개인 에이전트는 홈 디렉토리의 글로벌 클로드 코드 설정에 저장되어, 어떤 프로젝트에서든 사용할 수 있습니다.

임시 에이전트(Temporary Agent)라는 선택지도 존재합니다. 세션 한정으로 생성했다가 사라지는 에이전트인데, 실제 활용 빈도가 낮으므로 깊이 다루지는 않겠습니다.

[그림 25-1] /agents 명령어 실행 화면: 프로젝트 에이전트 목록과 빌트인 에이전트 목록이 구분되어 표시된 터미널 스크린샷]

한 가지 실전 팁이 있습니다. 에이전트를 생성할 때 "해당 폴더가 이미 존재한다"는 오류가 발생하는 경우가 있습니다. 이 경우 기존 agents 폴더의 이름을 임시로 변경한 뒤 에이전트를 생성하고, 기존 에이전트들을 새 폴더로 옮긴 다음 이전 폴더를 삭제하면 해결됩니다. 알려진 버그이지만, 기능에는 영향이 없습니다.

YAML 메타데이터 구성

보조 에이전트의 정체는 마크다운 파일 하나입니다. 이 사실을 이해하면 개념이 한결 명료해집니다. 스킬이 마크다운 파일이듯, 보조 에이전트 역시 마크다운 파일입니다.

파일의 구조는 두 부분으로 나뉩니다. 상단의 YAML 프론트매터(Front Matter)와 하단의 본문 지시사항입니다.

YAML 프론트매터에 들어가는 주요 필드를 살펴보겠습니다.

name: "AI Trend Hunter"

description: "AI 트렌드를 추적하고 콘텐츠 아이디어를 발굴하는 에이전트. 최신 AI 동향을 조사하고 영상 기획에 활용할 수 있는 시그널을 찾아냅니다."

tools: ["all"]

model: "sonnet"

memory: true

color: "cyan"

name은 에이전트의 식별자입니다. 메인 세션이 이 이름으로 보조 에이전트를 참조합니다.

description은 에이전트의 호출 조건을 결정하는 핵심 필드입니다. 메인 세션은 사용자의 요청을 받으면, 등록된 에이전트들의 설명문을 훑어보며 어떤 에이전트에게 위임할지 판단합니다. 스킬의 설명문이 트리거 정확도를 결정하는 것과 동일한 원리입니다. 설명문이 모호하면 잘못된 에이전트가 호출되고, 설명문이 구체적이면 정확한 위임이 이루어집니다.

tools는 이 에이전트가 사용할 수 있는 도구 세트를 지정합니다. "all"로 모든 도구를 허용할 수도 있고, "read-only" 같은 제한을 걸 수도 있습니다. disallowed_tools 필드로 특정 도구를 명시적으로 차단하는 것도 가능합니다.

model은 보조 에이전트가 사용할 언어 모델을 결정합니다. 메인 세션과 다른 모델을 지정할 수 있다는 점이 보조 에이전트의 핵심 강점 중 하나입니다. 빠른 탐색 작업에는 하이쿠를, 코드 생성에는 소네트를, 복잡한 추론에는 오퍼스를 배정하는 식으로 비용과 품질을 조율합니다.

memory를 활성화하면, 보조 에이전트는 자신의 작업 이력을 agent-memory 폴더에 기록합니다. 이 부분은 뒤에서 별도로 다루겠습니다.

color는 터미널에서 이 에이전트가 실행 중일 때 표시되는 색상입니다. 여러 보조 에이전트가 동시에 돌아갈 때 시각적으로 구분하는 데 도움이 됩니다. IDE 확장 프로그램에서는 보이지 않고, 터미널에서만 확인할 수 있습니다.

이 밖에도 permission_mode, max_turns, auto_compact 등 지원되는 프론트매터 필드가 더 있습니다. auto_compact의 기본값은 약 95%인데, 이 비율을 낮추면 보조 에이전트 내부의 컨텍스트 부패를 더 적극적으로 방지할 수 있습니다.

[표 24-1] 주요 YAML 프론트매터 필드

YAML 프론트매터 아래에는 본문이 이어집니다. 본문은 보조 에이전트가 깨어났을 때 참조하는 시스템 프롬프트입니다. 메인 세션이 "이 에이전트를 사용하겠다"고 결정한 뒤, 에이전트가 실제로 작업을 시작할 때 읽어 들이는 지시사항의 전문입니다.

AI 트렌드 헌터 에이전트 라이브 구축

개념을 손에 잡히는 실습으로 옮겨 보겠습니다. 여기서는 "AI 트렌드 헌터"라는 보조 에이전트를 처음부터 끝까지 만드는 과정을 따라갑니다.

터미널에서 /agents를 실행하고 "Create new agent"를 선택합니다. 프로젝트 에이전트로 생성하고, 클로드에게 자동 생성을 맡깁니다.

이 에이전트가 무엇을 해야 하는지 설명합니다. "최신 AI 트렌드를 추적하고, 콘텐츠로 만들 만한 주제를 발굴하는 에이전트. 퍼플렉시티(Perplexity) API와 X(구 트위터)를 활용해 트렌드 시그널을 수집하고, 영상 기획에 활용할 수 있는 형태로 정리한다." 설명은 더 구체적일수록 좋고, 나중에 언제든 수정할 수 있으니 완벽할 필요는 없습니다.

클로드 코드가 에이전트를 생성하기 시작합니다. 이 과정에서 주목할 점이 있습니다. 클로드 코드는 에이전트 설명만으로 마크다운 파일을 만드는 것이 아니라, 현재 프로젝트의 구조와 내용을 참조하여 에이전트를 맞춤 구성합니다. 유튜브 채널을 운영하고 있고, 클로드 코드와 자동화에 관한 콘텐츠를 만드는 프로젝트라면, 에이전트의 시스템 프롬프트에 그 맥락이 반영됩니다.

생성 과정에서 몇 가지 선택을 내려야 합니다.

도구 선택: 이 에이전트가 사용할 수 있는 도구를 지정합니다. "all"을 선택하면 모든 도구를 사용할 수 있고, "read-only"와 "MCP"만 선택하면 파일 읽기와 MCP 연결 서버 호출만 허용됩니다. 리서치 에이전트에게 파일 수정 권한을 줄 필요가 있을까요? 이 질문을 스스로에게 던지는 것이 제약 적용의 시작입니다.

모델 선택: 소네트를 선택합니다. 트렌드 리서치는 방대한 정보를 빠르게 훑어야 하므로, 오퍼스의 깊은 추론보다는 소네트의 속도가 더 적합한 용도입니다.

색상 선택: 터미널에서 이 에이전트를 시각적으로 식별하기 위한 색상을 고릅니다.

메모리 설정: "Enable"을 선택합니다. 이 설정의 의미는 다음 절에서 자세히 다룹니다.

생성이 완료되면, .claude/agents/ 폴더에 마크다운 파일이 생성됩니다. 파일을 열어보면 YAML 프론트매터에 이름, 설명, 도구, 모델, 메모리, 색상이 설정되어 있고, 본문에는 "당신은 엘리트 AI 트렌드 헌터입니다"로 시작하는 시스템 프롬프트가 작성되어 있습니다. 미션, 수색 대상, 메모리 활용법, 과거 컨텍스트 검색 방법까지 포함되어 있습니다.

[그림 25-2] 생성된 AI 트렌드 헌터 에이전트의 마크다운 파일 구조: YAML 프론트매터와 시스템 프롬프트 본문]

이제 이 에이전트를 실행해 봅니다. 터미널에서 메인 세션에게 "AI 트렌드 헌터를 실행해줘"라고 요청하면, 메인 세션은 등록된 에이전트의 설명문을 참조하여 AI 트렌드 헌터를 호출합니다. 터미널에서 에이전트가 동작하는 모습이 보입니다. 웹 검색을 수행하고, 정보를 수집하고, 분석을 진행합니다.

실행 중에 Ctrl+O를 누르면 에이전트의 사고 과정을 펼쳐 볼 수 있습니다. 메인 세션이 이 보조 에이전트에게 어떤 프롬프트를 보냈는지도 확인할 수 있습니다. Ctrl+B를 누르면 에이전트를 배경으로 보내서, 메인 세션과 대화를 이어가면서 보조 에이전트의 완료를 기다릴 수 있습니다.

실행이 끝나면, 결과가 메인 세션으로 돌아옵니다. 핫 시그널(Hot Signal), 웜 시그널(Warm Signal), 추천 영상 아이디어, 핵심 패턴 등이 정리된 보고서입니다.

한 가지 점검해 볼 사항이 있습니다. 생성된 에이전트의 설명문이 너무 길 수 있습니다. 설명문이 지나치게 길면 모델이 세는 글 조각을 낭비하게 됩니다. 반면 호출 정확도는 높아질 수 있으므로, 적절한 균형을 찾아야 합니다.

에이전트 빌더 스킬(Agent Builder Skill) 같은 도구를 사용해 감사(Audit)를 돌리면, 도구 제한 미설정, 최대 턴 미설정, 설명문 비대화 같은 문제를 자동으로 탐지할 수 있습니다.

에이전트 메모리

AI 트렌드 헌터를 처음 실행하기 전에 agent-memory 폴더를 열어보면, AI 트렌드 헌터용 폴더는 있지만 안에 파일이 없습니다. 메모리 파일은 에이전트를 최초 실행한 후에 자동 생성됩니다.

첫 실행이 완료되면, agent-memory/ai-trend-hunter/ 폴더 안에 메모리 파일이 생깁니다. 이 파일에는 무엇이 담겨 있을까요?

• 유용했던 정보 소스 목록
• 반복적으로 등장하는 주제 패턴
• 효과적이었던 영상 기획 방향
• 가장 최근 스캔 결과의 요약

보조 에이전트는 매번 완전히 새로운 컨텍스트에서 깨어납니다. 대화 기록이 없고, 이전 세션의 기억이 없습니다. 하지만 메모리 파일이 있으면 사정이 달라집니다. 깨어난 보조 에이전트는 메모리 파일을 읽어서, 과거의 학습 내용을 참조할 수 있습니다. 완전한 기억은 아니지만, "지난번에 이 소스가 유용했다", "이 주제는 이미 다루었다" 정도의 맥락은 유지됩니다.

[그림 25-3] 에이전트 메모리의 작동 흐름: 첫 실행 → 메모리 파일 자동 생성 → 이후 실행 시 메모리 파일 참조 → 작업 후 메모리 파일 업데이트]

이 구조 덕분에 트렌드 리서치 에이전트가 2시간 전에 이미 보고한 내용을 다시 보고하는 사태를 방지할 수 있습니다. 메모리에 "최근 스캔" 정보가 남아 있으니, 중복을 피하고 새로운 시그널에 집중합니다.

메모리는 보조 에이전트가 세션을 넘어 학습을 축적해 나가는 메커니즘입니다. 사용할수록 좋아지는 에이전트를 만들고 싶다면, 메모리를 활성화하는 것이 출발점입니다.

보조 에이전트로 메인 맥락 지키기

보조 에이전트의 컨텍스트 보존 효과를 수치로 확인해 보겠습니다.

AI 트렌드 헌터 에이전트가 실행을 마쳤습니다. 이 에이전트는 웹을 검색하고, 소스를 분석하고, 시그널을 분류하고, 보고서를 작성하는 과정에서 약 40,000모델이 세는 글 조각을 소비했습니다.

이제 메인 세션에서 /context 명령을 실행해 봅니다. 메인 세션의 현재 컨텍스트 사용량은 29,000모델이 세는 글 조각입니다.

이 숫자가 의미하는 바를 곱씹어 보겠습니다. 만약 보조 에이전트 없이 메인 세션에서 동일한 리서치를 직접 수행했다면, 메인 세션의 컨텍스트에 40,000모델이 세는 글 조각 이상이 추가되었을 것입니다. 기존 대화와 합산하면, 한 번에 읽는 범위의 상당 부분이 리서치 결과로 채워집니다. 이후 다른 작업—코드 리뷰, 문서 작성, 디버깅—을 할 때 사용 가능한 컨텍스트가 줄어듭니다.

보조 에이전트를 사용하면, 40,000모델이 세는 글 조각 분량의 작업이 별도의 컨텍스트에서 처리됩니다. 메인 세션에는 핫 시그널, 웜 시그널, 추천 아이디어 같은 요약만 전달됩니다. 메인 세션의 컨텍스트는 깨끗하게 보존됩니다.

[그림 25-4] 컨텍스트 보존 효과 비교: 직접 처리 시 메인 세션 69,000+ 모델이 세는 글 조각 vs 보조 에이전트 위임 시 메인 세션 29,000모델이 세는 글 조각]

이것이 보조 에이전트를 사용하는 가장 실질적인 이유 중 하나입니다. 한 번에 읽는 범위는 유한한 자원이고, 보조 에이전트는 그 자원을 보호하는 방벽입니다.

클로드 코드의 빌트인 보조 에이전트

커스텀 보조 에이전트를 만들기 전에, 클로드 코드가 기본으로 탑재하고 있는 보조 에이전트들이 있습니다. 클로드 코드를 사용하면서 터미널에 "agent"라는 표시가 나타난 적이 있다면, 이 빌트인 보조 에이전트를 만난 것입니다.

탐색 에이전트(Explore)는 코드 베이스를 검색하고 분석합니다. 하이쿠 모델로 실행되며, 읽기 전용 권한만 갖습니다. 비용이 낮고 빠른 대신, 파일을 수정하거나 코드를 생성하지는 못합니다. 코드 베이스의 구조를 파악하거나, 특정 패턴을 찾아낼 때 자동으로 호출됩니다.

계획 에이전트(Planning)는 리서치를 수행하고 계획을 수립합니다. 부모 모델의 모델을 그대로 상속받습니다. 메인 세션이 오퍼스로 돌아가고 있다면, 계획 에이전트도 오퍼스로 실행됩니다. 읽기 전용 권한을 가지며, 계획 모드(Plan Mode)에서 이 에이전트가 호출되는 것을 자주 볼 수 있습니다.

일반 에이전트(General)는 다단계 작업이 필요할 때 호출됩니다. 부모 모델을 상속받으며, 모든 도구를 사용할 수 있습니다. 앞의 두 에이전트와 달리 파일을 수정하고, 명령을 실행하고, 코드를 생성할 수 있습니다.

[표 24-2] 빌트인 보조 에이전트 비교

클로드 코드의 핵심 개발자 중 한 명이 직접 사용하는 커스텀 보조 에이전트 목록을 공개한 적이 있습니다. 구축 검증기(Build Validator), 코드 아키텍트(Code Architect), 코드 단순화기(Code Simplifier), 온콜 가이드(On-call Guide), 앱 검증기(Verify App).

클로드 코드를 만든 사람이 자신의 도구에 이렇게 다양한 보조 에이전트를 운용하고 있다는 사실 자체가, 보조 에이전트의 실용적 가치를 증명합니다.

클로드 코드 공식 문서에도 보조 에이전트 예시가 공개되어 있습니다. 코드 리뷰어(Code Reviewer), 디버거(Debugger), 데이터 과학자(Data Scientist), 데이터베이스 쿼리 검증기(Database Query Validator) 등의 전체 마크다운 구성을 확인할 수 있으니, 자신만의 보조 에이전트를 설계할 때 참고할 만합니다.

보조 에이전트를 구축하고 운용하는 실전 기술을 익혔습니다. 한 가지 확인해야 할 사실이 남아 있습니다. 보조 에이전트는 메인 세션의 지시를 받아 독립적으로 작업하고, 결과를 돌려보내는 단방향 구조입니다. 그렇다면 에이전트들이 서로 대화하고, 서로에게 작업을 할당하고, 공유된 목표를 향해 협력하는 구조는 어떤 모습일까요?