서브에이전트를 어디에 두어야 하나 — 글로벌·프로젝트·플러그인 배치 전략

서브에이전트 파일을 만들었다면 다음 질문이 온다. 이 파일을 어디에 두어야 하는가? Claude Code는 세 위치를 스캔한다 — 사용자 홈의 전역 디렉토리, 프로젝트의 로컬 디렉토리, 그리고 설치된 플러그인 캐시. 어디에 두느냐에 따라 적용 범위·팀 공유·버전 관리가 달라진다.

Claude Code가 에이전트를 찾는 세 경로

세 위치 모두 스캔되고 통합된다. 같은 name이 여러 위치에 있으면 프로젝트 에이전트가 전역보다 우선한다. 플러그인 에이전트는 설치된 패키지에서 로드된다.

전역 배치 — ~/.claude/agents/

▲ 전역 배치 구조 — 한 곳에 두면 모든 프로젝트에 적용된다

▲ 전역 배치의 장점 — 중앙 관리와 즉시 적용

▲ 전역 배치의 단점 — 팀 공유 불가와 Git 추적 부재

전역은 "어떤 프로젝트에서도 쓰이는 범용 에이전트"에 적합하다. 보안 감사, 기본 코드 리뷰처럼 프로젝트를 가리지 않는 에이전트를 여기에 둔다. 단점은 팀원과의 공유가 자동이 아니라는 것이다.

프로젝트 배치 — .claude/agents/

▲ 프로젝트 배치 구조 — git에 커밋하면 팀원의 pull·clone으로 자동 전파된다

▲ 프로젝트 배치의 장점 — 팀 공유 자동화와 git 히스토리 추적

프로젝트 배치는 팀 공유의 최선이다. git에 커밋하면 팀원이 pull하는 순간 자동으로 에이전트가 생긴다. 별도 설치 명령 없이. 에이전트 변경 이력도 프로젝트 히스토리에 함께 남는다.

플러그인 배치 — /plugin install 후 캐시에 저장

▲ 플러그인 배치 흐름 — install 한 번으로 에이전트·도구가 활성화된다

▲ 플러그인 배치의 장점 — MCP 도구 포함과 버전 관리

▲ 플러그인 배치의 단점 — 구조 복잡성과 수동 업데이트

세 배치 방식 비교

배치 위치 결정 흐름도

MCP 자체는 플러그인 없이도 동작한다. 프로젝트 루트에 .mcp.json을 두면 .claude/agents/의 에이전트가 그 MCP 도구를 호출할 수 있고, 사용자 스코프는 claude mcp add로 등록한다. 플러그인이 답이 되는 시점은 에이전트와 MCP 서버를 한 단위로 묶어 배포할 때다 — /plugin install 한 번에 에이전트·MCP·env가 원자적으로 설치되고, 버전이 묶음째 고정·갱신된다. 혼자 쓰는 프로젝트라면 .mcp.json + .claude/agents/ 조합으로 충분하다.

우선순위 규칙 — 같은 name이 여러 위치에 있을 때

우선순위는 항상 프로젝트 > 전역이다. 이것은 의도적인 설계다. 전역에 범용 에이전트를 두고, 특정 프로젝트에서는 같은 이름으로 더 특화된 버전을 프로젝트 디렉토리에 넣어서 덮어쓸 수 있다. 다른 프로젝트에서는 전역 버전이 그대로 동작한다.

흔한 실수 — 모든 에이전트를 전역에 두기

▲ 흔한 실수의 결과 — 전역에 다 모으면 공유·관리·추적이 모두 깨진다

▲ 권장 전략 — 범위와 배포 시나리오에 맞춰 세 위치를 나눠 쓴다

전역은 정말 모든 프로젝트에서 쓰이는 것만 넣는다. 프로젝트 특화 에이전트까지 전역에 모으면 관리가 복잡해지고 팀 공유가 안 된다. 기준은 간단하다: "이 에이전트를 팀원이 알아야 하는가?" — YES면 프로젝트 디렉토리, NO면 전역.

---

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