Claude Code 서브에이전트의 파일 구성 전체 지도 — 단순 .md부터 플러그인까지

Claude Code에서 서브에이전트를 만들면 어떤 파일이 어떤 경로에 만들어질까? "마크다운 파일 하나"로 끝나는 단순한 경우도 있고, 네 종류의 파일이 특정 디렉토리 구조로 배치된 플러그인 패키지가 되는 경우도 있다. 이 글은 서브에이전트의 파일 구성 전체 지도를 그린다.

두 형태의 갈림길 — 새 도구가 필요한가

갈림길은 단순하다. 기존 Claude Code 기본 도구(Read, Edit, Bash, Grep 등)만으로 충분하면 마크다운 파일 하나로 끝난다. 외부 도구가 필요하면 플러그인 패키지로 키운다.

단독 에이전트 — 파일 하나의 해부

frontmatter가 설정이고 본문이 지시서다. frontmatter가 "이 에이전트를 언제 켜고 어떤 도구를 허용할지"를 정의하고, 시스템 프롬프트가 "켜진 에이전트가 어떻게 생각하고 행동할지"를 정의한다.

플러그인 패키지 — 최대 5개 파일의 구조

▲ 필수 — 플러그인으로 인식되고 동작하려면 plugin.json과 에이전트 마크다운 두 개가 반드시 있어야 한다

▲ 선택사항 — MCP 도구, 슬래시 커맨드, 스킬 문서는 필요할 때 추가한다

필수는 두 개뿐이다. plugin.json과 에이전트 마크다운. 나머지는 필요할 때 추가하는 선택 사항이다. debug-pack 플러그인은 이 5개를 모두 갖춘 가장 완전한 형태의 예시다.

debug-pack 플러그인의 실제 디렉토리 트리

실제 debug-pack 플러그인의 파일 트리다. 이 구조를 참고해서 자신의 플러그인을 만들면 된다. agents/ 안에 여러 개의 에이전트 파일을 넣는 것도 가능하다.

각 파일의 역할과 없을 때의 영향

점진적 성장 경로 — 파일 하나에서 완전한 플러그인으로

처음부터 복잡하게 만들 필요 없다. 마크다운 파일 하나로 시작해서 필요가 생길 때마다 파일을 추가하는 방식이 현실적이다. 각 단계가 이전 단계의 파일을 그대로 유지하면서 파일만 추가하므로, 리팩토링 없이 점진적으로 키울 수 있다.

Claude Code가 파일을 로드하는 순서

스캔 순서가 우선순위를 결정하지 않는다. 같은 name이 여러 위치에 있을 때는 프로젝트 에이전트가 전역 에이전트보다 항상 우선한다. 덕분에 전역에 범용 에이전트를 두고, 특정 프로젝트에서는 같은 이름으로 더 특화된 버전으로 덮어쓰는 전략이 가능하다.

---

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