Claude Code에서 /agents로 서브에이전트를 만드는 가장 쉬운 방법

Claude Code에서 서브에이전트를 만드는 방법은 두 가지다. 하나는 텍스트 에디터로 마크다운 파일을 직접 작성하는 방법이고, 다른 하나는 /agents 명령어로 대화형 UI를 열어 만드는 방법이다. 파일을 직접 작성하는 방식이 더 세밀한 제어가 가능하지만, 처음 만들어 보거나 빠르게 프로토타입을 만들 때는 /agents UI가 훨씬 빠르다.

서브에이전트란 무엇인가 — 팀장이 팀원에게 위임하는 구조

서브에이전트는 메인 Claude가 특정 작업을 위임하는 전문화된 AI 조수다. 팀장(메인 Claude)이 "보안 감사는 보안팀한테 맡겨"라고 결정하면, 보안팀(서브에이전트)이 독립된 컨텍스트에서 작업하고 결과 요약만 돌려보낸다.

메인 Claude가 두 서브에이전트에게 작업을 동시에 위임한다. 독립 컨텍스트에서 돌아가므로 방대한 분석 결과가 메인 대화를 채우지 않는다. 작업이 끝나면 결과 요약만 메인으로 전달된다.

/agents 명령어 — UI 진입부터 저장까지

전체 흐름은 6단계다. UI 진입 → 탭 선택 → 저장 범위 결정 → 생성 방식 선택 → 내용 작성/수정 → 저장. 저장 즉시 파일이 생기고 Claude Code가 인식한다. 재시작 불필요.

Personal vs Project — 저장 범위 비교

▲ Personal — 내 모든 프로젝트에 적용되는 범용 에이전트

▲ Project — 특정 프로젝트에서만 보이고 git으로 팀과 공유되는 에이전트

Personal은 내 모든 프로젝트에 적용되는 범용 에이전트용이고, Project는 특정 프로젝트의 도메인 지식이 담긴 에이전트용이다. 팀 공유가 목적이라면 반드시 Project를 선택해야 한다.

Generate with Claude — AI가 초안을 쓰는 흐름

Generate with Claude는 대화형으로 초안을 완성한다. Claude가 역할 설명을 듣고 frontmatter와 시스템 프롬프트를 모두 제안한다. 마음에 들 때까지 "tools에 Grep 추가해줘", "시스템 프롬프트를 더 구체적으로" 식으로 수정을 요청하면 된다.

생성 결과 — 파일이 만들어지는 위치

파일이 생기는 즉시 에이전트가 활성화된다. Claude Code가 두 경로를 시작 시 자동으로 스캔하기 때문에 재시작도 불필요하다.

에이전트를 호출하는 세 가지 방법

▲ 방법 1: 자동 위임 — description 트리거를 보고 메인 Claude가 스스로 호출

▲ 방법 2: 명시적 호출 — @이름으로 직접 지목

▲ 방법 3: CLI 플래그 — 세션 전체를 해당 에이전트로 시작

세 방법 중 자동 위임이 가장 자연스럽다. description 필드에 "언제 쓰라"는 트리거 조건을 명확히 적어 두면, 메인 Claude가 상황을 보고 스스로 판단해서 에이전트를 호출한다. 이 자동 위임이 잘 작동하려면 description 작성이 핵심이다.

/agents UI vs 파일 직접 작성 — 언제 무엇을 쓸까

UI와 파일 편집은 배타적이지 않다. UI로 초안을 만들고, 저장된 파일을 에디터로 열어서 MCP 도구 추가나 세밀한 프롬프트 조정을 하는 흐름이 가장 실용적이다.

---

이 글은 생성형 AI의 도움을 받아 작성되었습니다. 원본 자료를 기반으로 AI가 초안을 생성하고, 작성자가 검토·편집하였습니다.